Sign in
Workflows

Submit workflow

Changed on
post/v2/consumer/workflows

Request

  • The document declares no server URL.
  • Auth: none required

Query parameters

waitinteger

Seconds to wait for the workflow to complete before returning. If it has not completed by then a 202 is returned and the client should query the workflow by its id.

whatifboolean

Whether to actually submit the workflow or return an estimate on what would happen upon submission

hideMatureContentboolean

When set to true, any blob that has mature won't be available and won't have a URL

Request body

metadataobject nullable
tagsstring[] nullable

Indexed for searching. At most 10 tags, each at most 200 characters.

argumentsobject nullable
nsfwLevel'pg' | 'pg13' | 'r' | 'x' | 'xxx' | 'na'
downloadPriority'high' | 'normal' | 'low' | 'idle'
tier'paid' | 'free'

How a workflow is paid for.

experimentalboolean nullable

Opts the workflow in to new features or behaviours that are not yet stable.

allowMatureContentboolean nullable

When false, no content marked as mature is returned; additional payment options are available for such workflows.

upgradeMode'manual' | 'automatic'

Specifies how a workflow should be upgraded when mature content is detected and green or blue buzz was used for payment.

currenciesBuzzClientAccount[] required

Limit the currencies that can be used to pay for this workflow.

ephemeralboolean nullable

Never persisted: results are available only via callbacks or the synchronous wait parameter, and GET returns 404 once terminal. Requires at least one callback or wait > 0 on submission.

externalIdstring nullable

Idempotency key: if a workflow with the same (userId, externalId) exists (including from a prior whatif=true request), it is returned instead of creating a new one. Max 128 chars, [A-Za-z0-9_-]+.

Example request

{
  "callbacks": [
    {
      "type": [
        "workflow:succeeded"
      ]
    }
  ]
}

Response

OK

idstring nullable
createdAtstring date-time required
metadataobject required
status'unassigned' | 'preparing' | 'scheduled' | 'processing' | 'succeeded' | 'failed' | 'expired' | 'canceled' required
startedAtstring date-time nullable
completedAtstring date-time nullable
tagsstring[] required

Indexed for searching; at most 10 per workflow.

argumentsobject required
nsfwLevel'pg' | 'pg13' | 'r' | 'x' | 'xxx' | 'na'
experimentalboolean nullable

Opts the workflow in to new features or behaviours that are not yet stable.

allowMatureContentboolean nullable
upgradeMode'manual' | 'automatic' required

Specifies how a workflow should be upgraded when mature content is detected and green or blue buzz was used for payment.

currenciesBuzzClientAccount[] required
forceRefundedboolean required

Whether this workflow has been force-refunded. Prevents re-charging on grain recovery.

ephemeralboolean nullable

Not persisted to telemetry/MongoDB; in-flight state lives only in grain state and nothing remains once terminal.

externalIdstring nullable

Client-supplied idempotency key, stored as "{userId}-{clientValue}" so the unique index is single-field yet per-user. See Civitai.Orchestration.Grains.Workflows.WorkflowTemplate.ExternalId.

lostBlobsRefundinteger nullable

Net buzz refunded for deliverable blobs lost in the 2026-06-12 storage incident. Null = not yet checked, 0 = intact; a value > 0 also prevents re-charging on recovery.

deletedAtstring date-time nullable

Soft delete: the telemetry document is kept until its TTL for operators, but consumer reads treat the workflow as gone.

downloadPriority'high' | 'normal' | 'low' | 'idle'
tier'paid' | 'free' required

How a workflow is paid for.

Example response

{
  "callbacks": [
    {
      "type": [
        "workflow:succeeded"
      ]
    }
  ]
}

Changes

  • 48103e81ab94Revision changes
    • info

      added liveTextToSpeech promptModeration discriminator mapping keys to the / request property (media type: application/json)

    • info

      added liveTextToSpeech promptModeration discriminator mapping keys to the / request property (media type: text/json)

    • info

      added liveTextToSpeech promptModeration discriminator mapping keys to the / request property (media type: application/*+json)

    • info

      added liveTextToSpeech promptModeration discriminator mapping keys to the / response property for the response status

    • info

      added liveTextToSpeech promptModeration discriminator mapping keys to the / response property for the response status

  • e3d4f2c08853Revision changes
    • warning

      added the new idle enum value to the response property for the response status

    • warning

      added the new idle enum value to the response property for the response status

    • warning

      added the new idle enum value to the //// response property for the response status

    • warning

      added the new idle enum value to the //// response property for the response status

    • warning

      added the new idle enum value to the // response property for the response status

    • warning

      added the new idle enum value to the // response property for the response status

    • info

      added the new optional request property (media type: application/json)

    • info

      added the new optional request property (media type: text/json)

    • info

      added the new optional request property (media type: application/*+json)

    • info

      added liveTranscription merge discriminator mapping keys to the / request property (media type: application/json)

    • info

      added liveTranscription merge discriminator mapping keys to the / request property (media type: text/json)

    • info

      added liveTranscription merge discriminator mapping keys to the / request property (media type: application/*+json)

    • info

      added the new idle enum value to the request property (media type: application/json)

    • info

      added the new idle enum value to the request property (media type: text/json)

    • info

      added the new idle enum value to the request property (media type: application/*+json)

    • info

      added the new idle enum value to the request property // (media type: application/json)

    • info

      added the new idle enum value to the request property // (media type: text/json)

    • info

      added the new idle enum value to the request property // (media type: application/*+json)

    • info

      added liveTranscription merge discriminator mapping keys to the / response property for the response status

    • info

      added liveTranscription merge discriminator mapping keys to the / response property for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status