SlideForgeSlideForge
Console

Jobs

GET/v1/jobs

List your recent jobs with optional filtering and pagination.

Parameters

NameTypeRequiredDescription
statusstringoptionalFilter by status: "queued", "generating", "complete", "failed".
limitintegeroptionalNumber of results to return. Default: 20, max: 100.
offsetintegeroptionalPagination offset. Default: 0.

Response

200
{
  "jobs": [
    {
      "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Build vs Buy Matrix",
      "status": "complete",
      "pptx_available": true,
      "artifact_status": "available",
      "cost": 0.1,
      "created_at": "2026-03-25T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Examples

curl "https://api.slideforge.dev/v1/jobs?status=complete&limit=10" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"
GET/v1/jobs/{id}

Get detailed status for a specific job. Poll this endpoint after generating or iterating to check progress and retrieve results. Successful jobs include a structured telemetry.latency rollup; failed jobs carry a structured error_envelope with a programmatic recovery_suggestion.

Response

200
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Build vs Buy Matrix",
  "status": "complete",
  "current_iteration": 2,
  "max_iterations": 5,
  "pptx_available": true,
  "artifact_status": "available",
  "retention_expires_at": "2026-08-07T10:30:00Z",
  "iterations": 2,
  "cost_usd": 0.08,
  "cost": 0.1,
  "latency_ms": 11500,
  "telemetry": {
    "latency": {
      "total_ms": 11500,
      "planning_ms": 540,
      "generation_ms": 6320,
      "render_ms": 3870,
      "preview_ms": 770
    }
  }
}

Examples

curl https://api.slideforge.dev/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

Downloading the file

Job responses carry no download credentials — pptx_available is just an opaque availability signal. Two ways to get the file, both ownership-checked:

  • GET /v1/jobs/{id}/pptx · /preview[/{size}] · /pdf — header-auth with your normal Authorization: Bearer key. The recommended path for programmatic access.
  • POST /v1/jobs/{id}/download-url (body {"artifact": "pptx"}) — mints a download_url with a 5-minute TTL, single-use (a replay 410s), instantly revocable. Use this for a link you hand to someone else.
curl https://api.slideforge.dev/v1/jobs/JOB_ID/pptx \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -o slide.pptx

curl -X POST https://api.slideforge.dev/v1/jobs/JOB_ID/download-url \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artifact": "pptx"}'

Artifacts auto-delete after 30 days; a job past that window reports artifact_status: "expired" and pptx_available: false — regenerate to get a fresh file.

Failed-job error_envelope

When status: "failed", the response carries an error_envelope alongside the legacy error string. For TIMEOUT and GENERATION_FAILED codes the envelope includes a best-effort recovery_suggestion with a candidate recipe, slot schema, and example slots — consumable directly by an agent for a one-shot retry without going back through the router.

{
  "job_id": "f3e4d5c6-b7a8-9012-3456-789abcdef012",
  "name": "Vague Brief",
  "status": "failed",
  "error": "GENERATION_FAILED",
  "error_envelope": {
    "code": "GENERATION_FAILED",
    "message": "Render failed after retry budget exhausted.",
    "user_action": "Add concrete metrics or a clear comparison to the brief and re-run, or send a structured intent (form + data).",
    "debug": {
      "stage": "render",
      "attempts": 3
    }
  },
  "cost": 0
}

Long-polling

Add ?poll=true&timeout=30 to wait for completion instead of polling repeatedly. The server holds the connection for up to timeout seconds (max 60), returning immediately when the job completes. Falls back to the current status if it times out.

curl "https://api.slideforge.dev/v1/jobs/JOB_ID?poll=true&timeout=30" \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

DELETE /v1/jobs/{id}

Delete a job and its associated files. Returns 204 No Content on success. Only the job owner can delete their jobs.

curl -X DELETE https://api.slideforge.dev/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

GET /v1/jobs/{id}/versions

Get the iteration history for a slide. Returns an array of job versions ordered by iteration. Download any version with GET /v1/jobs/{version_job_id}/preview or /pptx. Useful for comparing before/after.

curl https://api.slideforge.dev/v1/jobs/JOB_ID/versions \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

# Returns: [
#   {"job_id": "v1...", "iteration": 0, "pptx_available": true},
#   {"job_id": "v2...", "iteration": 1, "pptx_available": true}
# ]

Job statuses

queuedJob accepted, waiting to start
generatingAI is writing code and generating the slide
executingCode is running in the sandbox
renderingConverting PPTX to PNG preview
completeDone and faithful. pptx_available is true — download via GET /v1/jobs/{id}/pptx or mint a link; the slide was billed.
completed_with_errorsRendered, but ≥1 error means a datum is missing or an invariant is broken (see errors[]). pptx_available is false and the slide is free; add force_render to download it anyway.
partialDeck where some slides were dropped — the surviving slides are a real, shippable .pptx.
failedGeneration failed. Read error_envelope.recovery_suggestion for a programmatic retry hint; the legacy error string is also populated.