Quickstart

Create and run your first scheduled job in under five minutes. This guide walks you through getting an API key, creating a job with an interval schedule, checking execution history, and controlling job state.

Prerequisites

• A Krafter account (invite-only -- request access at app.krafter.dev)
• An API key with cron:write scope
• A publicly accessible HTTP endpoint to receive webhook calls

Step 1: Create a Cron Job

Create a job that calls your endpoint every 5 minutes using an interval preset:

curl -X POST https://app.krafter.dev/api/v1/cron/jobs \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Health Check",
    "schedule_type": "interval",
    "schedule": "every_5m",
    "url": "https://example.com/api/health",
    "method": "GET"
  }'

{
  "data": {
    "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "Health Check",
    "schedule_type": "interval",
    "schedule": "every_5m",
    "timezone": "UTC",
    "url": "https://example.com/api/health",
    "method": "GET",
    "headers": {},
    "timeout_ms": 30000,
    "max_retries": 3,
    "enabled": true,
    "failure_notify": false,
    "last_status": null,
    "last_run_at": null,
    "next_run_at": "2025-01-15T10:05:00Z",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

The job is created and enabled by default. It will fire its first request at next_run_at.

TIP

For precise scheduling, use schedule_type: "cron" with a standard cron expression instead. See the Scheduling Guide for details.

Step 2: View Execution History

After the job has run at least once, check its execution history:

curl https://app.krafter.dev/api/v1/cron/jobs/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/executions \
  -H "Authorization: Bearer kr_live_abc123def456"

{
  "data": [
    {
      "id": "e1f2a3b4-c5d6-e7f8-a9b0-c1d2e3f4a5b6",
      "status": "success",
      "http_status": 200,
      "response_body": "{\"status\":\"ok\"}",
      "error": null,
      "attempt": 1,
      "duration_ms": 142,
      "started_at": "2025-01-15T10:05:00Z",
      "finished_at": "2025-01-15T10:05:00Z"
    }
  ]
}

Each execution records the HTTP status, response body, duration, and whether retries were needed.

Step 3: Manually Trigger a Job

Don't want to wait for the next scheduled run? Trigger the job immediately:

curl -X POST https://app.krafter.dev/api/v1/cron/jobs/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/trigger \
  -H "Authorization: Bearer kr_live_abc123def456"

{
  "ok": true
}

The job executes right away. Check the execution history to see the result.

Step 4: Pause and Resume

Temporarily stop a job without deleting it:

# Pause the job
curl -X POST https://app.krafter.dev/api/v1/cron/jobs/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/pause \
  -H "Authorization: Bearer kr_live_abc123def456"

{
  "data": {
    "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "Health Check",
    "enabled": false
  }
}

When you're ready to restart the schedule:

# Resume the job
curl -X POST https://app.krafter.dev/api/v1/cron/jobs/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/resume \
  -H "Authorization: Bearer kr_live_abc123def456"

{
  "data": {
    "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "Health Check",
    "enabled": true
  }
}

WARNING

Pausing a job does not cancel an execution that is already in progress. It prevents future scheduled runs until the job is resumed.

Next Steps

• Scheduling Guide -- Cron expressions, interval presets, timezones, and retry logic
• Jobs API -- Full CRUD and control endpoints
• Executions API -- Query and filter execution history