{"openapi":"3.1.0","info":{"title":"Stafett","summary":"Hosted HTTP delivery queue: POST a job, we call your URL back.","description":"Stafett is a hosted HTTP delivery queue. `POST /enqueue` a payload and an HTTPS\ncallback URL; Stafett stores the job and calls you back with retries,\nexponential backoff, and [Standard Webhooks](https://www.standardwebhooks.com/)\nsigning, then holds anything that runs out of attempts in a replayable\ndead-letter queue.\n\n**Delivery is at-least-once** — a callback can arrive more than once, so make\nyour handler idempotent. The `webhook-id` header is the job id and is a stable\nidempotency key across retries.\n\nAuthenticate with a tenant API token (`Authorization: Bearer stf_…`) created in\nthe control plane.\n","contact":{"name":"Stafett","url":"https://stafett.dev/"},"license":{"name":"Proprietary - All rights reserved"},"version":"0.1.0"},"paths":{"/enqueue":{"post":{"tags":["jobs"],"summary":"Enqueue a job","description":"Accept a job for delivery.\n\nStafett stores the job and POSTs your `payload` to `callback_url` with\nretries, exponential backoff, and Standard Webhooks signing. Delivery is\n**at-least-once**, so your handler must be idempotent. Poll `status_url` to\nfollow the outcome.","operationId":"enqueue_enqueue_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnqueueRequest"}}},"required":true},"responses":{"202":{"description":"The job was accepted and will be delivered at least once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnqueueResponse"},"example":{"id":"018f3b7c-6c4a-7b32-9f21-2c0a5e4d9b11","status":"queued","status_url":"/jobs/018f3b7c-6c4a-7b32-9f21-2c0a5e4d9b11"}}}},"401":{"description":"Missing, invalid, or revoked bearer token.","content":{"application/json":{"example":{"detail":"missing bearer token"}}}},"409":{"description":"A job with this `dedupe_key` is already queued or in flight.","content":{"application/json":{"example":{"detail":"dedupe key already active"}}}},"422":{"description":"The request body failed validation."}},"security":[{"StafettApiToken":[]}]}},"/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"Fetch job status","description":"Report where a previously enqueued job is in its lifecycle.\n\nThis is the fetch-later half of the call-now, fetch-later contract: enqueue\nreturns immediately, and this endpoint reports `queued`, `delivering`,\n`delivered`, `retrying`, or `dead`.","operationId":"get_job_jobs__job_id__get","security":[{"StafettApiToken":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The job id returned by `POST /enqueue`.","title":"Job Id"},"description":"The job id returned by `POST /enqueue`."}],"responses":{"200":{"description":"The current status and attempt count for the job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"401":{"description":"Missing, invalid, or revoked bearer token.","content":{"application/json":{"example":{"detail":"missing bearer token"}}}},"404":{"description":"No job with this id for the calling tenant.","content":{"application/json":{"example":{"detail":"job not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/schedules":{"get":{"tags":["schedules"],"summary":"List schedules","operationId":"list_schedules_schedules_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ScheduleResponse"},"type":"array","title":"Response List Schedules Schedules Get"}}}},"401":{"description":"Missing, invalid, or revoked bearer token.","content":{"application/json":{"example":{"detail":"missing bearer token"}}}}},"security":[{"StafettApiToken":[]}]},"post":{"tags":["schedules"],"summary":"Create a cron schedule","description":"Register a recurring HTTPS delivery.\n\nEach fire enqueues a normal Stafett job with the same delivery, retry, and\nsigning contract as ``POST /enqueue``. Delivery is **at-least-once**.","operationId":"create_schedule_schedules_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScheduleRequest"}}},"required":true},"responses":{"201":{"description":"The schedule was stored and will enqueue jobs on fire.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleResponse"}}}},"401":{"description":"Missing, invalid, or revoked bearer token.","content":{"application/json":{"example":{"detail":"missing bearer token"}}}},"422":{"description":"The request body failed validation."}},"security":[{"StafettApiToken":[]}]}},"/schedules/{schedule_id}":{"get":{"tags":["schedules"],"summary":"Fetch a schedule","operationId":"get_schedule_schedules__schedule_id__get","security":[{"StafettApiToken":[]}],"parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The schedule id.","title":"Schedule Id"},"description":"The schedule id."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleResponse"}}}},"401":{"description":"Missing, invalid, or revoked bearer token.","content":{"application/json":{"example":{"detail":"missing bearer token"}}}},"404":{"description":"No schedule with this id for the calling tenant."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["schedules"],"summary":"Delete a schedule","operationId":"delete_schedule_schedules__schedule_id__delete","security":[{"StafettApiToken":[]}],"parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The schedule id.","title":"Schedule Id"},"description":"The schedule id."}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Missing, invalid, or revoked bearer token.","content":{"application/json":{"example":{"detail":"missing bearer token"}}}},"404":{"description":"No schedule with this id for the calling tenant."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CreateScheduleRequest":{"properties":{"name":{"type":"string","maxLength":128,"minLength":1,"title":"Name","description":"Operator-facing label for the schedule."},"cron_expression":{"type":"string","maxLength":128,"minLength":1,"title":"Cron Expression","description":"Five-field cron expression (minute hour day month weekday)."},"callback_url":{"type":"string","maxLength":2048,"minLength":1,"format":"uri","title":"Callback Url","description":"HTTPS endpoint Stafett POSTs to on each fire."},"payload":{"$ref":"#/components/schemas/JsonValue","description":"Arbitrary JSON delivered verbatim. Up to 1 MiB encoded."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Extra request headers to forward. Up to 50 entries."},"priority":{"type":"integer","maximum":100.0,"minimum":-100.0,"title":"Priority","description":"Priority applied to each enqueued job.","default":0}},"type":"object","required":["name","cron_expression","callback_url"],"title":"CreateScheduleRequest","examples":[{"callback_url":"https://api.example.com/hooks/cleanup","cron_expression":"0 3 * * *","name":"nightly-cleanup","payload":{"task":"cleanup"},"priority":0}]},"EnqueueRequest":{"properties":{"callback_url":{"type":"string","maxLength":2048,"minLength":1,"format":"uri","title":"Callback Url","description":"HTTPS endpoint Stafett POSTs the signed payload to."},"payload":{"$ref":"#/components/schemas/JsonValue","description":"Arbitrary JSON delivered verbatim. Up to 1 MiB encoded."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Extra request headers to forward. Up to 50 entries."},"delay_seconds":{"type":"integer","minimum":0.0,"title":"Delay Seconds","description":"Seconds to wait before the first delivery attempt.","default":0},"priority":{"type":"integer","maximum":100.0,"minimum":-100.0,"title":"Priority","description":"Higher values are claimed before lower ones. Defaults to 0; allowed range is -100..100.","default":0},"dedupe_key":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Dedupe Key","description":"Optional uniqueness key. While a job with this key is queued or in flight, a second enqueue with the same key returns 409."}},"type":"object","required":["callback_url"],"title":"EnqueueRequest","examples":[{"callback_url":"https://api.example.com/hooks/ship","delay_seconds":0,"headers":{"x-source":"checkout"},"payload":{"order":42},"priority":0}]},"EnqueueResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Stable job id. Also the Standard Webhooks id."},"status":{"$ref":"#/components/schemas/JobStatus","description":"Lifecycle state, `queued` on accept."},"status_url":{"type":"string","title":"Status Url","description":"Relative path to poll for job status."}},"type":"object","required":["id","status","status_url"],"title":"EnqueueResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"JobStatus":{"type":"string","enum":["queued","delivering","delivered","retrying","dead"],"title":"JobStatus"},"JobStatusResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The job id."},"status":{"$ref":"#/components/schemas/JobStatus","description":"One of queued, delivering, delivered, retrying, dead."},"attempts":{"type":"integer","title":"Attempts","description":"Delivery attempts made so far."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the job was enqueued (UTC)."}},"type":"object","required":["id","status","attempts","created_at"],"title":"JobStatusResponse"},"JsonValue":{},"ScheduleResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Stable schedule id."},"name":{"type":"string","title":"Name"},"cron_expression":{"type":"string","title":"Cron Expression"},"callback_url":{"type":"string","title":"Callback Url"},"priority":{"type":"integer","title":"Priority"},"enabled":{"type":"boolean","title":"Enabled"},"next_run_at":{"type":"string","format":"date-time","title":"Next Run At"},"last_enqueued_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Enqueued At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","name","cron_expression","callback_url","priority","enabled","next_run_at","last_enqueued_at","created_at"],"title":"ScheduleResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"StafettApiToken":{"type":"http","description":"Tenant API token issued in the control plane, e.g. `stf_…`.","scheme":"bearer"}}},"tags":[{"name":"jobs","description":"Enqueue jobs and poll their delivery status."},{"name":"schedules","description":"Cron → HTTP schedules that enqueue delivery jobs on fire."},{"name":"ops","description":"Operational probes. No authentication required."}]}