Reference
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.
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.
Every error response uses the envelope described on the 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.
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 |