Coco
Look something up

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

CallerSendsCan
AgentAuthorization: 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.
ReviewerAuthorization: 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.
InstallerThe 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

RouteCallerWhat it does
POST /v1/checkAgentDecides one proposed call.
GET /v1/rulesAgentReturns the project's mode, limits, contracts, and free checks left.
GET /v1/escalations/{id}AgentPolls one escalation.
POST /v1/escalations/{id}/withdrawAgentCloses it as rejected, with {"reason"}.
GET /v1/escalations?project=PReviewerReturns pending escalations.
POST /v1/escalations/{id}/approve?project=PReviewerApproves. {"reason"} is optional.
POST /v1/escalations/{id}/reject?project=PReviewerRejects. {"reason"} is required.
GET /v1/receipts?project=P&limit=&verdict=ReviewerReturns receipts, newest first.
GET /v1/ledger/verify?project=PReviewerRuns the chain check.
GET /v1/sdk/simple/Any keyThe package index's root listing (PEP 503).
GET /v1/sdk/simple/{name}/Any keyA package's files.
GET /v1/sdk/files/{path}Any keyOne file.
GET /healthAnyoneReturns 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"
  }'
FieldRequiredDescription
actionYesThe contract action, up to 200 characters.
argsNoThe arguments the model proposed.
stateNoFacts from your systems of record, which rules read as state.*.
session_idNo, defaultThe conversation. Give each its own, or counts and totals are shared.
agentNoThe agent's identity.
call_idNoTies a retry to its escalation.
conversationNoRecent messages, {role, content}, for judge checks.
toolNoname, 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"}
}
effectYour application
runRuns the tool. In Monitor, this includes calls with verdict DENY or ESCALATE.
denyDoesn't run the tool, and gives the model reason.
escalateWaits: 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": "..."}.

StatusWhenExample detail
400A package file path with .., an empty segment, or a scheme.
401No 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
401A 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)
401A key bound to another project than the header names.this key belongs to another project
402Free 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.
403A reviewer not on the project.<email> is not a reviewer of <project>
404No such escalation, project, or package.no escalation ESC-999
409Deciding an escalation already decided.ESC-001 is already approved
422An invalid body, or a rejection with no reason.a rejection needs a reason
502, 503The 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/receipts takes limit from 1 to 1000, default 50, newest first, and verdict to 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

RouteWhat it does
GET /v1/modelsReturns {"default", "models": [{"id", "provider", "policy_model", "vision_model", "key_env", "available", "note"}]}: the model presets offered, in order.
POST /v1/documentsRegisters 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.urlSends the bytes, with Content-Type set to upload.content_type and no Authorization header.
POST /v1/documents/{id}/completeChecks 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}/outputReturns the canonical policy as JSON and YAML, with its policy set and version. Nulls unless COMPLETED.
GET /v1/policy-jobs/{id}/artifactsReturns the artifact tree, each with an expiring download url.
GET /v1/policy-jobs/{id}/artifacts/{path}Returns one artifact.
GET /v1/policy-jobs/{id}/contractsReturns the drafts, each with published: written, updated, kept, or null.
POST /v1/policy-jobs/{id}/retryQueues a FAILED or REVIEW_REQUIRED job again, with optional body {"model": ...}. 409 when the source was deleted.
GET /healthReturns ok, database, store, platform, and run_jobs.

GET / redirects to the interactive API docs at /docs.


On this page