Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Jobs

Long-running operations on the Scripe API (post generation, knowledge base ingest, source ingest from file) run as async jobs. The endpoint that submits one returns a Job envelope; you poll GET /v1/jobs/{jobId} (or use wait_for_completion_ms for short jobs) until the status leaves QUEUED/RUNNING. The job lifecycle is:
StatusMeaning
QUEUEDSubmitted, not picked up yet. Cancellable.
RUNNINGWorker is processing it. Not cancellable in v1.
DONESucceeded. result populated; shape depends on type.
FAILEDFailed. errorCode + errorMessage populated.
CANCELLEDYou called the cancel endpoint while it was QUEUED.
Workers update progress to a separate Redis key with a 1-hour TTL, so the progress snapshot on GET /v1/jobs/{jobId} may be null if the job hasn’t started or has already finished.

​
Job types

typeSubmitted viaresult shape
POST_GENERATIONPOST /v1/posts/generations{ postId: "post_…" }
KB_INGEST_TEXTPOST /v1/knowledge (Wave 4){ documentId: "kb_…" }
KB_INGEST_FILEPOST /v1/knowledge (Wave 4){ documentId: "kb_…" }
KB_INGEST_URLPOST /v1/knowledge (Wave 4){ documentId: "kb_…" }
KB_INGEST_YOUTUBEPOST /v1/knowledge (Wave 4){ documentId: "kb_…" }
SOURCE_INGEST_FILEPOST /v1/sources (Wave 4, file uploads){ sourceId: "src_…" }
Wave 3 ships only POST_GENERATION. The other types appear in the enum / OpenAPI spec for forward-compat but the endpoints land in Wave 4.

​
GET /v1/jobs

List jobs in the workspace, newest first. 
curl -i 'https://api.scripe.io/v1/jobs?type=POST_GENERATION&status=DONE,FAILED&limit=20' \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01"

​
Query parameters

NameTypeRequiredDefaultNotes
typestringno—Comma-separated list of type values. Unknown values → 400 invalid_request.
statusstringno—Comma-separated list of statuses. Unknown values → 400 invalid_request.
dateFromstringno—YYYY-MM-DD, filters by createdAt. Inclusive.
dateTostringno—YYYY-MM-DD. Inclusive end-of-day UTC.
limitintegerno501…200.
cursorstringno—Opaque cursor from a previous response.

​
Response

{
  "data": [
    {
      "id": "job_01J9ZA…",
      "type": "POST_GENERATION",
      "status": "DONE",
      "projectId": "proj_01J9ZA…",
      "startedAt": "2026-05-15T08:21:30.000Z",
      "completedAt": "2026-05-15T08:21:55.000Z",
      "progress": null,
      "result": { "postId": "post_01J9ZA…" },
      "errorCode": null,
      "errorMessage": null,
      "attemptCount": 1,
      "estimatedCompletionMs": 25000,
      "createdAt": "2026-05-15T08:21:00.000Z",
      "updatedAt": "2026-05-15T08:21:55.000Z"
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}
The list endpoint omits live progress to keep it cheap. Fetch /v1/jobs/{jobId} for the freshest snapshot.

​
Errors

StatusCode
400invalid_request (bad type / status), bad_cursor, bad_pagination
401unauthenticated, invalid_token, key_revoked, key_expired
429rate_limited

​
GET /v1/jobs/{jobId}

Fetch a single job + its latest progress snapshot. 
curl -i https://api.scripe.io/v1/jobs/job_01J9ZA… \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01"

​
Response

While the job is running you’ll see a progress payload: 
{
  "data": {
    "id": "job_01J9ZA…",
    "type": "POST_GENERATION",
    "status": "RUNNING",
    "projectId": "proj_01J9ZA…",
    "startedAt": "2026-05-15T08:21:30.000Z",
    "completedAt": null,
    "progress": {
      "progress": 0.4,
      "message": "Generating post",
      "updatedAt": "2026-05-15T08:21:42.000Z"
    },
    "result": null,
    "errorCode": null,
    "errorMessage": null,
    "attemptCount": 1,
    "estimatedCompletionMs": 25000,
    "createdAt": "2026-05-15T08:21:00.000Z",
    "updatedAt": "2026-05-15T08:21:42.000Z"
  }
}
progress is null when the job is still QUEUED or has already finished (the Redis key has a 1-hour TTL).

​
Polling cadence

Workers emit ~10 progress updates per POST_GENERATION. Poll once per second while status is RUNNING. Long-running types (KB_INGEST_*) emit fewer updates — back off to once every 5 seconds after the first 30 seconds.

​
Errors

StatusCode
401unauthenticated, invalid_token, key_revoked, key_expired
404not_found
429rate_limited

​
POST /v1/jobs/{jobId}/cancel

Cancel a QUEUED job. v1 does NOT support cancelling RUNNING jobs (workers don’t poll for cancellation mid-run); attempting to cancel one returns 409 not_cancellable. 
curl -i https://api.scripe.io/v1/jobs/job_01J9ZA…/cancel \
  -X POST \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01"

​
Response

The freshly-cancelled job, with status: "CANCELLED" and a populated completedAt: 
{
  "data": {
    "id": "job_01J9ZA…",
    "type": "POST_GENERATION",
    "status": "CANCELLED",
    "projectId": "proj_01J9ZA…",
    "startedAt": null,
    "completedAt": "2026-05-15T08:21:05.000Z",
    "progress": null,
    "result": null,
    "errorCode": null,
    "errorMessage": null,
    "attemptCount": 0,
    "estimatedCompletionMs": 25000,
    "createdAt": "2026-05-15T08:21:00.000Z",
    "updatedAt": "2026-05-15T08:21:05.000Z"
  }
}

​
Errors

StatusCode
401unauthenticated, invalid_token, key_revoked, key_expired
404not_found
409not_cancellable (job is RUNNING, DONE, FAILED, or already CANCELLED)
429rate_limited

​
AI spend cap

Every job that runs an AI workload (currently: POST_GENERATION) is gated by a daily workspace spend cap (per UTC day). The pre-flight check happens at submit time:
PlanCap (per day)
SOLO$5 (500¢)
ADVANCED$20 (2,000¢)
BUSINESS$50 (5,000¢)
ENTERPRISEunlimited
When a submit would put the workspace over the cap, the API returns 402 spend_cap_exceeded with the current spentCents and capCents in the error meta. The bucket resets at 00:00 UTC.