Skip to content

API_USAGE.md

Latest commit

 

History

History
147 lines (108 loc) · 3.67 KB

API_USAGE.md

File metadata and controls

147 lines (108 loc) · 3.67 KB
Raw

Codex API Wrapper Usage

Base URL:

http://localhost:3100

Authentication:

Authorization: Bearer local-dev-token

Health Check

curl http://localhost:3100/health

Expected response:

{"ok":true}

Run Codex

Endpoint:

POST /codex

Request fields:

  • prompt: required. The instruction sent to Codex CLI.
  • user: optional. User key for web-console grouping. Defaults to default.
  • sandbox: optional. read-only or workspace-write. Defaults to read-only.
  • model: optional. Passed to codex exec --model.
  • cwd: optional. Working directory passed to codex exec --cd.
  • timeoutMs: optional. Timeout in milliseconds.

If model is omitted, the wrapper uses your Codex CLI default. In the current local logs this default is gpt-5.5.

Common model choices:

Model When to use
gpt-5.5 Default recommendation for complex coding, long-context review, reasoning, and professional work.
gpt-5.5-pro Highest-effort work when quality matters more than latency/cost, if enabled for your account.
gpt-5.4 More affordable coding/professional work when gpt-5.5 is not necessary.
gpt-5.4-mini Lower latency and lower cost for routine prompts, summaries, and simple automation.
gpt-5.4-nano Cheapest/fastest lightweight calls where depth is not important.
gpt-5.1 Older coding/agentic workload option; prefer newer GPT-5.5 unless you need compatibility.
gpt-5-codex Coding-agent optimized model for Codex-like environments; availability depends on the provider/API surface.

Selection guidance:

  • Start with no model field, or use gpt-5.5, until you have a reason to change.
  • Use smaller variants such as gpt-5.4-mini or gpt-5.4-nano for high-volume, simple, latency-sensitive calls.
  • Use gpt-5.5 or gpt-5.5-pro for hard debugging, large code review, multi-file reasoning, and tasks where mistakes are expensive.
  • If a model name fails, check that your Codex CLI/provider account supports it.

PowerShell example:

curl -X POST http://localhost:3100/codex `
  -H "Content-Type: application/json; charset=utf-8" `
  -H "Authorization: Bearer local-dev-token" `
  -d "{\"user\":\"alice\",\"prompt\":\"Reply with exactly: OK\",\"sandbox\":\"read-only\",\"timeoutMs\":180000}"

Python example:

import requests

response = requests.post(
    "http://localhost:3100/codex",
    headers={"Authorization": "Bearer local-dev-token"},
    json={
        "user": "alice",
        "model": "gpt-5.5",
        "prompt": "Reply with exactly: OK",
        "sandbox": "read-only",
        "timeoutMs": 180000,
    },
    timeout=240,
)
response.raise_for_status()
print(response.json()["stdout"])

Successful response shape:

{
  "stdout": "OK\n",
  "stderr": "...tokens used\n12345\n",
  "exitCode": 0,
  "timedOut": false
}

Web Console Records

Open:

http://localhost:3100/?token=local-dev-token

Records are grouped by:

user -> half-hour session

Example:

alice
  API Calls 2026-05-29 11:00

default
  API Calls 2026-05-29 10:30

If user is omitted in the API request, the record is stored under default. Old records without a user are also shown under default.

Each assistant message shows its token count when available. Each session shows the accumulated token total.

Sandbox Notes

Use read-only for inspection, Q&A, summaries, and safe analysis.

Use workspace-write only when the caller intentionally wants Codex to create or modify files in the target workspace.

Do not expose this local API directly to the public internet without stronger authentication and network controls.