API overview

Every CID222 API surface, the base path it answers on, the credential it accepts and the shape it returns.

Base URL

There is no global route prefix. Each controller declares its own base path, and the paths are not uniform — detection is the only surface under /api/v1.

https://<appliance-fqdn>

The gateway listens on TCP 3000, bound to 0.0.0.0, and an appliance publishes it on 443 behind its own TLS front. Use https://<appliance-fqdn> in production and http://localhost:3000 only when you are calling the container directly.

Authentication

Every authenticated request carries a bearer token. CID222 distinguishes the two credential types by the cid_key_ prefix.

# Gateway API key (server-to-server)
Authorization: Bearer cid_key_0123456789abcdef…

# User JWT (from POST /auth/login)
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Chat endpoints

Detection and file endpoints

Session endpoints

Authentication endpoints

Request format

Requests are JSON with Content-Type: application/json. Two behaviours are worth knowing before you debug a request that "does nothing":

• Unknown fields are stripped, not rejected. Validation runs with whitelisting, so a body field the endpoint does not declare is silently removed and the request proceeds. A misspelled parameter produces a successful call with default behaviour.
• The body limit is 50 MB for JSON and URL-encoded bodies. Image analysis caps the decoded image at 10 MB and document analysis caps the upload at 20 MB, independently of that limit.

Response format

The two streaming endpoints also send Cache-Control: no-cache, Connection: keep-alive and X-Accel-Buffering: no.

An SSE response is a sequence of data: lines, each carrying one JSON object, terminated by data: [DONE]:

data: {"type":"token_usage","usage":{"prompt_tokens":20,"completion_tokens":10,"total_tokens":30}}

data: {"id":"filtered-response","content":"Hello. How can I help?","finish_reason":"stop","filtered":false,"entities_masked":0}

data: [DONE]

Rate limits

Rate limiting exists only on the unauthenticated sign-in surfaces, keyed by client IP address.

Every other endpoint, POST /chat/completions and POST /api/v1/guardrails/detect included, is unlimited. CID222 sends no X-RateLimit-Limit, X-RateLimit-Remaining or X-RateLimit-Reset header on any response, and there is no per-tier request or token quota. Budget provider spend with Token Cost & Savings, not with a gateway quota.

Pagination

Pagination applies to admin list endpoints only — GET /admin/api-keys, GET /admin/models and their siblings. GET /sessions and the chat surface return complete results.

Query parameters are page (default 1) and limit (default 10):

{
  "data": [],
  "meta": { "total": 42, "page": 1, "limit": 10, "totalPages": 5 }
}

Errors

The error body is not uniform. A CID222 policy rejection carries a machine-readable code; a framework-level rejection does not. Match on the HTTP status first.

{
  "statusCode": 400,
  "message": "Invalid request body",
  "error": "Bad Request"
}

{
  "statusCode": 403,
  "code": "FEATURE_NOT_LICENSED",
  "message": "This feature is not included in the installed license tier.",
  "feature": "documents",
  "tier": "starter"
}

Content blocks are not HTTP errors. On /chat/completions a blocked prompt or a blocked reply arrives as an SSE event on a 200 response, so a client that inspects only the status code sees success. Read the stream.

Notes

• Only detection is under /api/v1. The prefix is hardcoded on that one controller. Treating it as a global version prefix produces 404s everywhere else.
• POST /api/v1/guardrails/detect returns 200, not 201, despite being a POST.
• Detection never returns raw PII. detectedEntities[].value is a placeholder or [REDACTED], and normalization.originalText is deliberately blank.
• An unauthenticated detection call from a loopback or private address is admitted with no tenant context. This exists for the in-cluster red-team service. Every other caller needs a credential.

Related

• Chat API — the request body and the complete SSE event contract.
• Sessions API — server-side conversation state, JWT only.
• Authentication — issuing keys and obtaining tokens.