Local API documentation

Connect AI Proxy API

Readable endpoint docs plus importable OpenAPI and Postman exports. No local secrets are embedded; examples use variables such as {{proxyApiKey}}.
OpenAPI JSONPostman collectionControl panel
Base URL: https://ai-api1.cus.cx

Authentication

Proxy endpoints accept x-api-key, anthropic-api-key, api-key, or Authorization: Bearer {{proxyApiKey}}. Admin endpoints use the ccp_admin_session cookie created by /ui/api/auth/setup or /ui/api/auth/login.

Documentation

GET /docs

Read local API documentationPublic local

Human-readable documentation generated from the same manifest as the OpenAPI and Postman exports.

Response example

<!doctype html>...

GET /openapi.json

Download OpenAPI documentPublic local

OpenAPI 3.0.3 JSON for Postman, Swagger UI, and other API tools.

Response example

{
  "info": {
    "title": "Connect AI Proxy API"
  },
  "openapi": "3.0.3"
}

GET /postman.json

Download Postman collectionPublic local

Postman Collection v2.1 export generated from the local API documentation manifest.

Response example

{
  "info": {
    "name": "Connect AI Proxy API"
  }
}

Public

GET /health

Check proxy healthPublic local

Returns whether the local process is reachable and whether proxy endpoints are currently enabled.

Response example

{
  "ok": true,
  "proxy_running": true
}

GET /antigravity/bridge

Open Antigravity browser bridge probePublic local

Serves the local HTML page used by the browser extension bridge for a safe wake and connection probe.

Response example

<!doctype html>...

Anthropic-compatible

GET /anthropic/v1/models

List Claude-compatible model aliasesProxy API key

Lists model aliases exposed through the Anthropic-compatible namespace.

Headers: anthropic-version.

Response example

{
  "data": [
    {
      "display_name": "sonnet[1m]",
      "id": "sonnet[1m]",
      "type": "model"
    }
  ],
  "object": "list"
}

GET /anthropic/v1/model-capabilities

List Claude-compatible model token limitsProxy API key

Lists exposed model aliases with upstream model ids, the active context window, maximum input budget, and maximum output tokens.

Headers: anthropic-version.

Response example

{
  "data": [
    {
      "context": "200k",
      "context_window_tokens": 200000,
      "display_name": "sonnet[1m]",
      "id": "sonnet[1m]",
      "limits_known": true,
      "limits_source": "built_in",
      "max_input_tokens": 72000,
      "max_output_tokens": 128000,
      "type": "model_capability",
      "upstream_model": "gpt-5.5"
    }
  ],
  "object": "list",
  "units": "tokens"
}

POST /anthropic/v1/messages

Create a Claude-compatible messageProxy API key

Accepts Claude Messages API style requests, then routes them to Codex or an OpenAI-compatible provider. Streaming is supported with server-sent events.

Headers: anthropic-version, X-Proxy-Session-Id.

Request example

{
  "max_tokens": 256,
  "messages": [
    {
      "content": "Say hello in one sentence.",
      "role": "user"
    }
  ],
  "model": "{{model}}",
  "stream": false
}

Response example

{
  "content": [
    {
      "text": "Hello from the proxy.",
      "type": "text"
    }
  ],
  "id": "msg_local",
  "model": "{{model}}",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

POST /anthropic/v1/messages/count_tokens

Estimate Claude-compatible input tokensProxy API key

Returns a local approximate input token count for a Claude Messages API style request.

Headers: anthropic-version.

Request example

{
  "messages": [
    {
      "content": "Quick count test",
      "role": "user"
    }
  ],
  "model": "{{model}}"
}

Response example

{
  "input_tokens": 14
}

OpenAI-compatible

GET /openai/v1/models

List OpenAI-compatible model aliasesProxy API key

Lists model aliases exposed through the OpenAI-compatible namespace.

Response example

{
  "data": [
    {
      "display_name": "gpt-5.5",
      "id": "gpt-5.5",
      "type": "model"
    }
  ],
  "object": "list"
}

GET /openai/v1/model-capabilities

List OpenAI-compatible model token limitsProxy API key

Lists exposed model aliases with upstream model ids, the active context window, maximum input budget, and maximum output tokens.

Response example

{
  "data": [
    {
      "context": "200k",
      "context_window_tokens": 200000,
      "display_name": "gpt-5.3-codex",
      "id": "gpt-5.3-codex",
      "limits_known": true,
      "limits_source": "built_in",
      "max_input_tokens": 72000,
      "max_output_tokens": 128000,
      "type": "model_capability",
      "upstream_model": "gpt-5.3-codex"
    }
  ],
  "object": "list",
  "units": "tokens"
}

POST /openai/v1/chat/completions

Create an OpenAI-compatible chat completionProxy API key

Accepts OpenAI Chat Completions style requests. The proxy either forwards to a provider route or converts to Codex Responses internally.

Headers: X-Proxy-Session-Id.

Request example

{
  "max_completion_tokens": 256,
  "messages": [
    {
      "content": "Say hello.",
      "role": "user"
    }
  ],
  "model": "{{model}}",
  "stream": false
}

Response example

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Hello from the proxy.",
        "role": "assistant"
      }
    }
  ],
  "created": 1767225600,
  "id": "chatcmpl_local",
  "model": "{{model}}",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 6,
    "prompt_tokens": 12
  }
}

POST /openai/v1/responses

Create an OpenAI-compatible responseProxy API key

Accepts OpenAI Responses API style requests. The local Codex route disables storage and can map stable session ids to local prompt cache keys.

Headers: X-Proxy-Session-Id.

Request example

{
  "input": [
    {
      "content": "Say hello.",
      "role": "user"
    }
  ],
  "model": "{{model}}",
  "stream": false
}

Response example

{
  "id": "resp_local",
  "model": "{{model}}",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "text": "Hello from the proxy.",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "type": "message"
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

GET /openai/v1/files

List provider filesProxy API key

OpenAI-compatible provider pass-through. Requires the default upstream to be OpenAI-compatible or the client key to route to a provider key.

Query: limit, after, purpose.

Response example

{
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "purpose": "assistants"
    }
  ],
  "object": "list"
}

POST /openai/v1/files

Upload a provider fileProxy API key

OpenAI-compatible multipart file upload pass-through.

Request form data

purpose = assistants
file = <nil>

Response example

{
  "id": "file-abc123",
  "object": "file",
  "purpose": "assistants"
}

GET /openai/v1/files/{path...}

Retrieve a provider file pathProxy API key

OpenAI-compatible provider pass-through for nested file paths such as file metadata or file content.

Path: path.

Response example

{
  "id": "file-abc123",
  "object": "file"
}

DELETE /openai/v1/files/{path...}

Delete a provider file pathProxy API key

OpenAI-compatible provider pass-through for file deletion where the upstream provider supports it.

Path: path.

Response example

{
  "deleted": true,
  "id": "file-abc123",
  "object": "file"
}

Admin auth

GET /ui/api/auth/status

Check admin login statusPublic local

Returns whether local admin auth is configured and whether the current browser session is authenticated.

Response example

{
  "authenticated": true,
  "configured": true,
  "username": "admin"
}

POST /ui/api/auth/setup

Create local admin loginPublic local

Creates the first local admin login. Fails once admin auth is already configured.

Request example

{
  "password": "{{adminPassword}}",
  "username": "{{adminUsername}}"
}

Response example

{
  "message": "Admin login configured.",
  "ok": true
}

POST /ui/api/auth/login

Log in to the admin UIPublic local

Sets the local admin session cookie when the credentials are valid.

Request example

{
  "password": "{{adminPassword}}",
  "remember": true,
  "username": "{{adminUsername}}"
}

Response example

{
  "ok": true
}

POST /ui/api/auth/logout

Clear admin sessionPublic local

Expires the local admin session cookie.

Response example

{
  "ok": true
}

Admin control panel

GET /ui/api/status

Get dashboard statusAdmin session cookie

Returns runtime status, local and public URLs, model rows, auth metadata, dashboard metrics, and the latest request summary.

Response example

{
  "anthropic_url": "https://proxy.example.com/anthropic",
  "display_url": "https://proxy.example.com",
  "local_url": "http://127.0.0.1:4000",
  "openai_url": "https://proxy.example.com/openai/v1",
  "proxy_running": true,
  "public_url": "https://proxy.example.com",
  "running": true,
  "update": {
    "current_version": "0.4.3",
    "latest_version": "0.4.4",
    "running": false,
    "update_available": true
  },
  "upstream": "codex",
  "version": "0.4.3"
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

GET /ui/api/update/status

Get update statusAdmin session cookie

Returns the installed version, latest GitHub version check, auto-update setting, and the last dashboard-started update status.

Response example

{
  "auto_update": false,
  "current_version": "0.4.3",
  "latest_version": "0.4.4",
  "running": false,
  "state": "idle",
  "update_available": true
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/update/check

Check for updatesAdmin session cookie

Refreshes the configured VERSION URL and returns the current update status without starting an update.

Response example

{
  "message": "Update check complete.",
  "ok": true,
  "update": {
    "current_version": "0.4.3",
    "latest_version": "0.4.4",
    "update_available": true
  }
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/update/start

Start non-interactive updateAdmin session cookie

Starts update-linux.sh in the background with a status file so the dashboard can reconnect after the service restarts.

Response example

{
  "message": "Update started.",
  "ok": true,
  "update": {
    "running": true,
    "state": "queued"
  }
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/update/settings

Save update settingsAdmin session cookie

Saves automatic-update, branch, VERSION URL, repository path, status-file path, and full-system updater options.

Request example

{
  "auto_update": true,
  "branch": "main",
  "full_system_update": false,
  "repo_dir": "/root/claude-code-proxy",
  "status_file": "/opt/connect-ai-proxy/.proxy.update.json",
  "version_url": "https://raw.githubusercontent.com/xMed-Jordan/claude-code-proxy/main/VERSION"
}

Response example

{
  "auto_update": true,
  "full_system_update": false,
  "ok": true,
  "update": {
    "auto_update": true
  }
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

GET /ui/api/config

Read editable proxy configAdmin session cookie

Returns .env-backed configuration values for the control panel. Secret-looking values are masked in config fields.

Response example

{
  "aliases": [],
  "config": {
    "OPENAI_BASE_URL": "https://api.openai.com/v1",
    "PROXY_API_KEY": "sk-...abcd"
  },
  "secrets": {
    "PROXY_API_KEY": "{{proxyApiKey}}"
  }
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/config

Save editable proxy configAdmin session cookie

Persists selected .env values and model aliases. Restart the proxy to apply process-level settings.

Request example

{
  "aliases": [
    {
      "Context": "1m",
      "From": "sonnet[1m]",
      "To": "gpt-5.5"
    }
  ],
  "config": {
    "OPENAI_BASE_URL": "https://api.openai.com/v1"
  }
}

Response example

{
  "message": "Configuration saved. Restart proxy to apply changes.",
  "ok": true
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

GET /ui/api/models

List model aliasesAdmin session cookie

Response example

{
  "models": [
    {
      "alias": "sonnet[1m]",
      "context": "1m",
      "real": "gpt-5.5"
    }
  ]
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/models

Save model aliasesAdmin session cookie

Request example

{
  "models": [
    {
      "alias": "sonnet[1m]",
      "context": "1m",
      "real": "gpt-5.5"
    }
  ]
}

Response example

{
  "message": "Model aliases saved and active for new requests.",
  "models": [
    {
      "alias": "sonnet[1m]",
      "context": "1m",
      "real": "gpt-5.5"
    }
  ],
  "ok": true
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

GET /ui/api/keys

List provider and client keysAdmin session cookie

Response example

{
  "clients": [],
  "defaults": {
    "anthropic_base": "https://proxy.example.com/anthropic",
    "openai_local_url": "https://proxy.example.com/openai/v1"
  },
  "providers": []
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/keys/provider

Create or renew a provider keyAdmin session cookie

Request example

{
  "api_key": "{{providerApiKey}}",
  "base_url": "https://api.openai.com/v1",
  "label": "OpenAI key",
  "provider": "openai"
}

Response example

{
  "clients": [],
  "message": "Provider key saved.",
  "ok": true,
  "providers": []
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/keys/client

Create a local client API keyAdmin session cookie

Request example

{
  "label": "Postman",
  "provider": "default",
  "provider_key_id": "",
  "schema": "both"
}

Response example

{
  "api_key": "{{proxyApiKey}}",
  "clients": [],
  "message": "Client key created. Copy it now; it will not be shown again.",
  "ok": true,
  "providers": []
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/keys/toggle

Enable or disable a keyAdmin session cookie

Request example

{
  "enabled": true,
  "id": "{{clientKeyId}}",
  "kind": "client"
}

Response example

{
  "clients": [],
  "ok": true,
  "providers": []
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

GET /ui/api/validate

Run local validation checksAdmin session cookie

Response example

{
  "duration_total": 123,
  "model": "sonnet[1m]",
  "ok": true,
  "ran_at": "12:00:00",
  "steps": [
    {
      "name": "GET /anthropic/v1/models",
      "ok": true,
      "status": 200
    }
  ],
  "upstream_model": "gpt-5.5"
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/test

Send a quick test promptAdmin session cookie

Request example

{
  "model": "{{model}}",
  "prompt": "Reply with only OK.",
  "stream": false
}

Response example

{
  "duration_ms": 450,
  "raw": "{\"type\":\"message\"}",
  "status": 200,
  "text": "OK"
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

GET /ui/api/logs

Read local logsAdmin session cookie

Response example

{
  "rows": [],
  "stderr": "",
  "stdout": "",
  "trace": ""
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

GET /ui/api/antigravity

Read browser bridge statusAdmin session cookie

Response example

{
  "available": true,
  "last_action": "browser_status",
  "mode": "dedicated"
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/antigravity/probe

Record browser bridge probe dataAdmin session cookie

Request example

{
  "source": "postman",
  "url": "http://127.0.0.1:4000/antigravity/bridge"
}

Response example

{
  "ok": true,
  "probe": {
    "source": "postman"
  }
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/proxy/stop

Stop proxy endpointsAdmin session cookie

Response example

{
  "message": "Proxy endpoints stopped. Claude settings restored. Control panel remains online.",
  "ok": true,
  "running": false
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/proxy/start

Start proxy endpointsAdmin session cookie

Response example

{
  "message": "Proxy endpoints started. Claude settings applied.",
  "ok": true,
  "running": true
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.

POST /ui/api/proxy/restart

Restart proxy processAdmin session cookie

Response example

{
  "message": "Proxy restarting.",
  "ok": true
}

Admin routes require a valid local browser session cookie. In Postman, call the login endpoint first and let Postman store the cookie, or set {{adminSessionCookie}}.