FoxCueAPI Jobs: Queue, Poll, Cancel and Retry Safely
Queue FoxCue script, article, slide and video jobs with POST /jobs and an Idempotency-Key, poll GET /jobs/{id} for status, and cancel. No webhooks yet.
Long-running work in the FoxCue API runs as jobs. You POST /jobs with an operation, an input and an Idempotency-Key, get back 202 with a job ID, then poll GET /jobs/{id} until it's done. Completion webhooks aren't available, so poll instead.
Operations
| Operation | What it does | Needs |
|---|---|---|
script.generate | Write a standard script | script_id, expected_updated_at, a meaningful topic and source or brief context |
script.generate_long | Write a long-form script | Same as above |
article.generate | Write an article from a script | script_id and a body snapshot |
slides.generate | Build slides from a script | script_id and a body snapshot |
video.render | Render existing slides into a narrated video | An existing deck and voice settings |
Script jobs accept an optional cost_limit_usd to lower the default $0.05 estimate ceiling. It can't raise it. See Script costs. Script jobs also accept writing_skill. Leave it out to keep the script's saved choice, or send null for the standard method.
Create a draft script first (POST /scripts), then queue generation.
Queue a job
curl "https://app.foxcue.com/api/v1/jobs" \
-H "Authorization: Bearer <workspace API key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: article-request-001" \
-d '{"operation":"article.generate","input":{"script_id":"<id>","body":"<script>"}}'The response is 202 with a job ID and a Location header.
Poll for status
GET /jobs/{id} returns the status, progress, result and any error_code:
| Status | Meaning |
|---|---|
queued | Waiting for a worker |
running | In progress |
done | Finished. The result is in the response. |
error | Failed, with a redacted error_code |
cancelled | Cancelled |
Idempotency
- Send an
Idempotency-Keyof 8–128 characters with everyPOST /jobs. - Repeating the same request with the same key returns the same job. It doesn't start (or pay for) a second one.
- Reusing a key with a different request returns
409. - After a network timeout, retry the exact original request with the same key.
- Ordinary create, update and delete calls don't have idempotency keys, so don't blindly retry a create after an uncertain response.
Cancel
POST /jobs/{id}/cancel (scope jobs:write) cancels queued work or asks running work to stop. A provider call that's already been sent may still complete and be charged.
Reliability
- Queued jobs survive server restarts.
- If a running job is interrupted, it fails as
worker_interrupted. AI and video work is never replayed automatically. Send a new request to retry. - Each workspace can have at most 3 queued or running API jobs at once.