HTTP API
Look up the hosted gate and document service, with authentication, routes, request and response examples, and error codes.
Look up the hosted gate and document service.
The gate decides tool calls and keeps the record. The document service turns policy documents into draft contracts. coco connect prints both addresses and writes them to coco.yaml as gate.url and policy.url.
The examples use COCO_GATE_URL, COCO_POLICY_URL, and COCO_API_KEY.
Gate
Authentication
| Caller | Sends | Can |
|---|---|---|
| Agent | Authorization: Bearer coco_live_... or coco_test_..., or X-Coco-Key. | Ask for verdicts, read its project's rules, and poll or withdraw its own escalations. Never approve. |
| Reviewer | Authorization: Bearer <Firebase ID token>, and ?project=P on the request. Must belong to the project. | List, approve, and reject escalations, read receipts, and check the chain. |
| Installer | The key as the Basic password, with any user name. | Use the package index. |
A key not bound to a project names one in X-Coco-Project, or without the header reaches its account's only project. An account with none or several returns 401, asking for coco connect --project <id>. A key bound to one project refuses a header naming another.
Routes
| Route | Caller | What it does |
|---|---|---|
POST /v1/check | Agent | Decides one proposed call. |
GET /v1/rules | Agent | Returns the project's mode, limits, contracts, and free checks left. |
GET /v1/escalations/{id} | Agent | Polls one escalation. |
POST /v1/escalations/{id}/withdraw | Agent | Closes it as rejected, with {"reason"}. |
GET /v1/escalations?project=P | Reviewer | Returns pending escalations. |
POST /v1/escalations/{id}/approve?project=P | Reviewer | Approves. {"reason"} is optional. |
POST /v1/escalations/{id}/reject?project=P | Reviewer | Rejects. {"reason"} is required. |
GET /v1/receipts?project=P&limit=&verdict= | Reviewer | Returns receipts, newest first. |
GET /v1/ledger/verify?project=P | Reviewer | Runs the chain check. |
GET /v1/sdk/simple/ | Any key | The package index's root listing (PEP 503). |
GET /v1/sdk/simple/{name}/ | Any key | A package's files. |
GET /v1/sdk/files/{path} | Any key | One file. |
GET /health | Anyone | Returns ok, database, classifier, and platform. |
GET / redirects to the interactive API docs at /docs.
POST /v1/check
Call this before your application runs the tool, then act on effect:
curl -s -X POST "$COCO_GATE_URL/v1/check" \
-H "Authorization: Bearer $COCO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "payments.send",
"args": {"amount": 25000, "payee": "Sunrise Capital"},
"state": {"approved_payees": ["Sunrise Capital"]},
"session_id": "run-42",
"agent": {"id": "payments-agent"},
"call_id": "call-2"
}'| Field | Required | Description |
|---|---|---|
action | Yes | The contract action, up to 200 characters. |
args | No | The arguments the model proposed. |
state | No | Facts from your systems of record, which rules read as state.*. |
session_id | No, default | The conversation. Give each its own, or counts and totals are shared. |
agent | No | The agent's identity. |
call_id | No | Ties a retry to its escalation. |
conversation | No | Recent messages, {role, content}, for judge checks. |
tool | No | name, description, schema, and impact, for a tool no contract governs. |
A call escalated by a contract returns this shape:
{
"verdict": "ESCALATE",
"effect": "escalate",
"mode": "enforce",
"reason": "Above the auto-release limit",
"action": "payments.send",
"rule": {"id": "payments.send_limit", "version": 1},
"deciding_check": "under_limit",
"checks": [
{
"contract": "payments.send_limit",
"version": 1,
"id": "under_limit",
"stage": "constraint",
"result": "fail",
"observed": 25000,
"verdict": "ESCALATE",
"reason": "Above the auto-release limit",
"shadow": false,
"kind": "rule",
"judge": null,
"obligations": {"approver_role": "Level 2 manager"}
}
],
"audit_id": 2,
"receipt_hash": "sha256:<64 hex characters>",
"escalation": {
"id": "ESC-001",
"seq": 1,
"receipt_id": 2,
"session_id": "run-42",
"call_id": "call-2",
"action": "payments.send",
"reason": "Above the auto-release limit",
"status": "pending",
"decided_by": null,
"decision_reason": null,
"created_at": "2026-11-09T01:15:01Z",
"decided_at": null
},
"impact": null,
"obligations": {"approver_role": "Level 2 manager"}
}effect | Your application |
|---|---|
run | Runs the tool. In Monitor, this includes calls with verdict DENY or ESCALATE. |
deny | Doesn't run the tool, and gives the model reason. |
escalate | Waits: polls the escalation, or listens on your webhook. |
Each result in checks is pass, fail, skipped, or error. shadow is true for a contract in testing. Polling an escalated call again, with the same session and call id, is free.
Keep in mind: If the gate doesn't answer, fail closed and treat it as DENY.
GET /v1/rules
Read the project's settings:
curl -s "$COCO_GATE_URL/v1/rules" -H "Authorization: Bearer $COCO_API_KEY"{
"project": "<project id>",
"mode": "monitor",
"ungoverned": "impact",
"limits": {},
"contracts": [],
"invalid": [],
"free_checks_remaining": 50
}invalid names contracts the gate skips because they don't parse. free_checks_remaining is null when the gate charges nothing.
Escalations
GET /v1/escalations/{id} returns the escalation object shown above. status moves from pending to approved or rejected, with decided_by, decision_reason, and decided_at.
When a project has a webhook, the gate posts each decision to it, so your application can resume at once:
{"type": "escalation_decided", "project": "<project id>", "escalation": {"id": "ESC-001", "status": "approved"}}Package index
The index takes the key as the Basic password with any user name. Bearer and X-Coco-Key work too. A package outside the published list returns 404. For details, see How the package index works.
Errors
Errors are {"detail": "..."}.
| Status | When | Example detail |
|---|---|---|
| 400 | A package file path with .., an empty segment, or a scheme. | |
| 401 | No key, or a key the gate doesn't know. | unknown or revoked key, send a key or token as Authorization: Bearer <value>, an agent authenticates with a project API key |
| 401 | A key that reaches no single project. | this key is not bound to a project and its account has several; name one with coco connect --project <id> (sent as X-Coco-Project) |
| 401 | A key bound to another project than the header names. | this key belongs to another project |
| 402 | Free checks spent and no plan in good standing. Nothing is recorded. | Your free checks are used up. Choose a plan on https://app.trustcoco.ai/settings (Billing) to keep enforcing. |
| 403 | A reviewer not on the project. | <email> is not a reviewer of <project> |
| 404 | No such escalation, project, or package. | no escalation ESC-999 |
| 409 | Deciding an escalation already decided. | ESC-001 is already approved |
| 422 | An invalid body, or a rejection with no reason. | a rejection needs a reason |
| 502, 503 | The package index's upstream failed, or no index is configured. |
The Python and TypeScript clients turn any failure on a check into DENY, with the detail in the reason.
Limits and pagination
- Rate limits: The gate sets no per-key rate limit. Use is bounded by your account's checks.
- Receipts:
GET /v1/receiptstakeslimitfrom 1 to 1000, default 50, newest first, andverdictto filter. There's no cursor. - Conversation: Read for judge checks only. The clients send the last 12 messages.
From the SDKs
Python:
from coco_sdk.project import load
decision = load().engine().check("payments.send", {"amount": 25000, "payee": "Sunrise Capital"},
session_id="run-42", call_id="call-2")TypeScript:
const decision = await coco.enforce({
action: "payments.send", args: { amount: 25000, payee: "Sunrise Capital" }, sessionId: "run-42", callId: "call-2",
});Document service
coco policy upload does all of this for you. Use the API to build your own upload flow.
Authentication
A caller is a project key (Authorization: Bearer coco_live_... or coco_test_...) or a person with a Firebase ID token. A person names the project as project_id in the register body, and as ?project= or X-Coco-Project on every other call, and must belong to the account owning it. A document or job of another project returns 404. Errors are {"detail": ...}.
The flow
Register, upload, complete, and poll:
# 1. Register. The answer holds document_id and a signed upload URL.
curl -s -X POST "$COCO_POLICY_URL/v1/documents" \
-H "Authorization: Bearer $COCO_API_KEY" -H "Content-Type: application/json" \
-d '{"filename": "policy.pdf", "content_type": "application/pdf", "size_bytes": 182044}'
# 2. Upload the bytes to upload.url, with Content-Type set to upload.content_type.
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @policy.pdf
# 3. Complete. The answer holds job_id.
curl -s -X POST "$COCO_POLICY_URL/v1/documents/$DOCUMENT_ID/complete" -H "Authorization: Bearer $COCO_API_KEY"
# 4. Poll until status is COMPLETED, REVIEW_REQUIRED or FAILED.
curl -s "$COCO_POLICY_URL/v1/policy-jobs/$JOB_ID" -H "Authorization: Bearer $COCO_API_KEY"A job goes QUEUED, PROCESSING, then COMPLETED, REVIEW_REQUIRED, or FAILED. COMPLETED covers a report of VERIFIED or FLAGGED. REVIEW_REQUIRED means no rule was kept.
Document service routes
| Route | What it does |
|---|---|
GET /v1/models | Returns {"default", "models": [{"id", "provider", "policy_model", "vision_model", "key_env", "available", "note"}]}: the model presets offered, in order. |
POST /v1/documents | Registers filename, content_type (PDF or DOCX, matching the extension), size_bytes (up to 50 MiB), and optional policy_name, temporary_storage (false), publish_contracts (true), project_id, and model (a preset id). Returns 201 with document_id, project_id, status, and upload (method, url, expires_in_seconds, content_type). An unknown model is 422, naming the ones offered. One the service can't run is 409. |
PUT to upload.url | Sends the bytes, with Content-Type set to upload.content_type and no Authorization header. |
POST /v1/documents/{id}/complete | Checks the object's size and type, and queues the job. Returns 202 with job_id. Idempotent. |
GET /v1/documents?limit= | Returns the project's documents, newest first, each with its job. limit from 1 to 500, default 50. |
GET /v1/documents/{id} | Returns one document and its job. |
DELETE /v1/documents/{id} | Deletes the source, every artifact, and the policy version. The document's row, marked deleted, its job, and its review issues stay. 409 while the job runs. |
GET /v1/policy-jobs/{id} | Returns status, model, attempts, error_message, processing_report, review_issues, artifacts, contracts (what was written), and timestamps. |
GET /v1/policy-jobs/{id}/output | Returns the canonical policy as JSON and YAML, with its policy set and version. Nulls unless COMPLETED. |
GET /v1/policy-jobs/{id}/artifacts | Returns the artifact tree, each with an expiring download url. |
GET /v1/policy-jobs/{id}/artifacts/{path} | Returns one artifact. |
GET /v1/policy-jobs/{id}/contracts | Returns the drafts, each with published: written, updated, kept, or null. |
POST /v1/policy-jobs/{id}/retry | Queues a FAILED or REVIEW_REQUIRED job again, with optional body {"model": ...}. 409 when the source was deleted. |
GET /health | Returns ok, database, store, platform, and run_jobs. |
GET / redirects to the interactive API docs at /docs.