# 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/<id>.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
```
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".