# API reference

Every public endpoint of the Contexory API, with the scope each one needs. This page is generated from the OpenAPI spec, which you can download and feed to a client generator.

Source: <https://www.contexory.com/docs/reference/api>

## Base URL and spec

Send requests to `https://api.contexory.com`. Until that host is live, the Agents and Ingest paths are also served by `https://sync.contexory.com` without the `/api` prefix.

The machine-readable spec is OpenAPI 3.1. [Download openapi.json](/docs/reference/api/openapi.json).

Every error response uses the envelope described on the [Errors](/docs/reference/errors) page and carries a `Request-Id` header.

## Credentials and scopes

Send a credential as `Authorization: Bearer $CONTEXORY_API_KEY`. Each operation names its scope in the spec as `x-contexory-scope`.

- **resolve**: a runtime key (`con_rt_`) or a delivery key. Read-only, limited to the agents you name.
- **deliveries:write**: a delivery key (`con_dl_`), kept in CI secrets only.
- **ingest:write**: an ingest key (`con_ing_`).
- **skills:read** and **skills:write**: a personal plugin token.

Operations in the Skills section are a preview. They are served today at the path in the last column and will move to the path shown.

The one limit enforced today is 300 requests a minute per IP, at the edge. A request it stops has no body in the error format and no `Retry-After`. Responses carry no `RateLimit-*` headers today; do not rely on them. See [Rate limits](/docs/reference/rate-limits).

## Agents

Resolve a release, record delivery receipts and report upstream tool hashes.

| Endpoint | Scope | Credential | Served at today |
| --- | --- | --- | --- |
| `GET /v1/agents/{slug}/resolve` | `resolve` | `runtimeKey or deliveryKey` | `/v1/agents/{slug}/resolve` |
| `POST /v1/agents/{slug}/deliveries` | `deliveries:write` | `deliveryKey` | `/v1/agents/{slug}/deliveries` |
| `POST /v1/agents/{slug}/upstream-hashes` | `ingest:write` | `ingestKey` | `/v1/agents/{slug}/upstream-hashes` |
| `GET /v1/signing-keys` | none | none | `/v1/signing-keys` |

## Ingest

Send OTLP/HTTP GenAI spans.

| Endpoint | Scope | Credential | Served at today |
| --- | --- | --- | --- |
| `POST /v1/ingest/v1/traces` | `ingest:write` | `ingestKey` | `/v1/ingest/v1/traces` |

## Skills

Read and write skills. Preview: not yet at these paths.

| Endpoint | Scope | Credential | Served at today |
| --- | --- | --- | --- |
| `GET /v1/me` | `skills:read` | `personalToken` | `/api/plugin/orgs` |
| `GET /v1/skills` | `skills:read` | `personalToken` | `/api/plugin/skills` |
| `POST /v1/skills` | `skills:write` | `personalToken` | `/api/plugin/skills` |
| `GET /v1/skills/{id}` | `skills:read` | `personalToken` | `/api/plugin/skills/{id}` |
| `PATCH /v1/skills/{id}` | `skills:write` | `personalToken` | `/api/plugin/skills/{id}` |
| `DELETE /v1/skills/{id}` | `skills:write` | `personalToken` | `/api/plugin/skills/{id}` |
| `GET /v1/skills/{id}/export` | `skills:read` | `personalToken` | `/api/plugin/skills/{id}/export` |
| `GET /v1/skills/{id}/files` | `skills:read` | `personalToken` | `/api/plugin/skills/{id}/files` |
| `GET /v1/skills/{id}/files/{path}` | `skills:read` | `personalToken` | `/api/plugin/skills/{id}/files/{path}` |
| `PUT /v1/skills/{id}/files/{path}` | `skills:write` | `personalToken` | `/api/plugin/skills/{id}/files/{path}` |
| `DELETE /v1/skills/{id}/files/{path}` | `skills:write` | `personalToken` | `/api/plugin/skills/{id}/files/{path}` |
| `GET /v1/skills/{id}/manifest` | `skills:read` | `personalToken` | `/api/plugin/skills/{id}/manifest` |
| `POST /v1/skills/{id}/publish` | `skills:write` | `personalToken` | `/api/plugin/skills/{id}/publish` |
| `POST /v1/skills/{id}/reviews` | `skills:write` | `personalToken` | `/api/plugin/skills/{id}/reviews` |