Sign in
jobs

Submit a workflow for execution

Changed on

Accepts the API-format workflow graph verbatim. Validation is synchronous: graph structure, unknown node classes, and asset references (core/ASSET objects — every referenced id must exist and be owned by the caller). A 201 means the job is durably recorded and queued.

UI-format workflow JSON (the export with nodes/links) is rejected with workflow_format_ui.

Idempotency-Key is single-use (reject-on-duplicate, NOT record-and-replay): the first request to present a given key is processed normally; ANY later request presenting the same key — a retry, a concurrent duplicate, or a same-key request with a different body — is rejected 422 idempotency_key_reuse and is never re-executed. The key is claimed only for a request that actually reaches submission and is released if that submission definitively fails without creating a job (a validation error, or an upstream reject such as out-of-credits or queue-full), so a legitimate retry with the same key can proceed. If a submission's outcome is unknown (an upstream timeout or 5xx where the job may or may not have been created), the key stays claimed and the retry is rejected: poll or list your jobs to find the possibly-created job rather than resubmitting. Keys expire after 24h. There is no response replay and no Idempotency-Replayed header.

Reserved for post-MVP and rejected if present today: webhook_url, inputs.

post/api/v2/jobs

Request

  • Base URL: http://127.0.0.1:8189
  • URL: http://127.0.0.1:8189/api/v2/jobs
  • Auth: one of:
    • HTTP bearer
    • none

Headers

Idempotency-Keystring

Client-generated UUID (recommended). Single-use: the first request to present a key is processed; any later request with the same key is rejected 422 idempotency_key_reuse (reject-on-duplicate, no response replay). Keys expire after 24h.

Request body

workflowobject required

API-format workflow graph, verbatim.

Response

Job created and queued.

idstring required
status'queued' | 'running' | 'succeeded' | 'canceling' | 'canceled' | 'failed' | 'expired' required

Lifecycle: queued → running → succeeded | failed | expired; a cancel request moves running → canceling → canceled. Terminal states: succeeded, canceled, failed, expired.

created_atstring date-time required
started_atstring date-time nullable required
completed_atstring date-time nullable required
expires_atstring date-time required

Retention deadline — a platform property, not an API constant.

queue_positioninteger nullable required
metricsobject

Values are nullable (a metric not yet available — e.g. execution_ms before a job starts running — is null, not omitted); the example below is deliberately all-non-null purely to work around a Spectral/nimma lint-tooling crash on a literal null inside a schema example combined with additionalProperties.nullable: true — the schema itself is unchanged and still allows null values at runtime.

Example response

{
  "id": "7f3d2c1b-9a8e-4d6f-b012-3c4d5e6f7a8b",
  "progress": {
    "value": 0.42,
    "nodes_done": 11,
    "nodes_total": 31,
    "current_node": "12",
    "current_node_class": "KSampler",
    "step": 21,
    "steps": 50,
    "message": "KSampler 21/50"
  },
  "outputs": [
    {
      "node_id": "9",
      "name": "ComfyUI_00001_.png",
      "content_type": "image/png",
      "size_bytes": 1848320,
      "id": "9f8a1c0d-2b3e-4f56-..."
    }
  ],
  "error": {
    "code": "node_execution_error"
  },
  "metrics": {
    "queue_ms": 9000,
    "execution_ms": 42000
  }
}

Changes

  • 1693eebb5691Revision changes
    • info

      added the new optional request property /

    • info

      added the optional property / to the response with the status

  • 2edfd164baddRevision changes
    • info

      added the optional property // to the response with the status