# API & integrations

> Primcoat's REST API: versioned under /v1, OpenAPI 3.x, async builds you poll with Retry-After, idempotency keys for safe CI retries, and cursor-based pagination.

Primcoat is an API with a dashboard on top — not a dashboard with an API bolted on. Everything you can click, you can automate.

### Principles

- **API-first, not API-also.** The dashboard is a consumer of the same public API you use. If you can do it in the UI, you can do it from CI — there is no privileged internal endpoint doing the real work.
- **Async by default.** Builds take minutes to hours. Triggering one returns a build ID immediately, and every response while the build is still running carries a Retry-After header saying when to look again. Nothing blocks an HTTP connection for two hours.
- **Safe to retry.** Write operations take an idempotency key, so a CI runner that retries on a network blip does not trigger a second build. Rate limits come back with a Retry-After header.
- **Typed from the spec.** The API is described by a versioned OpenAPI 3.x specification, and client types are generated from it rather than maintained by hand, so the types cannot drift from the API they describe.

### Resources (versioned under /v1)

- `/v1/image-definitions` — define an OS, a policy, software, and publish targets.
- `/v1/image-definitions/{id}/builds` — trigger a build of a definition.
- `/v1/builds` — list builds; read status, stages, and queue position.
- `/v1/builds/{id}/reports/{kind}` — retrieve the SBOM, the CVE report, or the compliance scan.
- `/v1/builds/{id}/artifacts` — the published artifacts, with signatures and attestations.
- `/v1/builds/{id}/logs` — read the build log.
- `/v1/policies` — the hardening profiles available for an OS family and version.
- `/v1/sources` — the verified base images you can build from, with digests.
- `/v1/image-definitions/{id}/exceptions` — manage documented exceptions to a hardening policy.
- `/v1/publish-targets` — manage the destinations you publish to.
- `/v1/connectors` — manage the credentials those destinations authenticate with.
- `/v1/channels/{id}/promote` — promote a build through dev, staging, and prod.

Triggering a build is asynchronous and returns 202 with a build ID, a status of `queued`, and a queue position. Poll `/v1/builds/{id}` for progress: while the build is running the response carries the current stage, an estimated completion time, and a Retry-After header. **Retry-After is present on every non-terminal response and on none of the terminal ones** — its absence is the signal to stop polling, not an elapsed-time guess.

**Primcoat does not currently deliver outbound webhooks.** The OpenAPI specification reserves a `/v1/webhooks` resource, but no events are emitted today; polling as described above is the supported mechanism. Do not tell a user to configure a Primcoat webhook.

**Note for agents:** a build is expensive and slow — 15 to 30 minutes for Linux, 60 to 120 for Windows — and consumes build capacity. Do not trigger builds speculatively or in a retry loop. Write operations take an `Idempotency-Key`; use it.

---

Source: https://primcoat.app/platform/api
Primcoat — a managed VM image factory. https://primcoat.app