# API Atlas — OpenAI + Anthropic (conventions for humans and agents)

Exhaustive, experimentally verified documentation of the public API surface of OpenAI and Anthropic. Machine-readable first: every important fact in docs/ must also exist in generated/ (JSON/CSV).

# Security (non-negotiable)

Keys live ONLY in .env (mode 600, gitignored). Never print, log, commit or paste them. Never put a key in a file under docs/, examples/, tests/, sources/, generated/, reports/.
Use source scripts/lib.sh (bash/zsh) → oai METHOD PATH [curl args], ant METHOD PATH [curl args] (auth injected, never printed), or python3 scripts/live.py helpers. Both mask sk-… patterns and auth headers in anything saved.
Raw live responses go to tmp-live/ (gitignored). Sanitized excerpts may be copied into docs.
Never run destructive Admin actions (delete users/keys/projects, rotate secrets). GET/LIST only.
Minimal payloads: "Reply with OK.", max_tokens/max_output_tokens ≤ 32, cheapest model of the family (OpenAI: gpt-5.4-nano/gpt-4.1-nano, Anthropic: claude-haiku-4-5-20251001) unless the feature requires another model. Log every live call with log_request (bash) or live.py (auto) → reports/live-requests.jsonl (ts, provider, method, path, status, est_cost_usd, note).

# Status vocabulary (use exactly these strings)

DOCUMENTED (in current official docs, not tested) · LIVE_DISCOVERED (seen via API, weak/absent docs) · LIVE_VERIFIED (called successfully with our key) · BETA · PREVIEW · LEGACY · DEPRECATED · RETIRED · ACCOUNT_RESTRICTED (documented; our key got 401/403/permission error) · UNVERIFIED · FAILED_VERIFICATION (tried; unexpected failure — record the reason). A record may carry several statuses (e.g. ["DOCUMENTED","BETA","LIVE_VERIFIED"]). A 403/404 with our key NEVER means "does not exist".

# Providers (4)

openai · anthropic · xai (Grok, https://api.x.ai, OpenAI-compatible surface + xAI-specific endpoints; Management API at https://management-api.x.ai needs a separate key we do NOT have) · gemini (Google Gemini Developer API, https://generativelanguage.googleapis.com/v1beta, key via x-goog-api-key header — never put the key in a URL). Helpers: xai/gemini in scripts/lib.sh, xai_request/gemini_request in scripts/live.py, pytest fixtures xai/gemini; cheap models: xAI grok-4.3 (note: every Grok call bills reasoning tokens; keep prompts tiny), Gemini gemini-3.5-flash-lite (2.5 models are "no longer available to new users" on this key). SDKs installed: .venv has xai-sdk 1.19 and google-genai 2.24; node_modules has @google/genai 2.23 (no official xAI Node SDK — use openai client with baseURL or raw fetch).

# Sources of truth (already downloaded, offline, grep them — do not re-fetch unless a page is missing)

xAI docs: sources/xai/pages/** (182 pages split from the official llms-full.txt: developers/** incl. rest-api-reference/, grpc-api-reference/, tools/, models/, pricing, rate-limits, release-notes; build/, grok/, grok-bot/, console/), manifest sources/xai/pages-manifest.json; official OpenAPI spec sources/xai/openapi/openapi.json (38 paths; op list openapi-ops.json); SDK: sources/xai/openapi/python-sdk-readme.md. Live: sources/xai/models-api-raw.json (12 ids), language-models-raw.json, image-generation-models-raw.json. Cite https://docs.x.ai/<path>.
Gemini docs: sources/gemini/pages/gemini-api/docs/** (guides) and sources/gemini/pages/api/** (REST reference pages, e.g. api/generate-content.md), manifest sources/gemini/pages-manifest.json; Google API discovery documents sources/gemini/openapi/discovery-v1beta.json (revision 20260918, 86 methods, full request/response schemas under schemas) + discovery-v1.json; extracted method list discovery-v1beta-methods.json; SDK types sources/gemini/openapi/python-genai-types.py (authoritative field names), READMEs. Live: sources/gemini/models-api-raw.json (58 models). Cite https://ai.google.dev/gemini-api/docs/<slug> or https://ai.google.dev/api/<slug> (drop the .md.txt).
OpenAI docs pages (Markdown twins): sources/openai/pages/api/docs/** (guides, models/.md, pricing, changelog, deprecations), reference: sources/openai/pages/api/reference/**; manifest sources/openai/pages-manifest.json. Combined export sources/openai/llms-full.txt (7.5 MB). Official OpenAPI spec: sources/openai/openapi/openapi-master.yaml (352 operations, extracted list openapi-master-ops.json). SDK surfaces: sources/openai/openapi/{python,node}-sdk-api.md.
Anthropic docs pages: sources/anthropic/pages/** (api/, build-with-claude/, agents-and-tools/, managed-agents/, models/, about-claude/, release-notes/**), manifest sources/anthropic/pages-manifest.json, combined sources/anthropic/llms-full.txt (35 MB, frontmatter title/url/description per page). SDK surfaces: sources/anthropic/openapi/{python,node}-sdk-api.md.
Live discovery: sources/openai/models-api-raw.json (136 ids), sources/anthropic/models-api-raw.json (11 ids).
Cite the canonical public URL (not the .md twin): OpenAI https://developers.openai.com/api/docs/... / https://developers.openai.com/api/reference/...; Anthropic https://platform.claude.com/docs/en/.... Every record has sources: [{url, retrieved_at}].

# Repository layout

text

docs/            human docs (Markdown). docs/openai/*, docs/anthropic/*, docs/models/*, docs/tools/*, docs/endpoints/*, docs/errors/*, docs/comparisons/*, docs/architecture/*, docs/security/*
generated/       merged machine-readable outputs (built by scripts/build_generated.py from generated/fragments/**)
generated/fragments/<domain>/*.json   ← agents write HERE only (never edit merged files by hand)
examples/<provider>/<area>/  runnable examples: *.sh (curl), *.py, *.ts — each header comment states STATUS and how verified
tests/<provider>/test_*.py   pytest smoke tests; expensive ones gated by RUN_*_TESTS env flags (see .env.example)
scripts/         crawl_docs.py, discover_models.py, live.py, lib.sh, build_generated.py, verify_links.py, update_atlas.py
sources/         downloaded official material (immutable inputs) + sanitized live discovery
reports/         live-requests.jsonl, changes.md, final-report.md, coverage
schemas/         JSON Schemas for every generated record type — validate fragments against them

# Record schemas (see `schemas/*.schema.json`; summary)

model: provider, id, display_name, aliases[], snapshots[], family, status[], release_date, knowledge_cutoff, context_window, max_output, modalities{input[],output[]}, capabilities{…booleans or "unknown"}, endpoints[], tools[], pricing{…}, rate_limits, beta_headers[], restrictions, availability{account, regions/clouds}, last_verified, verification{}, sources[]
endpoint: provider, api_family, method, path, name, description, status[], auth, beta_header, request{content_type, body_ref}, response{}, streaming{supported, events_ref}, pagination, idempotency, sdk{python, node}, verification{}, sources[]
parameter: provider, endpoint (e.g. POST /v1/messages), parameter (dotted path), location (body|query|path|header), type, required, default, minimum, maximum, enum[], description, compatible_models[], beta_header, status[], source
tool: provider, name, type (exact JSON type string, versioned), category (client|server|hosted|programmatic|mcp), description, compatible_models[], compatible_endpoints[], parameters_schema, tool_choice_support, parallel, streaming_events[], result_shape, billing, limitations, security, beta_header, status[], examples{curl,python,typescript}, verification{}, sources[]
streaming_event: provider, api, direction (server→client|client→server), event, description, schema, example, source
error: provider, http_status, type, code, message_semantics, retryable, recommended_action, source
header: provider, name, direction (request|response), required, description, example, source
price: provider, model_or_service, dimension (input|cached_input|output|…), price, currency (USD), unit (per 1M tokens | per image | per minute | per call | …), tier (standard|batch|priority|flex|fast), effective_notes, source, retrieved_at
example: provider, area, file, language, status (LIVE_VERIFIED|FAILED_VERIFICATION|UNVERIFIED), verified_at, notes
verification: {method: live_api|docs_only|sdk_types, verified_at, result: success|failure|restricted, http_status, request_note}

# Writing rules

French or English is fine in prose; identifiers, JSON keys and status strings are English.
Tables over prose for matrices. Every doc page starts with a status line + "Sources" list + "Last verified" date (2026-09-18 for this run).
Do not claim tested unless it ran. Record failures verbatim (sanitized).
Do not invent account-specific rate limits; separate "documented limits" from "observed headers".