> ## Documentation Index
> Fetch the complete documentation index at: https://headgate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Control API

> Operate queues, jobs, policies, workers, schedules, and workflows over one versioned contract.

The control API is shared by the embedded web console and external operator tooling. Rust
and Go servers implement the same OpenAPI contract and the conformance suite compares
their status codes, headers, and raw response bytes.

The API is mounted at:

```text theme={"system"}
/api/v1
```

## Safety defaults

* Job lists use opaque keyset cursors. Queues, workers, schedules, partitions, and
  quarantine use a bounded `limit` (maximum 200) plus a numeric cursor returned in the
  `x-next-cursor` response header. Redis discovers these collections with bounded
  `SSCAN`, never a blocking `SMEMBERS`.
* Job payloads are omitted unless `include_payload=true` is requested and allowed.
* Mutating requests require `Idempotency-Key`.
* Explicit-ID actions are bounded; selector-based bulk actions run asynchronously.
* Counts and history use maintained aggregates rather than queue-depth scans.
* Unsupported backend capabilities are discoverable through `GET /meta`.

## Operator-first endpoints

| Endpoint | Purpose |
| - | - |
| `GET /jobs/{id}/admission` | Explain the policy currently preventing a job from running. |
| `GET /jobs/{id}/checkpoint` | Explicitly inspect resumable steps, cursor state, and per-step crashes. |
| `GET /cluster` | Show capacity, utilization, and queues with no live workers. |
| `GET /rate-classes` | Inspect fleet-wide token budgets and waiting jobs. |
| `GET /queues/{queue}/history` | Graph arrival, drain, depth, and policy rejection trends. |
| `GET /periodic/{id}/enqueue-events` | Audit each automatic schedule tick. |
| `GET /events` | Stream shared control-plane changes over SSE. |

<Tip>
  Open the **API Reference** tab in the top navigation for parameters, schemas, response
  bodies, and the interactive playground generated from the canonical specification.
</Tip>

## Enqueue over HTTP

Polyglot producers can submit work without a native SDK:

```bash theme={"system"}
curl --request POST http://127.0.0.1:8080/api/v1/jobs \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: invoice-9481' \
  --data '{
    "kind": "billing:charge",
    "schema_version": 1,
    "payload": "eyJpbnZvaWNlX2lkIjo5NDgxfQ==",
    "queue": "billing",
    "partition_key": "tenant-acme"
  }'
```

The idempotency key protects a retried HTTP request from creating a second logical job.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.