---
url: /orchestration/reference.md
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# API Reference

Every consumer-facing operation, request schema, and response shape in the Civitai Orchestration API. Pages here are generated from a snapshot of the orchestration API's OpenAPI specification ([`v2-consumers.json`](/openapi/v2-consumers.json)), refreshed periodically.

## Conventions

* **Base URL**: `https://orchestration.civitai.com`
* **Auth**: `Authorization: Bearer <token>` on every request.
* **Content type**: `application/json` for bodies; blob upload endpoints accept `multipart/form-data` or presigned PUT.
* **IDs**: workflow IDs are ULIDs prefixed `wf_`; blob IDs are prefixed `blob_`.
* **Polymorphism**: workflow step bodies use a `$type` discriminator; request/response schemas list all valid subtypes under `oneOf`.

## Entry points

Most consumer integrations only touch three operations:

* [`SubmitWorkflow`](https://developer.civitai.com/orchestration/reference/operations/SubmitWorkflow.md) — create a workflow with one or more steps
* [`GetWorkflow`](https://developer.civitai.com/orchestration/reference/operations/GetWorkflow.md) — poll a single workflow
* [`QueryWorkflows`](https://developer.civitai.com/orchestration/reference/operations/QueryWorkflows.md) — list / filter workflows

The sidebar is grouped by OpenAPI tag. Recipes offer one typed endpoint per job type as an alternative to the polymorphic `SubmitWorkflow` body.

## Rate limits & quotas

Responses report the limits that apply to you in the `RateLimit-Policy` and `RateLimit` headers, using the named-policy syntax of the [IETF RateLimit header fields draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/). Each limit is one named entry:

```http
RateLimit-Policy: "buzz";q=1000;w=60
RateLimit: "buzz";r=940;t=12
```

| Parameter | Header | Meaning |
|-----------|--------|---------|
| `q` | `RateLimit-Policy` | Quota per window |
| `w` | `RateLimit-Policy` | Window length in seconds |
| `r` | `RateLimit` | Remaining quota in the current window |
| `t` | `RateLimit` | Seconds until the current window resets |

When a limit is exhausted the API responds with `429 Too Many Requests` and a `Retry-After` header giving the seconds to wait.

### Free tier

A limited set of models can be run without Buzz on a best-effort basis. [`GetFreeTier`](https://developer.civitai.com/orchestration/reference/operations/GetFreeTier.md) returns the models currently offered and your remaining quota for each. To opt in:

* set `"tier": "free"` on [`SubmitWorkflow`](https://developer.civitai.com/orchestration/reference/operations/SubmitWorkflow.md)
* add `?tier=free` to a recipe endpoint
* send `X-Civitai-Tier: free` on the OpenAI-compatible chat completions endpoint

Free work is scheduled behind paid work and expires if it cannot be served in time. Each free request uses quota when it is accepted, whether or not it later succeeds. Every step in a free workflow must use a model offered on the free tier; otherwise the request is rejected with `400`. On free requests, each quota also appears as its own entry in the `RateLimit` headers.