API authorization and rules.
Keys, capabilities, errors, pagination and idempotency.
Address and authorization
This deployment's API address: https://ctx4.me/v1. Console and connections. The CONTEXT4_API_KEY variable holds your secret server-environment key; the documentation does not substitute it.
curl "https://ctx4.me/v1/identity" \
-H "Authorization: Bearer $CONTEXT4_API_KEY"A key is issued in the console and displayed once. Its format is ctx4_<env>_<secret>. A key is scoped to an organization, workspace and set of capabilities. A resource belonging to another tenant returns 404 not_found. The required capability for each method appears in the reference.
| Capability | Purpose |
|---|---|
tools:read | Tools and HTTP method catalog |
executions:read, executions:write | Read and create executions; proxy also requires write |
connections:read, connections:write | Connections, auth configs and sources |
connections:manage | Additional permission to manage other users' connections within a tenant; requires connections:write |
tool-sessions:read, tool-sessions:write | Tool sessions |
syncs:read, syncs:write | Syncs and exports |
events:read, events:write | Events and subscriptions |
A missing capability produces 403 capability_missing. An ordinary key does not gain permission to change another user's connection merely by having connections:write. MCP OAuth does not delegate connections:manage.
The interface is intended for server use. CORS is not enabled for /v1, /mcp or compat. Do not put a bearer key in browser code, a URL or a public repository.
Request bodies and identifiers
Send JSON with Content-Type: application/json. The input body limit is 65,536 bytes. Headers and the request line are bounded by the listener; a long vendor URL may be rejected before routing.
X-Request-Id is optional: it accepts 1–128 characters matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}. Without it, the server generates a UUID. An invalid value is rejected with 422; the response includes a new safe request ID. Store X-Request-Id and the execution ID for diagnosis.
Idempotency and retries
Send Idempotency-Key when declared in the method's parameters. Its value is 8–128 characters from [A-Za-z0-9._:-]. Repeating the same request with the same key returns the original result; a changed body with the previous key produces 409 idempotency_conflict. Choose a new key for a new intentional operation.
202 when creating an execution means acceptance or a recorded refusal, not a successful provider change. Read status, denial_code and the address in Location, then poll the execution. Do not automatically repeat a write after a timeout: it may have been applied.
The current idempotency_conflict does not distinguish an in-progress request from a mismatched body; it does not promise Retry-After. Check the original request and operation state. Mirror API and raw proxy are not idempotent: each call may send a new request to the provider.
Pagination
Lists use opaque cursor and next_cursor. Pass the returned cursor unchanged until null; do not construct it from an ID. The general limit is 1–100, default 20; the reference lists each method's exact parameters and constraints. A cursor is limited to 400 characters. Keep filters unchanged between pages.
Vendor pagination is a separate provider contract: see paging in the endpoint descriptor. A Context4 cursor does not imply automatic retrieval of all upstream pages.
Errors and limits
Platform errors return application/problem+json with type, code, title, status, request_id. Exact enums and fields: Problem. Internal causes and credentials are not exposed to the client.
| HTTP | Client action |
|---|---|
| 400 | Correct parameters or body; check the schema |
| 401 | Check the key, expiry and revocation |
| 403 | Check capabilities, ownership, policy and session restrictions |
| 404 | Check the ID and access scope |
| 409 | Check version, account or idempotency key conflicts |
| 429 | Respect Retry-After if returned |
| 500 | Save the request ID for support |
| 503 | Check service availability; a write retry requires checking its outcome |
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset describe the API key's minute window; reset is the number of seconds until reset. If Redis is unavailable, writes fail closed with 503; reads may continue without rate-limit headers. Execution quota and HTTP request rate limits are separate checks.