Production Lifecycle

A production moves through a defined set of states from creation to completion. Understanding these states helps you build robust integrations.

Triggering a Production

Create a new production by posting to the account’s productions endpoint:

curl -X POST https://apim-jarai-prd.azure-api.net/v1/accounts/{accountId}/productions \
-H "X-API-Key: jarai_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "topic": "Weekly market analysis for tech sector",
  "languageId": "LANGUAGE_UUID",
  "countryId": "COUNTRY_UUID",
  "avatarId": "AVATAR_UUID",
  "projectTypeSlug": "social-video-30s",
  "metadataMD": "Focus on AI chip stocks and cloud infrastructure trends."
}'

Request Fields

Field	Required	Type	Description
`topic`	Yes	string (1–500 chars)	The subject matter for the production.
`languageId`	Yes	UUID	Language for the production content.
`countryId`	Yes	UUID	Target country/locale.
`avatarId`	Yes	UUID	The AI avatar to use for the production.
`projectTypeSlug`	No	string	Project type identifier. Defaults to the account’s default.
`metadataMD`	No	string (max 4,096 chars)	Additional Markdown context passed to the AI pipeline.

Production States

Productions move through the following states:

Status	Type	Description
`Queued`	Transient	Production submitted, waiting to be picked up by the pipeline.
`Producing`	Transient	Pipeline is actively processing steps (narrative, visuals, audio, video).
`AwaitingApproval`	Transient	All pipeline steps complete. Deliverables available for review. Waiting for operator release.
`Distributing`	Transient	Content is being published to connected platforms.
`Published`	Terminal	All platforms published successfully.
`Failed`	Terminal	Production failed. Check `errorCode` and `errorMessage` for details.
`Cancelled`	Terminal	Production was cancelled by the partner or operator.

Terminal states are final — no further transitions occur. Transient states will eventually transition to a terminal state.

Production Expiry

API-triggered productions include an expiresAt timestamp. If the production is not picked up by the pipeline within this window (default: 10 minutes), it transitions to Failed with error code PRODUCTION_EXPIRED. This is safe to retry immediately.

Polling for Status

curl https://apim-jarai-prd.azure-api.net/v1/productions/{productionId} \
-H "X-API-Key: jarai_your_api_key_here"

Recommended Polling Intervals

Status	Interval	Reason
`Queued`	10 seconds	Productions are picked up quickly; you want to know when processing starts.
`Producing`	30 seconds	Pipeline steps take minutes each; frequent polling adds no value.
`AwaitingApproval`	60 seconds	Waiting for operator action; no urgency.
`Distributing`	30 seconds	Platform publishing typically completes within minutes.

For real-time updates without polling overhead, use webhooks instead.

Status Response Shape

{
  "productionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "Producing",
  "createdAt": "2026-04-03T10:30:00Z",
  "updatedAt": "2026-04-03T10:35:22Z",
  "errorCode": null,
  "errorMessage": null,
  "stepsComplete": 5,
  "currentStep": "Image Acquisition",
  "platforms": [],
  "expiresAt": "2026-04-03T10:40:00Z"
}

Listing Productions

Retrieve all productions for an account with cursor-based pagination:

# First page (20 results by default)
curl "https://apim-jarai-prd.azure-api.net/v1/accounts/{accountId}/productions" \
-H "X-API-Key: jarai_your_api_key_here"

# Next page using cursor
curl "https://apim-jarai-prd.azure-api.net/v1/accounts/{accountId}/productions?after={lastProductionId}" \
-H "X-API-Key: jarai_your_api_key_here"

Results are ordered by createdAt descending. Default page size is 20 (maximum: 100).

Cancelling a Production

Cancel a production that has not yet reached a terminal state:

curl -X DELETE https://apim-jarai-prd.azure-api.net/v1/productions/{productionId} \
-H "X-API-Key: jarai_your_api_key_here"

Cancellation is idempotent — cancelling an already-cancelled production returns 204 again. Cancelling a Published or Failed production returns 409 ALREADY_TERMINAL. Only API-triggered productions can be cancelled by partners; manual and autonomous productions return 403 CANCELLATION_NOT_PERMITTED.

Production Error Codes

When a production reaches Failed status, the errorCode field indicates what went wrong:

Error Code	Meaning	Retry?
`PROVIDER_UNAVAILABLE`	AI provider returned 5xx or was unreachable	Yes — safe to retry
`PROVIDER_QUOTA_EXHAUSTED`	AI model’s monthly token budget exhausted	No — wait for next billing period
`PRODUCTION_EXPIRED`	Not picked up within the expiry window	Yes — retry immediately
`COMPLIANCE_GATE_FAILED`	Content failed a compliance guardrail	No — adjust topic or configuration
`BUDGET_EXHAUSTED`	Account’s monthly AI spend limit reached	No — wait for next month or top up budget
`INVALID_CONFIGURATION`	Account configuration invalid for this production type	No — fix configuration first
`CONTENT_SENSITIVITY_SUPPRESSED`	Sensitivity rule blocked the production	No — contact operator
`INTERNAL_ERROR`	Unexpected system error	Yes — retry once after 5 minutes

Next Steps

Webhook Integration — receive real-time production events
Error Handling — full error envelope reference and retry guidance
Rate Limiting — understand request limits by tier