Codex API Reference Guide

API Architecture and Design Principles

The Codex API is built on three principles: predictability, discoverability, and fault tolerance. If you have integrated with a modern REST API before, you already understand the patterns.

All API endpoints live under https://api.codex.gr.com/v1/. The base URL is fixed and does not vary by plan or region. Resources are named as plural nouns: /v1/generations, /v1/reviews, /v1/projects. Actions that do not fit CRUD semantics use a verb suffix: /v1/generations/:id/retry, /v1/reviews/:id/approve. Request bodies are JSON; responses are JSON. Timestamps use ISO 8601 in UTC. IDs are opaque strings (k-sortable UUIDv7) — you should treat them as atomic values and never parse structure from them. Pagination uses cursor-based traversal with starting_after and ending_before parameters; each response includes a has_more boolean and the cursor for the next page. The API never returns more than 100 items per page. If a request would produce a response larger than 10 MB, the API returns a 413 status and asks you to paginate with smaller page sizes.

Authentication uses bearer tokens passed in the Authorization header. Every endpoint except the health check requires authentication. Tokens are scoped to a specific plan tier and inherit that tier's rate limits. The API supports personal access tokens for individual developers, OAuth 2.0 client credentials for service-to-service integrations, and SCIM-provisioned tokens for enterprise identity provider integration. All token types have identical capabilities — the difference is lifecycle management. Personal tokens are rotated manually from the dashboard. OAuth tokens follow the standard client credentials grant with configurable expiry. SCIM tokens are provisioned and revoked through your identity provider and never appear in the Codex dashboard.

Core API Endpoint Summary

The API surface is organized into seven resource groups. Each group follows consistent patterns for create, read, update, delete, and list operations.

Each endpoint group has a dedicated reference page with full request and response schemas. The table above provides the high-level routing structure. Generations and Reviews are the most frequently called endpoints — they handle the core AI operations. Projects maintains the semantic index and configuration that give Codex its contextual awareness. Webhooks and Keys manage integration infrastructure. Teams and Usage support administration and billing. The API is symmetric across plan tiers: Professional and Enterprise plans access the same endpoints with higher rate limits; the Starter plan has a subset of the Generations and Reviews endpoints with a tighter quota.

Authentication and API Key Management

Bearer tokens are the only authentication mechanism. They are simple, widely supported, and trivial to rotate.

Include your token in every request: Authorization: Bearer cdx_sk_a1b2c3d4e5f6.... Tokens begin with cdx_sk_ for secret keys (server-side use) or cdx_pk_ for publishable keys (client-side use with restricted permissions). Secret keys have full access to your account. Publishable keys can only call read-only endpoints and generation endpoints with a per-day quota — they are safe to embed in client-side applications. Generate keys from the Codex dashboard under Settings > API Keys. Each key has a name, creation date, last-used date, and a revoke button. Revocation is immediate and irreversible — all active requests using the revoked key will fail with a 401 status on their next API call. The API supports up to 25 active keys per account. For additional security, you can restrict a key to specific IP ranges using CIDR notation; requests from outside the allowed ranges receive a 403 status.

Rate Limiting and Quota Management

Rate limits protect the API from abuse and ensure fair resource distribution. They are tiered by plan, clearly communicated, and easy to handle gracefully.

Every API response includes four rate limit headers: X-RateLimit-Limit (your per-hour ceiling), X-RateLimit-Remaining (requests left in the current window), X-RateLimit-Reset (Unix timestamp when the window resets), and X-RateLimit-Used (requests consumed in the current window). When you exhaust your quota, the API returns a 429 Too Many Requests status with a Retry-After header indicating how many seconds to wait. The recommended client pattern is to read X-RateLimit-Remaining on each response and slow down preemptively when it drops below 10% of your limit. The official SDKs handle this automatically — they pause and retry with exponential backoff when a 429 is received. Enterprise plans can request custom rate limits; contact the sales team with your expected request volume and concurrency profile. Rate limits apply per API key, not per IP address, so load-balanced services sharing a key share a single quota pool.

Official SDKs and Client Libraries

Four languages, four SDKs, one consistent interface. Install the one that matches your stack and start calling the API in minutes.

The TypeScript SDK (npm install @codex/api) targets Node.js 18+ and modern browsers. It provides fully typed request and response objects, automatic pagination with async iterators, and a configurable retry policy. The Python SDK (pip install codex-api) targets Python 3.10+ and follows Pythonic conventions: snake_case parameters, context managers for sessions, and dataclass-based models. The Go SDK (go get github.com/codex/api-go) exposes a service struct with method-per-endpoint conventions and context-based cancellation. The Rust SDK (cargo add codex-api) provides async functions with tokio runtime support and serde-based serialization. All four SDKs are generated from the same OpenAPI specification, so they are functionally identical — the same parameter names, the same error types, the same pagination behavior. Community-maintained SDKs for Java, Ruby, and PHP are listed in the documentation with their maintenance status and test coverage links; they are not officially supported but are widely used and actively maintained.

Webhooks Overview and Event Types

Webhooks let Codex push events to your server in real time. Register an endpoint, subscribe to event types, and Codex delivers JSON payloads with signature verification.

Webhook subscriptions are managed through the /v1/webhooks endpoint or the dashboard. Each subscription specifies a URL, a list of event types, and an optional secret for HMAC-SHA256 signature verification. When an event fires, Codex POSTs a JSON payload to your URL within 500 milliseconds. The payload includes the event type, the resource ID, a timestamp, and the event data. Codex retries failed deliveries up to five times with exponential backoff (1 min, 5 min, 25 min, 2 hr, 6 hr). After the fifth failure, the endpoint is automatically disabled and you receive an email notification. The API exposes delivery history for the last 30 days, including HTTP status codes and response bodies. For high-throughput use cases, you can register up to 25 webhook endpoints per project. Event types span generation completion, review completion, project index updates, team membership changes, and key lifecycle events. The full event catalog is documented on the webhook system page.

Error Handling and Status Codes

The error format is consistent across every endpoint. A machine-readable code tells your integration what happened; a human-readable message tells a developer how to fix it.

All error responses have the same JSON structure: { "error": { "code": "rate_limit_exceeded", "message": "You have exceeded your rate limit. Retry after 42 seconds.", "doc_url": "https://codex.gr.com/documentation.html" } }. The code field is a snake_case string that your code can switch on — it never changes without a major API version bump. The message field is localized to the Accept-Language header you send (English by default). The doc_url points to the relevant troubleshooting section. Common error codes include authentication_required (401), permission_denied (403), resource_not_found (404), rate_limit_exceeded (429), validation_error (422), and internal_error (500). Validation errors include a details array with per-field error messages suitable for displaying inline in a form. The 500 error includes a request_id that you should include in support tickets for faster triage. Idempotency is supported on POST endpoints via the Idempotency-Key header — send the same key with retried requests and the API returns the original result instead of creating a duplicate resource.

Code Generation via the API

POST a description, a language, and optional context — get back production-ready code. It is the API equivalent of typing into the CLI or IDE plugin.

The POST /v1/generations endpoint accepts a JSON body with prompt (required, the natural language description), language (optional, inferred from project context if omitted), project_id (optional, for context-aware generation), and options (optional, controlling style, verbosity, and safety filters). The response includes code (the generated source), language (detected or specified), explanation (a paragraph describing the design decisions), confidence (a 0-1 score indicating model certainty), and warnings (an array of potential concerns like missing error handling or deprecated API usage). The generation is synchronous for prompts under 200 tokens and asynchronous for longer prompts — check the status field; if it is processing, poll GET /v1/generations/:id until it becomes completed. Completed generations are stored for 90 days and accessible via the API and dashboard history. Multi-file generation is supported through the POST /v1/generations/scaffold endpoint, which returns a ZIP archive of generated files with correct imports and directory structure.

Code Review via the API

Submit a diff, a file, or an entire repository snapshot — the review endpoint returns annotated issues ranked by severity with suggested fixes.

The POST /v1/reviews endpoint accepts code in three formats: a unified diff, a single file with path and content, or a repository snapshot with multiple files and their relationships. The response includes summary (a paragraph overview), issues (an array of findings with path, line range, severity, category, message, and suggested fix), and score (a 0-100 quality score). Issues are categorized as bug, security, performance, style, or maintainability. Each issue includes a confidence field so you can set a threshold — for CI/CD pipelines, you might only fail the build on issues with confidence above 0.85. The review endpoint supports streaming: set the Accept: text/event-stream header to receive issues as they are discovered rather than waiting for the full review to complete. This is useful for large codebases where a complete review might take 30-60 seconds; streaming delivers the first issues within 2-3 seconds.

Ingrid L. Sørensen, Senior Backend Architect at Polaris Networks in New York, described how her team built on the API: "We integrated Codex's API into our internal developer portal so that any engineer can trigger a full codebase review from a Slack slash command. The API's consistency made the integration straightforward — we spent more time designing the Slack message formatting than we did wiring up the API calls. The webhook system notifies our incident management channel when a review scores below 70, which has caught three potential production issues before deployment." Her team processes roughly 1,200 API calls per day through a single service account, well within the Professional tier's rate limits.

For deeper environmental integration, review the U.S. Digital Government API standards which provide complementary guidelines for building reliable API integrations at scale.