prikke

API Reference

Base URL: https://api.prikke.io

Authentication

All API requests require an API key. Include it in the Authorization header:

Authorization: Bearer pk_live_xxx.sk_live_yyy

Declarative API

Prikke supports a declarative, idempotent API. Push your entire configuration in one call and get back what changed. Perfect for infrastructure-as-code workflows.

PUT /sync

Sync your entire project configuration. This is idempotent - safe to call repeatedly with the same config.

Request Body

Field	Type	Description
`jobs`	array	Array of job configurations
`jobs[].key`	string	Unique key for this job (your identifier)
`jobs[].name`	string	Display name for this job
`jobs[].url`	string	The URL to call
`jobs[].method`	string	HTTP method: GET or POST (default: POST)
`jobs[].cron`	string	Cron expression for recurring jobs
`jobs[].headers`	object	Custom headers to send (optional)
`jobs[].body`	string	Request body for POST requests (optional)
`notifications`	object	Notification settings (optional)
`delete_removed`	boolean	Delete jobs not in this config (default: false)

Example

curl -X PUT https://api.prikke.io/sync \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {
        "key": "daily-backup",
        "name": "Daily backup",
        "url": "https://myapp.com/api/backup",
        "cron": "0 6 * * *"
      },
      {
        "key": "hourly-sync",
        "name": "Hourly sync",
        "url": "https://myapp.com/api/sync",
        "cron": "0 * * * *",
        "headers": {
          "Authorization": "Bearer my-app-token"
        }
      }
    ],
    "notifications": {
      "email": "alerts@myapp.com",
      "webhook_url": "https://hooks.slack.com/services/xxx"
    },
    "delete_removed": true
  }'

Response

{
  "created": ["daily-backup"],
  "updated": ["hourly-sync"],
  "deleted": ["old-job"],
  "unchanged": [],
  "jobs": [
    {
      "id": "job_abc123",
      "key": "daily-backup",
      "name": "Daily backup",
      "url": "https://myapp.com/api/backup",
      "cron": "0 6 * * *"
    },
    {
      "id": "job_def456",
      "key": "hourly-sync",
      "name": "Hourly sync",
      "url": "https://myapp.com/api/sync",
      "cron": "0 * * * *"
    }
  ],
  "notifications": {
    "email": "alerts@myapp.com",
    "webhook_url": "https://hooks.slack.com/services/xxx"
  }
}

Tip: Store your config in version control and sync on deploy. The key field is your stable identifier - Prikke uses it to match existing jobs.

Infrastructure as Code

Keep your job configuration in a JSON file and sync it in CI/CD:

// prikke.json
{
  "jobs": [
    {
      "key": "daily-backup",
      "name": "Daily backup",
      "url": "https://myapp.com/api/backup",
      "cron": "0 6 * * *"
    }
  ],
  "notifications": {
    "email": "alerts@myapp.com"
  },
  "delete_removed": true
}

# In your deploy script
curl -X PUT https://api.prikke.io/sync \
  -H "Authorization: Bearer $PRIKKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @prikke.json

Jobs API

You can also manage jobs individually using traditional REST endpoints.

POST /jobs

Create a new scheduled job.

Request Body

Field	Type	Description
`key`	string	Unique key for this job (optional, auto-generated if not provided)
`name`	string	A name for this job
`url`	string	The URL to call
`method`	string	HTTP method: GET or POST (default: POST)
`cron`	string	Cron expression for recurring jobs
`run_at`	string	ISO 8601 timestamp for one-time jobs
`headers`	object	Custom headers to send (optional)
`body`	string	Request body for POST requests (optional)

Use either cron (recurring) or run_at (one-time), not both.

Example: Recurring Job

curl -X POST https://api.prikke.io/jobs \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "daily-backup",
    "name": "Daily backup",
    "url": "https://myapp.com/api/backup",
    "cron": "0 6 * * *"
  }'

Example: One-time Job

curl -X POST https://api.prikke.io/jobs \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Send reminder",
    "url": "https://myapp.com/api/remind",
    "run_at": "2025-02-01T09:00:00Z",
    "body": "{\"user_id\": 123}"
  }'

Example: Run Immediately

Set run_at to the current time to execute a job right away:

await fetch('https://api.prikke.io/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Process upload',
    url: 'https://myapp.com/api/process',
    run_at: new Date().toISOString(),
    body: JSON.stringify({ file_id: 'abc123' })
  })
});

GET /jobs

List all your jobs.

curl https://api.prikke.io/jobs \
  -H "Authorization: Bearer pk_live_xxx"

Response

{
  "jobs": [
    {
      "id": "job_abc123",
      "key": "daily-backup",
      "name": "Daily backup",
      "url": "https://myapp.com/api/backup",
      "method": "POST",
      "cron": "0 6 * * *",
      "enabled": true,
      "created_at": "2025-01-28T12:00:00Z",
      "updated_at": "2025-01-28T12:00:00Z"
    }
  ]
}

GET /jobs/:id

Get a specific job by ID or key.

# By ID
curl https://api.prikke.io/jobs/job_abc123 \
  -H "Authorization: Bearer pk_live_xxx"

# By key
curl https://api.prikke.io/jobs/key/daily-backup \
  -H "Authorization: Bearer pk_live_xxx"

PATCH /jobs/:id

Update a job. You can update any field. Returns the updated job.

curl -X PATCH https://api.prikke.io/jobs/job_abc123 \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 7 * * *"
  }'

Response

{
  "job": {
    "id": "job_abc123",
    "key": "daily-backup",
    "name": "Daily backup",
    "cron": "0 7 * * *",
    "updated_at": "2025-01-28T14:00:00Z"
  },
  "changes": {
    "cron": {
      "from": "0 6 * * *",
      "to": "0 7 * * *"
    }
  }
}

DELETE /jobs/:id

Delete a job. This also cancels any pending executions.

curl -X DELETE https://api.prikke.io/jobs/job_abc123 \
  -H "Authorization: Bearer pk_live_xxx"

Response

{
  "deleted": true,
  "job": {
    "id": "job_abc123",
    "key": "daily-backup",
    "name": "Daily backup"
  }
}

Executions

GET /jobs/:id/executions

Get execution history for a job.

Response

{
  "executions": [
    {
      "id": "exec_123",
      "status": "success",
      "status_code": 200,
      "duration_ms": 145,
      "started_at": "2025-01-28T06:00:00Z",
      "finished_at": "2025-01-28T06:00:00Z"
    }
  ]
}

Project Settings

Configure project-level settings including notifications.

GET /project

Get current project settings.

Response

{
  "notifications": {
    "email": "alerts@myapp.com",
    "webhook_url": "https://hooks.slack.com/services/xxx"
  }
}

PUT /project

Update project settings. Returns the updated settings and what changed.

Request Body

Field	Type	Description
`notifications.email`	string	Email address for alerts (null to disable)
`notifications.webhook_url`	string	Webhook URL for alerts (null to disable)

Example

curl -X PUT https://api.prikke.io/project \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": {
      "email": "alerts@myapp.com",
      "webhook_url": "https://hooks.slack.com/services/xxx/yyy/zzz"
    }
  }'

Response

{
  "notifications": {
    "email": "alerts@myapp.com",
    "webhook_url": "https://hooks.slack.com/services/xxx/yyy/zzz"
  },
  "changes": {
    "notifications.webhook_url": {
      "from": null,
      "to": "https://hooks.slack.com/services/xxx/yyy/zzz"
    }
  }
}

Notifications

Webhook Payload

When a job fails, we send a POST request to your webhook URL with this payload:

{
  "event": "job.failed",
  "timestamp": "2025-01-28T06:00:15Z",
  "job": {
    "id": "job_abc123",
    "key": "daily-backup",
    "name": "Daily backup",
    "url": "https://myapp.com/api/backup"
  },
  "execution": {
    "id": "exec_xyz789",
    "status": "failed",
    "status_code": 500,
    "duration_ms": 1234,
    "started_at": "2025-01-28T06:00:00Z",
    "finished_at": "2025-01-28T06:00:01Z",
    "error": "Internal Server Error"
  }
}

Event Types

Event	Description
`job.failed`	Job returned non-2xx status code
`job.timeout`	Job did not respond within 30 seconds
`job.recovered`	Job succeeded after previous failure

Slack Integration

To send alerts to Slack, use a Slack Incoming Webhook URL. Prikke automatically formats the payload for Slack when it detects a hooks.slack.com URL.

Discord Integration

Discord webhooks work the same way. Prikke detects discord.com/api/webhooks URLs and formats accordingly.

Errors

The API returns standard HTTP status codes:

Code	Meaning
`200`	Success
`400`	Bad request - check your parameters
`401`	Unauthorized - invalid API key
`404`	Not found
`429`	Rate limited - slow down
`500`	Server error - try again

Error responses include a message:

{
  "error": {
    "code": "invalid_cron",
    "message": "Invalid cron expression: '* * * *' (expected 5 fields)"
  }
}