Jobs

GET/v1/jobs

List your recent jobs with optional filtering and pagination.

Parameters

Name	Type	Required	Description
status	string	optional	Filter by status: "queued", "generating", "complete", "failed".
limit	integer	optional	Number of results to return. Default: 20, max: 100.
offset	integer	optional	Pagination offset. Default: 0.

Response

200

{
  "jobs": [
    {
      "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Build vs Buy Matrix",
      "status": "complete",
      "pptx_url": "https://api.slideforge.dev/v1/files/...",
      "preview_url": "https://api.slideforge.dev/v1/files/...",
      "cost_charged": 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.

Response

200

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Build vs Buy Matrix",
  "status": "complete",
  "current_iteration": 2,
  "max_iterations": 5,
  "pptx_url": "https://api.slideforge.dev/v1/files/...",
  "preview_url": "https://api.slideforge.dev/v1/files/...",
  "final_score": 8.7,
  "iterations": 2,
  "cost_usd": 0.08,
  "cost_charged": 0.1,
  "latency_ms": 11500
}

Examples

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

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, each with its own pptx_url, preview_url, and score. 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, "score": 7.2, "preview_url": "..."},
#   {"job_id": "v2...", "iteration": 1, "score": 8.5, "preview_url": "..."}
# ]

Job statuses

`queued`	Job accepted, waiting to start
`generating`	AI is writing code and generating the slide
`executing`	Code is running in the sandbox
`rendering`	Converting PPTX to PNG preview
`complete`	Done. pptx_url and preview_url are available.
`failed`	Generation failed. Check the error field.