This service exposes a versioned HTTP adapter over the local Codex app-server. The stable surface for browser-based coding agents is under /api/v1. Search is enabled by default, managed projects resume the latest Codex thread for the same workspace, and approval-aware coding flows remain explicit rather than hidden.
Version: v1.0.25. Customer API authentication now treats the Codex API username as the bearer value. For example, a user named g2g-codex-example can call protected client endpoints with Authorization: Bearer g2g-codex-example. Existing generated API keys still work for backward compatibility, while admin-only routes still require an admin bearer key.
Authorization: Bearer g2g-codex-example. The username resolves to the user's active wallet key internally, so wallet balance, token usage, Stripe top-ups, and FUP checks stay attached to the correct account./api/v1, threads, turns, files, models, and read-only release endpoints for backward compatibility./api/codex/rpc, auth endpoints, raw event streams, system control, and other protected admin routes./admin → Access & Tokens.These examples automatically use the bearer value in the field above. When a client opens this page from the dashboard, that value is their Codex API username. Replace the prompt text and project names as needed.
Use the customer's Codex API username as CODEXAPI_CODEX_API_KEY with the official OpenAI package installed by npm install -g @openai/codex@latest. The API compatibility target is Codex CLI 0.130.0. Do not run codex login for CodexAPI.pro; configure CodexAPI.pro as a custom Responses provider and supply the username through CODEXAPI_CODEX_API_KEY.
If the user is already logged into OpenAI Codex, run the returned loggedInOverrideCommand or set CODEX_HOME="$HOME/.codexapi-codex". That isolates CodexAPI.pro config/history and makes this API override the existing logged-in profile for that command.
For non-interactive live-search runs, use codex --search exec .... The current official CLI rejects codex exec --search ....
The dashboard returns a token-specific command after creation; the generic provider shape is:
{
"providerId": "codexapi",
"providerName": "CodexAPI.pro",
"officialCliVersion": "0.130.0",
"officialInstallTag": "latest",
"officialInstallCommand": "npm install -g @openai/codex@latest",
"baseUrl": "https://codexapi.pro/v1",
"envKey": "CODEXAPI_CODEX_API_KEY",
"wireApi": "responses",
"model": "gpt-5.5",
"reasoningEffort": "medium",
"modelsUrl": "https://codexapi.pro/v1/models",
"responsesUrl": "https://codexapi.pro/v1/responses",
"codexHome": "$HOME/.codexapi-codex",
"configArgs": [
"-c 'preferred_auth_method=\"apikey\"'",
"-c 'model_provider=\"codexapi\"'",
"-c 'model_providers.codexapi.name=\"CodexAPI.pro\"'",
"-c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"'",
"-c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"'",
"-c 'model_providers.codexapi.wire_api=\"responses\"'",
"-c 'model_providers.codexapi.supports_websockets=false'",
"-c 'model_reasoning_effort=\"medium\"'"
],
"startCommand": "CODEXAPI_CODEX_API_KEY='<CODEXAPI_API_KEY>' codex --search -m gpt-5.5 -c 'preferred_auth_method=\"apikey\"' -c 'model_provider=\"codexapi\"' -c 'model_providers.codexapi.name=\"CodexAPI.pro\"' -c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"' -c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"' -c 'model_providers.codexapi.wire_api=\"responses\"' -c 'model_providers.codexapi.supports_websockets=false' -c 'model_reasoning_effort=\"medium\"'",
"execSmokeTestCommand": "CODEXAPI_CODEX_API_KEY='<CODEXAPI_API_KEY>' codex --search exec --skip-git-repo-check -m gpt-5.5 -c 'preferred_auth_method=\"apikey\"' -c 'model_provider=\"codexapi\"' -c 'model_providers.codexapi.name=\"CodexAPI.pro\"' -c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"' -c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"' -c 'model_providers.codexapi.wire_api=\"responses\"' -c 'model_providers.codexapi.supports_websockets=false' -c 'model_reasoning_effort=\"medium\"' \"Say hello from CodexAPI.pro.\"",
"loggedInOverrideCommand": "mkdir -p \"$HOME/.codexapi-codex\" && CODEX_HOME=\"$HOME/.codexapi-codex\" CODEXAPI_CODEX_API_KEY='<CODEXAPI_API_KEY>' codex --search -m gpt-5.5 -c 'preferred_auth_method=\"apikey\"' -c 'model_provider=\"codexapi\"' -c 'model_providers.codexapi.name=\"CodexAPI.pro\"' -c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"' -c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"' -c 'model_providers.codexapi.wire_api=\"responses\"' -c 'model_providers.codexapi.supports_websockets=false' -c 'model_reasoning_effort=\"medium\"'",
"loggedInOverrideExecSmokeTestCommand": "mkdir -p \"$HOME/.codexapi-codex\" && CODEX_HOME=\"$HOME/.codexapi-codex\" CODEXAPI_CODEX_API_KEY='<CODEXAPI_API_KEY>' codex --search exec --skip-git-repo-check -m gpt-5.5 -c 'preferred_auth_method=\"apikey\"' -c 'model_provider=\"codexapi\"' -c 'model_providers.codexapi.name=\"CodexAPI.pro\"' -c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"' -c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"' -c 'model_providers.codexapi.wire_api=\"responses\"' -c 'model_providers.codexapi.supports_websockets=false' -c 'model_reasoning_effort=\"medium\"' \"Say hello from CodexAPI.pro.\"",
"resumeLastCommand": "mkdir -p \"$HOME/.codexapi-codex\" && CODEX_HOME=\"$HOME/.codexapi-codex\" CODEXAPI_CODEX_API_KEY='<CODEXAPI_API_KEY>' codex resume --last --search -m gpt-5.5 -c 'preferred_auth_method=\"apikey\"' -c 'model_provider=\"codexapi\"' -c 'model_providers.codexapi.name=\"CodexAPI.pro\"' -c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"' -c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"' -c 'model_providers.codexapi.wire_api=\"responses\"' -c 'model_providers.codexapi.supports_websockets=false' -c 'model_reasoning_effort=\"medium\"'",
"windowsDependencyInstallCommand": "# Run PowerShell as Administrator for this dependency step.\nwinget source update\nwinget install --id OpenJS.NodeJS.LTS -e --accept-package-agreements --accept-source-agreements\nwinget install --id Git.Git -e --accept-package-agreements --accept-source-agreements\nSet-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force\n# Close PowerShell, open a new PowerShell window, then run the verification step.",
"windowsVerifyDependenciesCommand": "node --version\nnpm --version\ngit --version",
"windowsCodexInstallCommand": "npm install -g @openai/codex@0.130.0\ncodex --version",
"windowsFullInstallCommand": "# Run PowerShell as Administrator for this dependency step.\nwinget source update\nwinget install --id OpenJS.NodeJS.LTS -e --accept-package-agreements --accept-source-agreements\nwinget install --id Git.Git -e --accept-package-agreements --accept-source-agreements\nSet-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force\n# Close PowerShell, open a new PowerShell window, then run the verification step.\n\n# After reopening PowerShell:\nnode --version\nnpm --version\ngit --version\nnpm install -g @openai/codex@0.130.0\ncodex --version",
"windowsSetupCommand": "$env:CODEX_HOME = \"$HOME\\.codexapi-codex\"\nNew-Item -ItemType Directory -Force -Path $env:CODEX_HOME | Out-Null\n@'\nmodel = \"gpt-5.5\"\npreferred_auth_method = \"apikey\"\nmodel_provider = \"codexapi\"\nmodel_reasoning_effort = \"medium\"\n\n[model_providers.codexapi]\nname = \"CodexAPI.pro\"\nbase_url = \"https://codexapi.pro/v1\"\nenv_key = \"CODEXAPI_CODEX_API_KEY\"\nwire_api = \"responses\"\nsupports_websockets = false\n'@ | Set-Content -Path (Join-Path $env:CODEX_HOME \"config.toml\") -Encoding utf8",
"windowsStartCommand": "$env:CODEX_HOME = \"$HOME\\.codexapi-codex\"; $env:CODEXAPI_CODEX_API_KEY = '<CODEXAPI_API_KEY>'; codex --search -m gpt-5.5 -c 'preferred_auth_method=\"apikey\"' -c 'model_provider=\"codexapi\"' -c 'model_providers.codexapi.name=\"CodexAPI.pro\"' -c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"' -c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"' -c 'model_providers.codexapi.wire_api=\"responses\"' -c 'model_providers.codexapi.supports_websockets=false' -c 'model_reasoning_effort=\"medium\"'",
"windowsResumeLastCommand": "$env:CODEX_HOME = \"$HOME\\.codexapi-codex\"; $env:CODEXAPI_CODEX_API_KEY = '<CODEXAPI_API_KEY>'; codex resume --last --search -m gpt-5.5 -c 'preferred_auth_method=\"apikey\"' -c 'model_provider=\"codexapi\"' -c 'model_providers.codexapi.name=\"CodexAPI.pro\"' -c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"' -c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"' -c 'model_providers.codexapi.wire_api=\"responses\"' -c 'model_providers.codexapi.supports_websockets=false' -c 'model_reasoning_effort=\"medium\"'",
"windowsExecSmokeTestCommand": "$env:CODEX_HOME = \"$HOME\\.codexapi-codex\"; $env:CODEXAPI_CODEX_API_KEY = '<CODEXAPI_API_KEY>'; codex --search exec --skip-git-repo-check -m gpt-5.5 -c 'preferred_auth_method=\"apikey\"' -c 'model_provider=\"codexapi\"' -c 'model_providers.codexapi.name=\"CodexAPI.pro\"' -c 'model_providers.codexapi.base_url=\"https://codexapi.pro/v1\"' -c 'model_providers.codexapi.env_key=\"CODEXAPI_CODEX_API_KEY\"' -c 'model_providers.codexapi.wire_api=\"responses\"' -c 'model_providers.codexapi.supports_websockets=false' -c 'model_reasoning_effort=\"medium\"' \"Say hello from CodexAPI.pro.\"",
"configToml": "model = \"gpt-5.5\"\npreferred_auth_method = \"apikey\"\nmodel_provider = \"codexapi\"\nmodel_reasoning_effort = \"medium\"\n\n[model_providers.codexapi]\nname = \"CodexAPI.pro\"\nbase_url = \"https://codexapi.pro/v1\"\nenv_key = \"CODEXAPI_CODEX_API_KEY\"\nwire_api = \"responses\"\nsupports_websockets = false\n",
"clientModelLabel": "GPT-5.5",
"displayModel": "GPT-5.5",
"modelDisplayName": "GPT-5.5"
}
Windows users must use PowerShell syntax, not Bash exports. For a fresh Windows machine, run PowerShell as Administrator and install dependencies with winget install --id OpenJS.NodeJS.LTS -e and winget install --id Git.Git -e, then reopen PowerShell and install the pinned Codex CLI with npm install -g @openai/codex@0.130.0. Configure an isolated home with $env:CODEX_HOME = "$HOME\.codexapi-codex", set $env:CODEXAPI_CODEX_API_KEY, write config.toml, and start with codex --search -m gpt-5.5. The live /api/v1/cli/public-codex payload includes full Windows dependency, setup, start, resume, and smoke-test commands.
gpt-5.5mediumneverdanger-full-accesscodex app-server over stdio with the required initialize then initialized handshake.0.130.0 keeps legacy turn-level sandboxPolicy compatibility, while newer clients can send permissions / permissionProfile profile selections through the stable project endpoints or protected raw app-server RPC.experimentalApi during initialize, so the new /permissions Full Access client toggle can send permission profiles without being rejected by app-server.GET /api/v1/permissions publishes the Full Access and workspace profile payloads; GET /api/v1/skills lists the root Codex skills available to API-backed sessions.thread/goal/*, hooks/list, and modelProvider/capabilities/read are reachable through the protected raw RPC adapter. The stable browser-agent endpoints continue to stream the core thread, turn, item, and approval lifecycle.GET /api/v1/agent/status to inspect live runtime and defaults.POST /api/v1/projects to create a durable project workspace.POST /api/v1/projects/{project_id}/open to create or resume the workspace thread.POST /api/v1/projects/{project_id}/turns to start work.GET /api/v1/projects/{project_id}/events for SSE notifications.GET /api/v1/billing/token-usage to render wallet token transactions and daily usage graphs for the signed-in user.GET /api/v1/share-credit and POST /api/v1/share-credit/claim power the one-time $10 CodexAPI.pro share-credit dashboard offer.$5.00 per million tokens.$30.00 per million tokens.Each managed project_id maps to one stable workspace directory. When the same user returns to that project, the API resumes the latest Codex thread for that workspace instead of creating a fresh conversation.
Project-scoped approval handling stays explicit:
GET /api/v1/projects/{project_id}/approvals lists pending approval requests for the project’s latest thread.POST /api/v1/projects/{project_id}/approvals/{request_id}/resolve resolves the approval. An empty JSON body now defaults to {"decision":"accept"} for the current command and file-change approval flows.POST /api/v1/projects/{project_id}/turns/{turn_id}/interrupt interrupts a running turn.v1.0.25 # Changelog ## v1.0.25 - 2026-05-09 - Added an admin-only GPT-5.5 provider selector for the public Codex Responses gateway so new starts/resumes can use the selected GPT-5.5 route. - Added a compatible secondary GPT-5.5 execution route while keeping all client-facing setup and model labels under CodexAPI.pro GPT-5.5. - Added an admin model usage chart with provider/model request totals, token totals, and wallet deductions. - Updated token wallet billing to $5 per million input tokens and $30 per million output tokens for both providers. ## v1.0.24 - 2026-05-08 - Updated the CodexAPI.pro public Codex compatibility target to Codex CLI `0.129.0` and verified the host is already running `@openai/codex` `0.129.0` with current npm. - Enabled Codex app-server `experimentalApi` negotiation so `permissions` profile payloads used by the new `/permissions` Full Access client toggle are accepted. - Added `/api/v1/permissions` and `/api/v1/skills`, exposed root Codex skill availability in agent defaults, and made `CODEX_HOME=/root/.codex` explicit for the service. - Added Windows PowerShell-specific public Codex setup/start/resume/smoke-test command support for API users. ## v1.0.23 - 2026-05-04 - Rebuilt the CodexAPI.pro homepage around instant Codex CLI API access, current wallet packs, the $199 Unlimited Credit plan, Stripe top-ups, and resumable public Codex setup. - Added fresh SEO metadata, structured data, sitemap, robots file, and a new 1200x630 Open Graph image for Google, WhatsApp, Facebook, and other social previews. - Configured SMTP delivery for CodexAPI.pro and polished signup, wallet top-up, low-balance, and Unlimited fair-use email templates. ## v1.0.22 - 2026-05-04 - Repriced PAYG and top-up packs to the new wallet-credit values, including the private exit-intent $50 to $585 offer. - Added a vivid top-of-dashboard top-up panel, subscription card, and exit-intent offer modal for signed-in customers. - Added the $199 Unlimited Credit subscription flow with private fair-use enforcement and admin-adjustable 5-hour and 3-day limits. ## v1.0.21 - 2026-05-03 - Hardened Stripe wallet top-ups so paid Checkout sessions are reloaded from Stripe, fulfilled idempotently, and credited as soon as the webhook or return confirmation succeeds. - Preserved existing wallet API tokens during Stripe top-ups, low-balance SSO, and normal admin simulation so G2G buyers do not need to reconfigure Codex after adding credit. - Added direct client simulation controls to the admin Access & Tokens page. ## v1.0.20 - 2026-05-03 - Repaired legacy G2G wallet-token state so each buyer account has exactly one active buyer API token. - Hid expired/admin-impersonation tokens from buyer token summaries to avoid confusing G2G delivery credentials. - Hardened dashboard login token reuse so existing active wallet tokens are preferred over creating extra buyer tokens. - Kept the G2G creation success message visible after dashboard refresh so admins can see that the order was created. ## v1.0.19 - 2026-05-03 - Fixed G2G order creation so the admin page gives visible progress and creates a usable account from a single wallet-credit amount. - Stopped customer dashboard logins from issuing a new wallet API token every time; existing active wallet tokens are now reused. - Expanded the G2G delivery and token display areas so admins can read and copy the generated setup text without cramped fields. ## v1.0.18 - 2026-05-03 - Added a once-per-version release notes modal for admin and customer dashboard sessions. - Preserved direct admin section links after login and made Access & Tokens load independently of the full dashboard refresh. - Added wallet balances to the Access & Tokens API key list so admins can see remaining credit beside each token. ## v1.0.17 - 2026-05-02 - Corrected public Codex token billing so cumulative reported input context is stored separately and only newly added input tokens are charged. - Added token usage idempotency by response ID to prevent duplicate wallet deductions for the same completion. - Added billing regression coverage for the advertised `$2/M` input and `$15/M` output rates plus cumulative input delta handling. ## v1.0.16 - 2026-05-01 - Rebuilt G2G Codex delivery commands around one-time config-file setup blocks instead of long inline `-c` command strings. - Added separate Linux/macOS/WSL and Windows PowerShell G2G setup, start, resume, and smoke-test commands. - Updated the G2G admin command cards with exact-copy buttons and non-wrapping command rendering so marketplace delivery text stays executable. ## v1.0.15 - 2026-05-01 - Added plaintext token persistence for newly created managed API keys so admins can retrieve customer and G2G tokens after creation. - Updated the admin Access & Tokens and Customers & Wallets tables to show full stored tokens with copy controls instead of only prefixes. - Labeled legacy hash-only token rows clearly because older plaintext tokens cannot be reconstructed from their hashes. ## v1.0.14 - 2026-05-01 - Fixed the G2G Orders admin layout so the create form and delivery preview use the intended 5/7 grid split instead of collapsed single-column cards. - Added scrollable delivery and command previews so generated G2G instructions remain readable after token-filled commands are created. - Added a public favicon response and cleaned login autocomplete metadata to keep live browser verification free of avoidable console errors. ## v1.0.13 - 2026-05-01 - Added a dedicated admin G2G Orders workspace for one-click marketplace account delivery. - Stored G2G usernames and account notes on API users for future admin reference. - Rebuilt G2G delivery output with dashboard credentials, wallet details, and token-filled public Codex CLI commands split by state. ## v1.0.12 - 2026-05-01 - Updated the official public OpenAI Codex install command to `npm install -g @openai/codex@latest` across generated API payloads, docs, and customer-facing pages. - Updated the CodexAPI.pro public Codex compatibility target to Codex CLI `0.128.0`. - Reviewed the Codex `0.128.0` app-server protocol changes and documented the relevant additions: `permissions` profile selection, `thread/goal/*`, `hooks/list`, `modelProvider/capabilities/read`, and the continued stdio-first production transport. ## v1.0.11 - 2026-04-30 - Auto-issued wallet-linked API tokens when admins create API users. - Added one-click G2G marketplace account generation with paste-ready public Codex CLI delivery instructions. - Returned token-specific official public Codex setup, start, override, smoke-test, and resume commands with admin-created accounts. ## v1.0.10 - 2026-04-30 - Pinned customer-facing official OpenAI Codex CLI guidance for the then-current public Codex release. - Added a one-time $10 CodexAPI.pro share-credit offer for signed-in customer wallets. - Added live dashboard wallet refresh polling and share-credit status removal after claim. - Updated public SEO and Open Graph metadata for the CodexAPI.pro Codex API service. ## v1.0.9 - 2026-04-29 - Changed Codex token billing to micro-USD accounting at $2 per million input tokens and $15 per million output tokens. - Added token usage transactions with input tokens, output tokens, charged USD, and balance-after values. - Added a customer dashboard token usage list and daily usage graph. - Moved app-server token debits to turn completion so the wallet is charged after each completed prompt. ## v1.0.8 - 2026-04-29 - Integrated Modbot WhatsApp notifications for signup and wallet-balance thresholds. - Added required country and WhatsApp/mobile collection during first-time signup. - Added signed dashboard SSO links for notification-driven Stripe recharges. - Added matching formatted email notifications for WhatsApp notices. ## v1.0.7 - 2026-04-29 - Fixed public Codex token-usage billing so completed streams drain available wallet credit instead of silently skipping deduction when usage exceeds the remaining balance. - Added a preflight wallet check for `/v1/responses` so wallet-linked public Codex calls are blocked once a customer balance reaches zero. ## v1.0.6 - 2026-04-29 - Updated the public Codex startup commands shown on the client dashboard and install page. - Added logged-in OpenAI Codex override commands to the client dashboard so CodexAPI.pro API settings win for that run. - Hid register/login fields for signed-in dashboard users and added a visible logout button. ## v1.0.5 - 2026-04-29 - Corrected the official OpenAI `@openai/codex` CLI setup guide for CodexAPI.pro provider usage. - Added generated command variants that isolate CodexAPI.pro with `CODEX_HOME="$HOME/.codexapi-codex"` so existing OpenAI/ChatGPT Codex logins are overridden for that run. - Updated non-interactive examples to use `codex --search exec ...`, because the current official CLI rejects `codex exec --search ...`. ## v1.0.4 - 2026-04-29 - Added admin-created manual API tokens for the official OpenAI `@openai/codex` CLI provider flow. - Returned token-specific official Codex CLI install/start/smoke-test configuration when an admin creates a token. - Documented the manual-token workflow in `/api-docs` and the public Codex CLI guide. ## v1.0.3 - 2026-04-25 - Added admin-managed API users with username/password credentials and wallet balances stored in cents. - Added a configurable per-call USD price for wallet-linked managed API keys. - Added wallet charging for standard API calls made with user-linked managed API keys while leaving static tokens and unlinked keys unchanged. - Added admin dashboard controls for billing settings, API users, wallet balances, and assigning managed API tokens to billing users. ## v1.0.2 - 2026-04-16 - Added PostgreSQL-backed managed API keys that admins can create and revoke from the hosted admin dashboard. - Extended bearer authentication so managed `api` and `admin` keys work alongside the existing static environment tokens. - Expanded `/api-docs` into a verbose operator-facing guide with auth rules, defaults, project lifecycle notes, approval flow details, version display, and embedded agent reference material. - Displayed the running version and changelog directly on the admin dashboard and docs page. ## v1.0.1 - 2026-04-16 - Added the stable `/api/v1` project-scoped browser-agent surface for managed projects, turns, files, events, approvals, and resume behavior. - Added project-scoped approval and interrupt endpoints for browser coding clients. - Normalized managed sandbox policy values to the upstream Codex app-server wire enum format. ## v1.0.0 - 2026-04-16 - Published the HTTPS API and admin dashboard on `codexapi.pro`. - Integrated PostgreSQL-backed admin login. - Added public docs, release sync, security hardening, and the managed Codex app-server lifecycle API.
This catalogue is generated from the live FastAPI route table. public calls need no bearer token, api calls accept the Codex API username or a managed API key, and admin calls require an admin bearer key or admin session.
| Method | Path | Access | Tags | Summary |
|---|---|---|---|---|
GET | / | public | system | API root |
GET | /admin | public | - | admin_root |
GET | /admin/api/api-keys | public | - | admin_api_keys |
POST | /admin/api/api-keys | public | - | admin_create_api_key |
POST | /admin/api/api-keys/{key_id}/revoke | public | - | admin_revoke_api_key |
POST | /admin/api/auth/device/start | public | - | admin_device_start |
POST | /admin/api/auth/logout | public | - | admin_codex_logout |
GET | /admin/api/billing | public | - | admin_billing |
POST | /admin/api/billing/fup-settings | public | - | admin_update_subscription_fup_settings |
POST | /admin/api/billing/settings | public | - | admin_update_billing_settings |
GET | /admin/api/dashboard | public | - | admin_dashboard_data |
GET | /admin/api/email/templates | public | - | admin_email_templates |
POST | /admin/api/email/templates/test | public | - | admin_email_template_test |
GET | /admin/api/me | public | - | admin_me |
GET | /admin/api/model-provider | public | - | admin_model_provider |
POST | /admin/api/model-provider | public | - | admin_set_model_provider |
GET | /admin/api/model-usage | public | - | admin_model_usage |
GET | /admin/api/models | public | - | admin_models |
GET | /admin/api/pending-signups | public | - | admin_pending_signups |
POST | /admin/api/pending-signups/{application_id}/approve | public | - | admin_approve_pending_signup |
POST | /admin/api/pending-signups/{application_id}/reject | public | - | admin_reject_pending_signup |
GET | /admin/api/registrations | public | - | admin_registration_events |
POST | /admin/api/releases/sync | public | - | admin_release_sync |
POST | /admin/api/rpc | public | - | admin_rpc |
GET | /admin/api/server-requests | public | - | admin_server_requests |
GET | /admin/api/smtp/settings | public | - | admin_smtp_settings |
POST | /admin/api/smtp/settings | public | - | admin_update_smtp_settings |
POST | /admin/api/smtp/test | public | - | admin_test_smtp_settings |
POST | /admin/api/system/start | public | - | admin_system_start |
POST | /admin/api/system/stop | public | - | admin_system_stop |
GET | /admin/api/threads | public | - | admin_threads |
GET | /admin/api/users | public | - | admin_api_users |
POST | /admin/api/users | public | - | admin_create_api_user |
POST | /admin/api/users/g2g | public | - | admin_create_g2g_api_user |
DELETE | /admin/api/users/{user_id} | public | - | admin_delete_api_user |
POST | /admin/api/users/{user_id}/active | public | - | admin_set_api_user_active |
POST | /admin/api/users/{user_id}/impersonate | public | - | admin_impersonate_api_user |
POST | /admin/api/users/{user_id}/wallet | public | - | admin_update_api_user_wallet |
POST | /admin/api/users/{user_id}/wallet/credit | public | - | admin_adjust_api_user_wallet_credit |
GET | /admin/api/users/{user_id}/wallet/transactions | public | - | admin_api_user_wallet_credit_transactions |
POST | /admin/auth/login | public | - | admin_login |
POST | /admin/logout | public | - | admin_logout |
GET | /api-docs | public | - | api_docs |
POST | /api/auth/device/start | admin | auth | Start ChatGPT device-code login |
POST | /api/auth/logout | admin | auth | Log out the managed Codex account |
GET | /api/auth/status | admin | auth | Read current Codex auth/account state |
GET | /api/codex/events | admin | rpc | Stream Codex notifications over SSE |
POST | /api/codex/notify | admin | rpc | Send a Codex app-server notification |
POST | /api/codex/rpc | admin | rpc | Call a Codex app-server JSON-RPC method |
GET | /api/core/releases/current | api | releases | Read the current synced stable Codex release |
POST | /api/core/releases/sync | admin | releases | Sync the latest stable upstream Codex release |
GET | /api/models | api | rpc | List visible Codex models |
POST | /api/projects/open | api | threads | Open a project by cwd, resuming the latest matching thread when present |
GET | /api/server-requests | admin | rpc | List pending server-initiated approval requests |
POST | /api/server-requests/{request_id}/resolve | admin | rpc | Resolve a pending server-initiated request |
POST | /api/system/start | admin | system | Start managed Codex app-server |
GET | /api/system/status | admin | system | Get API runtime status |
POST | /api/system/stop | admin | system | Stop managed Codex app-server |
GET | /api/threads | api | threads | List Codex threads |
POST | /api/threads | api | threads | Start a new thread |
GET | /api/threads/{thread_id} | api | threads | Read a thread by id |
POST | /api/threads/{thread_id}/resume | api | threads | Resume an existing thread |
POST | /api/turns | api | turns | Start a new turn on a thread |
POST | /api/turns/{turn_id}/interrupt | api | turns | Interrupt an active turn |
GET | /api/v1/agent/status | api | agent | Read the managed Codex account state and default coding-agent configuration |
GET | /api/v1/auth/google/callback | public | auth | Complete Google sign-up or sign-in for a CodexAPI.pro wallet account |
GET | /api/v1/auth/google/start | public | auth | Start Google sign-up or sign-in for a CodexAPI.pro wallet account |
POST | /api/v1/auth/login | public | auth | Authenticate a CodexAPI.pro CLI user and issue a wallet-linked API key |
GET | /api/v1/auth/sso | public | auth | Open the customer dashboard from a signed notification link |
GET | /api/v1/billing/token-usage | api | billing | Read token usage transactions and daily spend for the current wallet |
GET | /api/v1/cli/public-codex | public | system | Read stock public Codex CLI connection settings for CodexAPI.pro |
GET | /api/v1/cli/version | public | system | Read the current CodexAPI.pro Codex CLI release metadata |
POST | /api/v1/customer/register | public | auth | Create a CodexAPI.pro customer account and issue a wallet-linked API key |
GET | /api/v1/me | api | auth | Read the current CodexAPI.pro customer wallet and CLI configuration |
POST | /api/v1/me/email | api | auth | Save the required customer email address for the current CodexAPI.pro wallet |
GET | /api/v1/permissions | api | agent | Read Codex permission profile presets for API clients |
GET | /api/v1/plans | public | billing | List CodexAPI.pro wallet credit plans |
POST | /api/v1/projects | api | projects | Create a managed project workspace for a web coding session |
GET | /api/v1/projects | api | projects | List managed isolated project workspaces |
GET | /api/v1/projects/{project_id} | api | projects | Read managed project metadata and its latest Codex thread summary |
GET | /api/v1/projects/{project_id}/approvals | api | agent | List pending approval requests for the latest managed project thread |
POST | /api/v1/projects/{project_id}/approvals/{request_id}/resolve | api | agent | Resolve a pending project-scoped approval request |
GET | /api/v1/projects/{project_id}/events | api | agent | Stream project-scoped Codex notifications over SSE |
GET | /api/v1/projects/{project_id}/files/content | api | projects | Read a file from a managed project workspace |
PUT | /api/v1/projects/{project_id}/files/content | api | projects | Write a file inside a managed project workspace |
GET | /api/v1/projects/{project_id}/files/tree | api | projects | List files inside a managed project workspace |
POST | /api/v1/projects/{project_id}/open | api | agent | Open or resume a managed project and optionally start an initial turn |
GET | /api/v1/projects/{project_id}/state | api | agent | Read project metadata, latest thread state, and pending project-scoped approvals |
GET | /api/v1/projects/{project_id}/thread | api | agent | Read the latest Codex thread for a managed project |
POST | /api/v1/projects/{project_id}/turns | api | agent | Start a project-scoped Codex turn using the web-coding defaults |
POST | /api/v1/projects/{project_id}/turns/{turn_id}/interrupt | api | agent | Interrupt an active turn for a managed project |
GET | /api/v1/share-credit | api | billing | Read the one-time CodexAPI.pro share-credit offer for the current wallet |
POST | /api/v1/share-credit/claim | api | billing | Claim the one-time CodexAPI.pro share credit after sharing the public site |
GET | /api/v1/skills | api | agent | List Codex skills available to API-backed Codex sessions |
POST | /api/v1/stripe/webhook | public | billing | Receive Stripe wallet payment events |
POST | /api/v1/wallet/auto-topup | api | billing | Configure automatic wallet top-up for the current CodexAPI.pro user |
POST | /api/v1/wallet/stripe/checkout | api | billing | Create a Stripe Checkout Session for a CodexAPI.pro wallet credit pack |
POST | /api/v1/wallet/stripe/confirm | api | billing | Confirm a paid Stripe Checkout Session and reconcile wallet credit |
POST | /api/v1/wallet/top-up | api | billing | Load credit onto the current CodexAPI.pro wallet after a plan payment |
GET | /favicon.ico | public | - | favicon |
GET | /health | public | system | Health check |
GET | /openapi.json | api | - | openapi |
GET | /v1/models | api | openai-compatible | List CodexAPI.pro models for stock public Codex CLI |
POST | /v1/responses | api | openai-compatible | Proxy stock public Codex CLI Responses API traffic through CodexAPI.pro wallet billing |
# Agent API v1
This document describes the stable `/api/v1` layer for a browser-based coding agent that uses the managed local Codex CLI runtime behind this service.
## Goal
The `/api/v1` layer is designed for an external web application or agentic LLM orchestration layer that needs to:
- create isolated coding projects
- resume a returning user's project history
- run Codex turns against a stable workspace
- stream live Codex events
- inspect the project file tree and file contents
It is an adapter over the existing `codex app-server` thread and turn model, not a replacement for it.
## Authentication
The hosted API accepts bearer tokens in two ways:
- static environment tokens configured on the server
- managed PostgreSQL-backed API keys created from the admin dashboard at `/admin`
Use standard API keys for the browser-agent surface. Use admin keys only when you need the privileged raw RPC, auth, or system-control endpoints.
## Defaults
Managed project runs default to:
- model: `gpt-5.5`
- effort: `medium`
- approval policy: `untrusted`
- sandbox mode on the API wire: `workspace-write`
- live web search: enabled globally by the managed Codex app-server process
- root machine skills: exposed through Codex `skills/list` and `GET /api/v1/skills`
These defaults can be overridden per request.
## Lifecycle
1. Read runtime status:
```http
GET /api/v1/agent/status
Authorization: Bearer <api-token>
```
Optional checks for the current permission and skill surfaces:
```http
GET /api/v1/permissions
Authorization: Bearer <api-token>
```
```http
GET /api/v1/skills
Authorization: Bearer <api-token>
```
2. Create a project:
```http
POST /api/v1/projects
Authorization: Bearer <api-token>
Content-Type: application/json
{
"name": "Landing Page Builder",
"ownerId": "user_123",
"template": "react"
}
```
3. Open or resume the project:
```http
POST /api/v1/projects/{project_id}/open
Authorization: Bearer <api-token>
Content-Type: application/json
{}
```
4. Subscribe to live events:
```http
GET /api/v1/projects/{project_id}/events?threadId=<thread_id>
Authorization: Bearer <api-token>
Accept: text/event-stream
```
5. Start a coding turn:
```http
POST /api/v1/projects/{project_id}/turns
Authorization: Bearer <api-token>
Content-Type: application/json
{
"prompt": "Build a polished SaaS landing page with pricing, testimonials, FAQ, and a contact form."
}
```
The `open` and `turns` responses include convenient top-level `threadId` and `turnId` fields in addition to the raw upstream payloads.
6. Rehydrate project state when the user returns:
```http
GET /api/v1/projects/{project_id}/state?includeTurns=true
Authorization: Bearer <api-token>
```
7. Surface and resolve approvals when Codex asks:
```http
GET /api/v1/projects/{project_id}/approvals
Authorization: Bearer <api-token>
```
```http
POST /api/v1/projects/{project_id}/approvals/{request_id}/resolve
Authorization: Bearer <api-token>
Content-Type: application/json
{}
```
## Resume Semantics
Managed project history is keyed by the managed workspace path for that project.
- each `project_id` maps to one stable `cwd`
- Codex session history remains attached to that `cwd`
- reopening the same project resumes the latest thread for that workspace
This means the browser agent does not need to track Codex session ids itself in the common case. It can treat `project_id` as the durable resume key.
## File Access
The file endpoints are intended for UI rendering and synchronization:
- `GET /api/v1/projects/{project_id}/files/tree`
- `GET /api/v1/projects/{project_id}/files/content?path=...`
- `PUT /api/v1/projects/{project_id}/files/content`
The tree endpoint is useful for explorer panels. The file-content endpoints are useful for editors, preview pipelines, and project snapshots.
## Approvals
Codex approvals remain part of the underlying app-server model.
- `approvalPolicy=untrusted` is the default for managed web-agent runs
- approval-bearing events continue to flow through the Codex notification stream
- project-scoped approval polling is available at `GET /api/v1/projects/{project_id}/approvals`
- project-scoped approval resolution is available at `POST /api/v1/projects/{project_id}/approvals/{request_id}/resolve`
- an empty JSON object is sufficient for a basic approval grant on the current file-change approval flow
## Full Access And Permissions
Codex CLI `0.129.0` accepts permission profile payloads only after the client
declares the `experimentalApi` capability during `initialize`. The adapter now
does this automatically.
Clients whose Full Access toggle lives under `/permissions` can read the exact
payload from:
```http
GET /api/v1/permissions
Authorization: Bearer <api-token>
```
For compatibility, managed project `open` and `turns` endpoints accept either
`permissions` or `permissionProfile`. Legacy clients can still use
`sandboxPolicy`.
## API Shape
The main endpoints a browser coding agent should bind to are:
- `GET /api/v1/agent/status`
- `GET /api/v1/permissions`
- `GET /api/v1/skills`
- `GET /api/v1/projects`
- `POST /api/v1/projects`
- `GET /api/v1/projects/{project_id}`
- `GET /api/v1/projects/{project_id}/state`
- `GET /api/v1/projects/{project_id}/thread`
- `POST /api/v1/projects/{project_id}/open`
- `POST /api/v1/projects/{project_id}/turns`
- `POST /api/v1/projects/{project_id}/turns/{turn_id}/interrupt`
- `GET /api/v1/projects/{project_id}/approvals`
- `POST /api/v1/projects/{project_id}/approvals/{request_id}/resolve`
- `GET /api/v1/projects/{project_id}/events`
- `GET /api/v1/projects/{project_id}/files/tree`
- `GET /api/v1/projects/{project_id}/files/content`
- `PUT /api/v1/projects/{project_id}/files/content`
If your frontend wants a richer approval UX, subscribe to the event stream and surface server requests explicitly.