API Reference

Create a Job

Create one asynchronous Job from a complete ComfyUI API-format prompt.

POST/v1/api/job/comfy-prompt

Request example

bash

curl --request POST   --url "$NORDY_BASE_URL/v1/api/job/comfy-prompt"   --header "api-key: $NORDY_API_KEY"   --header "content-type: application/json"   --data-binary @request.json

Success response202 Accepted

JSON

{
  "id": "68abcdef0123456789abcdef",
  "user_metadata": {},
  "status": "queued",
  "createdAt": "2026-08-26T00:00:00.000Z",
  "startedAt": null,
  "completedAt": null,
  "outputs": null,
  "error": null
}

Authentication

api-keystringrequired

Send the user API key in the api-key request header.

Request body

Content-Type: application/json

promptobjectbodyrequired: API-format prompt keyed by node ID.
prompt.<nodeId>.class_typestringbodyrequired: ComfyUI node class name.
prompt.<nodeId>.inputsobjectbodyrequired: Inputs passed to the node; connections use [sourceNodeId, outputIndex].
user_metadataobjectbodyoptional: Custom data to associate the Job with a record in your application.

Input limits

A request can contain up to 50 MiB of JSON and 1 to 1,024 prompt nodes.
Prompt structure: up to 32 levels of nesting, 16,384 object properties in total, and 4,096 items per array.
Prompt text: up to 64 KiB per string and 1,024 bytes per key, measured in UTF-8. Integers must be between -9,007,199,254,740,991 and 9,007,199,254,740,991.
user_metadata accepts up to 32 keys and 8 KiB in total.
Metadata keys: up to 64 characters, starting with A-Z, a-z, or 0-9. Use these characters plus underscores, dots, and hyphens. The names __proto__, prototype, and constructor are reserved.
Metadata values: strings, numbers, booleans, or null. Nested objects and arrays are not accepted. Strings are limited to 1,024 UTF-8 bytes.
Metadata numbers must be finite and between -9,007,199,254,740,991 and 9,007,199,254,740,991. Use 0 instead of -0.

Success response

202 Accepted Queued and processing responses include Retry-After: 5.

idstringresponserequired: Job ID.
user_metadataobjectresponserequired: Metadata supplied when the Job was created; {} when omitted.
statusqueued | processing | succeeded | failed | canceledresponserequired: Current Job status.
createdAtdate-timeresponserequired: Job creation time.
startedAtdate-timeresponserequirednullable: Execution start time; null when unavailable.
completedAtdate-timeresponserequirednullable: Terminal completion time; null when unavailable.
outputsarrayresponserequirednullable: Unexpired outputs for succeeded Jobs; [] after all expire, while the Job remains available. Null for other statuses.
outputs[].idstringresponserequired: API Output Asset ID.
outputs[].urlstringresponserequired: Generated file URL.
outputs[].kindimage | video | audio | model3dresponserequired: Output media kind.
outputs[].expiresAtdate-timeresponserequired: Expiration time, 7 days after this output was created. Download the file before this time.
errorobjectresponserequirednullable: Terminal Job error for failed or canceled Jobs; null otherwise.
error.codeenumresponserequired: INVALID_INPUT, INSUFFICIENT_CREDIT, EXECUTION_TIMEOUT, WORKER_UNAVAILABLE, EXECUTION_FAILED, or JOB_CANCELED.
error.messagestringresponserequired: Public error message.
error.detailsobjectresponseoptional: Raw ComfyUI validation data, only for INVALID_INPUT when available.
error.details.errorobjectresponserequired: ComfyUI prompt validation error.
error.details.node_errorsobjectresponserequired: ComfyUI validation errors keyed by node ID.

Notes

Job creation is subject to a daily limit.
Only prompt and optional user_metadata are accepted at the top level.
Each accepted request creates a separate Job, even with identical prompt or user_metadata. Do not automatically resubmit after a timeout or lost response; check the saved ID or recent Jobs first.
ComfyUI node-value validation can fail later as a failed Job with error.code INVALID_INPUT.

Responses and errors

Status	Code	Description
429	DAILY_JOB_LIMIT_EXCEEDED	Creation limit reached. Try again after it resets.
400	INVALID_JSON, INVALID_INPUT	Invalid JSON, prompt, or metadata.
400	MULTIPLE_AUTH_CREDENTIALS	Send only the api-key header, without login cookies.
401	AUTHENTICATION_REQUIRED	Missing or invalid API key.
402	INSUFFICIENT_CREDIT	Not enough credit to create the Job.
403	USER_SUSPENDED, PRO_SUBSCRIPTION_REQUIRED, INVALID_INPUT	Your account is suspended, does not have an active Pro subscription, or is not permitted to use the API.
413	REQUEST_BODY_TOO_LARGE	The JSON body exceeds the 50 MiB limit.
415	UNSUPPORTED_MEDIA_TYPE	Content-Type is not application/json.
500	INTERNAL_ERROR	Internal server error.