API reference

TinyConductor has two REST APIs. Start with the Orchestration API v2: it is the primary API for new clients and covers the whole engine, from deploying and starting processes to identity and tenant administration. The REST API v1 serves existing v1 clients and adds the history, analytics, audit, console and system routes.

Reference	What it covers
Orchestration API v2 (primary)	Process instances, deployments, process definitions, element instances, variables, user tasks, jobs, messages, signals, incidents, decisions, resources, the Embedded clock, and identity and tenant administration, under `/v2/…`
REST API v1	The v1 surface under both `/v1/…` and `/api/v1/…`, plus history, analytics, audit, console, health, metrics and the Embedded and Bundled engine routes

Every operation has its own page, with a link you can share. Each page shows:

the method and path, and a ready-to-run request as cURL, JavaScript or Java (the samples call http://localhost:8080, the quickstart address);
Available in: the deployment modes that serve the operation;
Auth: whether it needs credentials, which kinds, and the action the caller must hold;
the parameters and request body, with an example, then the success response and, folded underneath, the error responses.

The search box finds operations by name, path or description. A running engine also serves its v1 document at GET /openapi.yaml (public). Which versions each surface is compatible with is stated in Compatibility.

Every operation in every mode

All three deployment modes — Embedded, Bundled and Cluster — are served by one route layer. Every operation in both references works in every mode; the modes differ only in durability, latency, capacity and tenancy. Each operation carries x-tinyconductor-modes, which is supported for all three modes except on the short list below.

Mode-specific routes exist for one mode only:

Route	Served by	Why
`GET /v1/embedded/records`	Embedded	Every record the in-memory test engine has written, for test assertions
`POST /v1/embedded/reset`	Embedded	Removes every deployment, instance and record and sets the clock back to its fixed starting time
`GET /v1/embedded/clock`, `POST /v1/embedded/clock/freeze`, `POST /v1/embedded/clock/advance-by`, `POST /v1/embedded/clock/advance-to`	Embedded	The virtual clock; Bundled and Cluster use the real clock
`PUT /v2/clock`, `POST /v2/clock/reset`	Embedded	The v2-compatible form of the virtual clock

Shared routes one mode cannot serve:

Route	Refused by	Why
`GET /api/v1/analytics/reports`	Embedded	Reports need durable storage, which Embedded mode does not have
`GET /api/v1/analytics/process-definitions/{key}/reports`	Embedded	As above

A refused route answers 501 with the problem type urn:bpm:error:mode-not-supported, the mode in mode and the reason in detail — never a silent 404. The console (/console) is outside the API reference. So is GET /metrics: Bundled and Cluster serve it on a metrics port of its own (9090), and the API port answers 404 there.

Task lists

The v2 user-task operations (/v2/user-tasks/…) are a complete task-list API: a per-user search with filters, sort and paging, a task’s form, variables and audit log, and the claim, assign, update and complete commands. Building an external task list walks through them.

Authentication

Every route that reads or changes engine state needs Authorization: Bearer <token> — a static credential, a token the engine issued at /oauth/token, or an access token from your identity provider — or a signed-in console session. GET /livez, GET /healthz, GET /readyz, GET /openapi.yaml and the /auth/* endpoints are public. A principal that may act in several tenants names the tenant of each request in X-Tenant-Id. See Identity and access for roles, grants and the permission each route requires (listed per operation as x-tinyconductor-action).

An Embedded engine started without credentials is anonymous and answers local callers only; see Embedded mode.

Errors

Errors are RFC 7807 application/problem+json documents whose type is a urn:bpm:error:* URN, for example:

`type`	Meaning
`urn:bpm:error:unauthorized`	No valid credential (`401`)
`urn:bpm:error:forbidden`	The caller lacks the permission the route requires (`403`)
`urn:bpm:error:not-found`	No such entity or route, or an entity the principal may not see (`404`)
`urn:bpm:error:invalid-argument`	The request is malformed (`400`)
`urn:bpm:error:mode-not-supported`	The route exists but this deployment mode does not serve it (`501`, names the `mode`)
`urn:bpm:error:unavailable`	A component the route needs is not available (`503`)
`urn:bpm:error:quota-exhausted`	The tenant reached one of its limits; `detail` names it. Retry after the `Retry-After` delay (`429`)
`urn:bpm:error:payload-too-large`	The request is larger than the engine accepts (`413`)
`urn:bpm:error:tenant-limit-exceeded`	The request goes over one of the tenant’s size limits; `detail` names it, and nothing was changed (`413`)
`urn:bpm:error:backpressure`	The tenant’s searches are too far behind; retry after the `Retry-After` delay with the same idempotency key (`503`)
`urn:bpm:error:partition-moved`	The tenant moved to another partition while the request was on its way; send it again (`409`)
`urn:bpm:error:partition-unavailable`	The tenant’s partition cannot serve at the moment (for example while it reloads); retry after the `Retry-After` delay with the same idempotency key (`503`)
`urn:bpm:error:tenant-unavailable`	The tenant is quarantined after a fault; an operator releases it (`503`)

Retrying a request

A request that changes state may carry an Idempotency-Key header (at most 200 bytes). When its answer never arrives (a timeout, a dropped connection, a 503 saying the outcome is unknown), send the same request again with the same key. If the engine applied it the first time, the retry gets that first answer, even when the task, job or instance has moved on or finished since: completing a user task twice with one key answers 204 both times, not 404 the second time. The same key on a different request answers 409. The engine remembers a key for 24 hours by default (CONDUCTOR_DEDUP_RETENTION).

Keys

Entity keys are 64-bit integers. Responses encode them as decimal strings so that JavaScript clients keep full precision; send them back as strings.