# OpenAPI specs

> Coho's two public APIs as OpenAPI 3.1: one to manage content, one to deliver it. Generate a client, explore them in a tool, or hand them to an agent.

The page: https://coho-cms.com/openapi/

## Management API

Everything a project holds: projects, branches, tags, environments, content types, entries, assets, diffs, merges, tokens, and webhooks. Authenticate with a person's access token or a project token, as a bearer token.

- **File:** [`management.yaml`](https://coho-cms.com/openapi/management.yaml), version 0.3.0
- **Server:** `https://api.coho-cms.com`
- **Size:** 63 paths, 90 operations
- **Used by:** The CLI, the management SDK, scripts, CI, and agents.

## Delivery API

Read-only delivery of released content, by environment or tag, with references resolved to a depth and one locale per response. Authenticate with a delivery key, from a server.

- **File:** [`delivery.yaml`](https://coho-cms.com/openapi/delivery.yaml), version 2.2.0
- **Server:** `https://delivery.coho-cms.com/v1/projects/{project}`
- **Size:** 4 paths, 4 operations
- **Used by:** Your site or app, at run time, and the delivery SDKs.

## How they relate

Content changes through the management API, on a branch, and reaches the delivery API when it is tagged and an environment points at the tag. Previews of a live environment are the one overlap: the management API serves them in the delivery API's shapes, under `/api/v1/accounts/{account}/projects/{project}/preview/`.

Both send errors as RFC 9457 problems with a stable `code` to branch on, and every problem's `type` is its code's page in the [error codes](https://coho-cms.com/errors/).

## Keeping up

Both are generated from the specs Coho's services are tested against, and a test fails when a generated file falls behind, so a changed route cannot leave its spec unchanged without anyone noticing. The URLs stay the same from release to release.