# FAQ — answering the owner's questions from the atlas data (4 providers)

Status: every table on this page is computed from generated/*.json on 2026-09-18 (the jq/python used is shown so the answer can be re-derived after the next build); generator scripts/generators/synth/faq.py. Statuses are the record statuses. Where a question needs interpretation, the interpretation is stated. Providers: openai, anthropic, xai, gemini. Sources: generated/models.json, generated/tools.json, generated/parameters.json, generated/endpoints.json, generated/streaming-events.json, generated/webhook-events.json, generated/pricing.json, generated/fragments/headers/anthropic-beta-headers.json, generated/examples-manifest.json, plus the docs pages linked per answer. Last verified: 2026-09-18

Questions: 1 tool X + structured outputs + caching (Anthropic) · 2 image + reasoning + web search + streaming (OpenAI) · 2b the same combination on all four providers · 3 exact JSON for feature Y · 4 SSE / WebSocket events per call type · 5 endpoint that creates an agent session · 6 features needing a beta header / beta path · 7 which model supports combination Z · 8 which provider offers X and at what price · 9 where things live in the atlas

# Q1. Which Anthropic model accepts tool X with structured outputs and prompt caching?

Interpretation: model records where capabilities.structured_outputs_json, capabilities.strict_tool_use and capabilities.prompt_caching are all true, crossed with the versioned tool types listed in each model's tools[]. Retired ids excluded. All 13 active Claude models satisfy the SO + caching precondition, so the answer is really the tool column.

jq -r '.[] | select(.provider=="anthropic" and (.status|index("RETIRED")|not) and .capabilities.structured_outputs_json==true and .capabilities.prompt_caching==true) | [.id, ([.tools[].type]|join(","))] | @tsv' generated/models.json

Caveats from the records: strict is rejected on toolsets (mcp_toolset, computer_toolset_20260801, browser_toolset_20260801) and on programmatic callers; changing output_config.format invalidates the prompt cache (docs/anthropic/prompt-caching.md); tool_choice any/tool is 400 on Fable 5.1 / Mythos 5.1; mcp_toolset and advisor_20260301 still need beta headers (mcp-client-2025-11-20, advisor-tool-2026-03-01); Mythos ids are ACCOUNT_RESTRICTED (invite only). Tool-level compatibility lists: generated/compatibility/anthropic-tool-model-matrix.json, generated/compatibility/model-tool-matrix.json.

# Q2. Which OpenAI models accept image input + reasoning + web search + streaming?

Interpretation: capabilities.image_in, capabilities.reasoning, capabilities.tool_web_search and capabilities.streaming all true in generated/models.json. Web search here means the hosted web_search tool on /v1/responses (Chat Completions only has search models). Retired ids are listed separately.

jq -r '.[] | select(.provider=="openai" and .capabilities.image_in==true and .capabilities.reasoning==true and .capabilities.tool_web_search==true and .capabilities.streaming==true) | [.id, (.status|join(",")), (.context_window|tostring), (.capabilities.reasoning_effort_values//[]|join("/"))] | @tsv' generated/models.json

Also matching but RETIRED (excluded): gpt-5-codex, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.2-codex, o3-deep-research, o3-deep-research-2025-06-26, o4-mini-deep-research, o4-mini-deep-research-2025-06-26. Caveats: o4-mini, o3-2025-04-16, gpt-5-*-2025-08-07 snapshots are DEPRECATED with shutdown dates (see docs/openai/deprecations.md); web search is not supported with gpt-5 reasoning.effort: minimal and may degrade with none (docs/tools/openai/web-search.md); gpt-5.6-cyber, gpt-daybreak-* are gated (ACCOUNT_RESTRICTED/DOCUMENTED).

# Q2b. The same combination on all four providers — image input + reasoning + vendor web search + structured outputs + streaming

Interpretation per provider (capability keys differ): openai image_in, reasoning, tool_web_search, structured_outputs, streaming; anthropic vision, (thinking_adaptive or thinking_extended_manual_budget), web_search, structured_outputs_json (streaming is universal); xai image_input, reasoning, web_search, structured_outputs, streaming; gemini image_input, thinking (true or a 'Supported…' string), google_search_grounding, structured_output (streaming is universal). Retired ids, aliases and id-only records excluded; xAI retired_redirect/legacy kinds and Gemini alias/agent kinds excluded.

jq -r '.[] | select(.provider=="xai" and .kind=="model" and .capabilities.image_input==true and .capabilities.reasoning==true and .capabilities.web_search==true and .capabilities.structured_outputs==true) | .id' generated/models.json
jq -r '.[] | select(.provider=="gemini" and (.kind=="stable" or .kind=="preview") and (.status|index("RETIRED")|not) and .capabilities.image_input==true and (.capabilities.thinking==true or (.capabilities.thinking|type=="string" and startswith("Supported"))) and .capabilities.google_search_grounding==true and .capabilities.structured_output==true) | .id' generated/models.json

Reading notes: OpenAI snapshots (gpt-5.4-2026-03-05…) appear as separate callable ids; Anthropic aliases (claude-haiku-4-5) are excluded (capabilities live on the snapshot); Gemini image-output models (gemini-3.1-flash-image, gemini-3-pro-image) support Google Search grounding and thinking but not structured output, so they drop out; gemini-2.5-* match on paper but are ACCOUNT_RESTRICTED ('no longer available to new users'); xAI grok-4.20-0309-non-reasoning drops out on reasoning: false.

# Q3. What is the exact JSON to call feature Y?

Three lookups, in order of precision:

1. Parameter rows — generated/parameters.json (7,862 rows) is keyed by endpoint (METHOD /path) and dotted parameter path (Gemini uses the REST camelCase names, e.g. generationConfig.thinkingConfig.thinkingLevel), with type, required, default, enum, beta_header, status, description.

# every parameter of the Anthropic structured-output block
jq '[.[] | select(.provider=="anthropic" and .endpoint=="POST /v1/messages" and (.parameter|startswith("output_config.format")))]' generated/parameters.json
# the OpenAI equivalent
jq '[.[] | select(.provider=="openai" and .endpoint=="POST /v1/responses" and (.parameter|startswith("text.format")))]' generated/parameters.json
# xAI Responses reasoning + caching knobs
jq '[.[] | select(.provider=="xai" and .endpoint=="POST /v1/responses" and (.parameter|test("^(reasoning|prompt_cache_key|store|previous_response_id|max_turns)")))]' generated/parameters.json
# Gemini thinking and structured-output knobs
jq '[.[] | select(.provider=="gemini" and .endpoint=="POST /v1beta/models/{model}:generateContent" and (.parameter|test("thinkingConfig|responseJsonSchema|responseMimeType|cachedContent")))]' generated/parameters.json
# all tool entry shapes accepted by OpenAI Responses
jq -r '.[] | select(.provider=="openai" and .endpoint=="POST /v1/responses" and (.parameter|test("^tools\\[\\]\\("))) | .parameter' generated/parameters.json

2. Tool records — generated/tools.json has parameters_schema, result_shape, examples{curl,python,typescript} per exact tool type (69 records: OpenAI 19, Anthropic 27, xAI 12, Gemini 11).

jq '.[] | select(.type=="web_search_20260318") | {parameters_schema, result_shape, beta_header, examples}' generated/tools.json
jq '.[] | select(.provider=="xai" and .type=="x_search") | {parameters_schema, result_shape, billing}' generated/tools.json
jq '.[] | select(.provider=="gemini" and .type=="googleSearch") | {parameters_schema, result_shape, billing, limitations}' generated/tools.json

3. Runnable examples — generated/examples-manifest.json maps features to files under examples/<provider>/<area>/ with their verification status. Selection:

Minimal verified bodies (from the live probes recorded in the docs):

// OpenAI — POST /v1/responses (structured output, LIVE_VERIFIED gpt-5.4-nano)
{"model":"gpt-5.4-nano","input":"Reply with OK.","max_output_tokens":32,
 "text":{"format":{"type":"json_schema","name":"ok_reply","strict":true,
   "schema":{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"],"additionalProperties":false}}}}

// Anthropic — POST /v1/messages (structured output, LIVE_VERIFIED claude-haiku-4-5-20251001)
{"model":"claude-haiku-4-5-20251001","max_tokens":100,
 "messages":[{"role":"user","content":"Reply with OK."}],
 "output_config":{"format":{"type":"json_schema",
   "schema":{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"],"additionalProperties":false}}}}

// xAI — POST /v1/responses (structured output, LIVE_VERIFIED grok-4.3; reasoning tokens are billed on every call)
{"model":"grok-4.3","input":"Reply with OK.","max_output_tokens":64,"reasoning":{"effort":"low"},
 "text":{"format":{"type":"json_schema","name":"ok_reply","strict":true,
   "schema":{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"],"additionalProperties":false}}}}

// Gemini — POST /v1beta/models/gemini-3.5-flash-lite:generateContent (structured output, LIVE_VERIFIED; header x-goog-api-key)
{"contents":[{"role":"user","parts":[{"text":"Reply with OK."}]}],
 "generationConfig":{"maxOutputTokens":64,"thinkingConfig":{"thinkingLevel":"minimal"},
   "responseMimeType":"application/json",
   "responseJsonSchema":{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}}}

Per-topic parameter mappings with full JSON quads: state-management, tool-execution, caching-and-reasoning, streaming, agents-platforms, realtime-and-media.

# Q4. Which SSE / WebSocket events can arrive during this call?

Computed from generated/streaming-events.json (506 records: openai 282, anthropic 68, xai 94, gemini 62; api field = call type, direction = server→client unless noted). Event names are listed exactly as recorded; ✔ marks events observed live in this run (LIVE_VERIFIED).

jq -r '.[] | select(.provider=="xai" and .api=="responses") | .event' generated/streaming-events.json
jq -r '.[] | select(.provider=="gemini" and .api=="live" and .direction=="server→client") | .event' generated/streaming-events.json

How to read the four core streams: OpenAI Responses is event: <type> + data: with sequence_number, terminal response.completed|failed|incomplete|error, no [DONE]; Anthropic Messages is event: <type> + data: (data.type == event), fixed skeleton message_start → content_block_start/delta/stop × N → message_delta → message_stop, ping anywhere, no [DONE]; xAI reuses both shapes — /v1/responses emits the OpenAI Responses event names (with sequence_number, no [DONE]), /v1/chat/completions emits data-only chat.completion.chunk + data: [DONE], and /v1/messages emits the Anthropic skeleton (no ping); Gemini streamGenerateContent has no event names at all — a JSON array of GenerateContentResponse chunks by default or data: lines with ?alt=sse (thought parts flagged thought: true, end detected by finishReason), while the Interactions API uses named events (interaction.start … content.delta … interaction.complete). Details: streaming comparison.

The Anthropic messages group is the advanced fragment (thinking/citations/compaction variants of the same core events); the POST /v1/messages (stream=true) group is the core catalogue — both describe one stream. Voice WebSockets (OpenAI Realtime/Live, xAI realtime/tts/stt, Gemini Live/Lyria RealTime) are bidirectional message families, not SSE.

# Q5. Which endpoint creates an agent session on each provider?

jq '.[] | select((.provider=="openai" and .path=="/v1/agents/sessions") or (.provider=="anthropic" and .path=="/v1/sessions") or (.provider=="gemini" and .path=="/v1beta/interactions") or (.provider=="xai" and .path=="/v1/responses")) | select(.method=="POST") | {provider, method, path, status, beta_header, verification}' generated/endpoints.json

Prerequisite creates: OpenAI POST /v1/agents (LIVE_VERIFIED 201) or an inline agent; Anthropic POST /v1/agents (LIVE_VERIFIED 200) and POST /v1/environments (LIVE_VERIFIED 200); Gemini POST /v1beta/agents (custom managed agents, PREVIEW, not tested) and POST /v1beta/environments (LIVE_VERIFIED). Not to be confused with: OpenAI Conversations (POST /v1/conversations — a state container for Responses, not an agent), Realtime client secrets (POST /v1/realtime/client_secrets), ChatKit sessions, the retired Assistants threads/runs; xAI POST /v1/realtime/client_secrets (voice session token); Gemini POST /v1beta/auth_tokens (ephemeral Live token) and cachedContents (a prefix cache, not a session). Full comparison: agents-platforms.

# Q6. Which feature needs a beta header (or a beta path / preview model)?

The four providers gate pre-GA features differently: Anthropic by anthropic-beta header values (per parameter/tool/endpoint), OpenAI by OpenAI-Beta header values (per surface), Gemini by the URL version (/v1beta vs /v1) and -preview / -exp model ids (no header exists), xAI by nothing visible — no version or beta headers; gated features answer 403 ('alpha users') or 404 (ACL) and are recorded ACCOUNT_RESTRICTED.

# Anthropic — anthropic-beta values that are still gating (status BETA / PREVIEW / DOCUMENTED-only), from generated/fragments/headers/anthropic-beta-headers.json, cross-referenced with the beta_header field of generated/parameters.json, tools.json and endpoints.json

Graduated (header now optional — LEGACY): message-batches-2024-09-24, prompt-caching-2024-07-31, pdfs-2024-09-25, token-counting-2024-11-01, computer-use-2025-01-24, token-efficient-tools-2025-02-19, output-128k-2025-02-19, files-api-2025-04-14, code-execution-2025-05-22, extended-cache-ttl-2025-04-11, skills-2025-10-02, thinking-token-count-2026-05-13, structured-outputs-2025-11-13, ce-user-management-2026-07-13, fine-grained-tool-streaming-2025-05-14, search-results-2025-06-09, effort-2025-11-24. Retired / deprecated: computer-use-2024-10-22, mcp-client-2025-04-04, context-1m-2025-08-07, max-tokens-3-5-sonnet-2024-07-15.

Live findings worth knowing: mcp_servers without a header → 400 that names mcp-client-2026-09-15, which is itself rejected (use mcp-client-2025-11-20); memory-store calls reject the pair agent-memory-2026-07-22 + managed-agents-2026-04-01; speed and context_management are rejected with 400 'Extra inputs are not permitted' without their headers; output_format (legacy) → 400 even with structured-outputs-2025-11-13.

# OpenAI — OpenAI-Beta values (from generated/endpoints.json / headers.json)

Everything else on OpenAI (Responses, hosted tools incl. MCP, structured outputs, prompt caching, Batch, Files, Webhooks, Realtime GA) needs no beta header; POST /v1/responses?beta=true exposes a beta schema (multi_agent) with an optional body-level openai-beta[]. OpenAI-Beta: realtime=v1 is legacy (the beta endpoints return 404).

# Gemini — /v1beta vs /v1, -preview models, BETA/PREVIEW endpoints (from generated/endpoints.json, models.json)

# Gemini surfaces that exist only under /v1beta
jq -r '[.[] | select(.provider=="gemini" and (.path|startswith("/v1beta/")))] | group_by(.api_family) | .[] | "\(.[0].api_family)\t\(length)"' generated/endpoints.json
# preview / experimental Gemini model ids still served
jq -r '.[] | select(.provider=="gemini" and (.kind=="preview" or .kind=="experimental") and (.status|index("RETIRED")|not)) | .id' generated/models.json

• Stable /v1 surface (9 paths recorded): /v1/interactions, /v1/interactions/{id}, /v1/interactions/{id}/cancel, /v1/models, /v1/models/{model}:generateContent, /v1/webhooks, /v1/webhooks/{id}, /v1/webhooks/{id}/rotate_secret, /v1/webhooks/{id}:ping. Everything else — including explicit context caching (cachedContents), Files, File Search stores, Batch, embeddings, countTokens, Live API (v1beta WebSocket), ephemeral auth_tokens, Veo predictLongRunning, the OpenAI-compatibility layer and the managed-agents preview (agents, environments, credentials, triggers) — is v1beta-only (families: agents, auth-tokens, batch, caching, credentials, dynamic, embeddings, environments, file-search, files, image-generation, legacy-palm, openai-compat, operations, tokens, transcription, triggers, tuning, video-generation). /v1/cachedContents returns 404.
• Endpoints recorded BETA/PREVIEW (64): agents (4), auth-tokens (1), caching (5), credentials (5), dynamic (2), environments (7), file-search (12), interactions (4), live (2), music-generation (1), openai-compat (7), triggers (7), video-generation (1), webhooks (6). POST /v1beta/interactions is BETA + LIVE_VERIFIED; its /v1/interactions twin is documented GA but UNVERIFIED.
• Preview / experimental model ids still served (25): gemini-2.5-flash-preview-tts (PREVIEW), gemini-2.5-pro-preview-tts (PREVIEW), gemini-3-flash-preview (PREVIEW), gemini-3.1-pro-preview (PREVIEW/ACCOUNT_RESTRICTED), gemini-3.1-pro-preview-customtools (PREVIEW), gemini-omni-flash-preview (PREVIEW/DEPRECATED), lyria-3-clip-preview (PREVIEW), lyria-3-pro-preview (PREVIEW), gemini-3.1-flash-tts-preview (PREVIEW), gemini-robotics-er-2-preview (PREVIEW), gemini-2.5-computer-use-preview-10-2025 (PREVIEW), gemini-embedding-2-preview (PREVIEW), veo-3.1-generate-preview (PREVIEW), veo-3.1-fast-generate-preview (PREVIEW), veo-3.1-lite-generate-preview (PREVIEW), gemini-2.5-flash-native-audio-preview-09-2025 (PREVIEW), gemini-2.5-flash-native-audio-preview-12-2025 (PREVIEW), gemini-3.1-flash-live-preview (PREVIEW), gemini-robotics-er-2-streaming-preview (PREVIEW), gemini-3.5-live-translate-preview (PREVIEW), lyria-realtime-exp (BETA), gemini-2.0-flash-exp (BETA/UNVERIFIED), gemini-2.5-flash-preview-09-2025 (PREVIEW/UNVERIFIED), lyria-3.5-clip-preview (PREVIEW/UNVERIFIED), lyria-3.5-pro-preview (PREVIEW/UNVERIFIED). Preview models 'may be used in production' but carry more restrictive limits and can be deprecated with two weeks' notice; -latest aliases (gemini-flash-latest, gemini-pro-latest, gemini-flash-lite-latest) are hot-swapped.
• Gated by account tier rather than header: Pro models and paid-only media models return 429 limit: 0 on the free tier (gemini-3.1-pro-preview, gemini-pro-latest, cachedContents create — all ACCOUNT_RESTRICTED here); Gemini 2.5 models return 404 'no longer available to new users'.

# xAI — no beta headers; gating is by ACL / alpha program (from generated/endpoints.json, tools.json, headers.json)

• headers.json records no versioning / beta headers for xAI: features are selected by body fields (service_tier, reasoning_effort, store, prompt_cache_key, include) or by base URL (us.api.x.ai, management-api.x.ai).
• ACCOUNT_RESTRICTED endpoints (41): collections (11), embeddings (1), management (21), models (2), skills (5), voice (1) — the Management API needs a separate Management key (401 code 16 with an inference key), /v1/embeddings and grok-embedding-small return 404 for this team, /v1/skills returns 404, custom-voice creation is Enterprise-only, and Collections are documented on management-api.x.ai although the same paths answered on api.x.ai (LIVE_DISCOVERED).
• Tools: tool_search → DOCUMENTED · ACCOUNT_RESTRICTED; live_search → DOCUMENTED · RETIRED. tool_search (+ defer_loading) answers 403 'only available for alpha users'; live_search / search_parameters / web_search_options answer 410.
• Models flagged BETA/PREVIEW: grok-4.20-multi-agent-0309 (BETA), grok-build-0.1 (PREVIEW) (multi-agent is Responses-only; Grok Build is 'early access'). Regional host eu-west-1.api.x.ai is undocumented (LIVE_DISCOVERED).

# Q7. Which model supports combination Z?

Recipe: filter generated/models.json on capabilities.* booleans. Key families — OpenAI: image_in, reasoning, structured_outputs, function_calling, prompt_caching, tool_web_search, tool_code_interpreter, tool_mcp, tool_computer_use, tool_hosted_shell, tool_apply_patch, tool_skills, tool_tool_search, fine_tuning, batch, audio_in/out, realtime; Anthropic: vision, pdf_input, structured_outputs_json, strict_tool_use, prompt_caching, web_search, web_fetch, code_execution, programmatic_tool_calling, computer_use_toolset_ga, browser_use, mcp_connector, agent_skills, tool_search, effort_parameter, thinking_adaptive, context_1m_default_no_beta, fast_mode_speed_fast, batch_api, zero_data_retention_eligible; xAI: reasoning, reasoning_can_be_disabled, reasoning_effort_levels[], function_calling, structured_outputs, prompt_caching_automatic, batch_api, priority_processing, context_compaction, websocket_responses, web_search, x_search, code_execution, collections_search, remote_mcp, image_generation_tool, files_attachments, encrypted_reasoning_content, anthropic_messages_compat; Gemini: thinking, thinking_level_param, thinking_levels[], thought_signatures, structured_output, function_calling, parallel_function_calling, compositional_function_calling, google_search_grounding, google_maps_grounding, url_context, code_execution, computer_use, file_search, context_caching_explicit, context_caching_implicit, batch_api, flex_inference, priority_inference, live_api, interactions_api, openai_compatible_chat, audio_input, video_input, pdf_input, image_output, audio_output, embeddings, tuning. Flat matrices: generated/compatibility/model-capability-matrix.json (+ .csv), gemini-feature-model-matrix.json, gemini-tool-model-matrix.json.

# generic pattern
jq -r '.[] | select(.provider=="anthropic" and .capabilities.context_1m_default_no_beta==true and .capabilities.computer_use_toolset_ga==true and .capabilities.web_search==true and (.status|index("RETIRED")|not)) | .id' generated/models.json
jq -r '.[] | select(.provider=="gemini" and .capabilities.live_api==true and .capabilities.function_calling==true and .capabilities.google_search_grounding==true and (.status|index("RETIRED")|not)) | .id' generated/models.json

Snapshot ids (e.g. gpt-5.4-2026-03-05) share their alias's capabilities and appear in the raw query output; the table above keeps them because they are distinct callable ids. Capability flags marked "unknown" in the source never match a == true filter — check the model page before excluding a model on that basis (many Gemini media/agent records and Gemma 4 carry "unknown" for tool flags). Gemini computer_use / file_search may be the string "Supported (Preview)" / "Supported (AI Studio only)" — treated as true above (✔*).

# Q8. Which provider offers X, and at what price?

Computed from generated/pricing.json (tool/service rows) and the pricing blocks of generated/models.json. Units are quoted as recorded; '—' = no documented surface. Statuses are those of the underlying tool/model record.

# every per-call tool price across providers
jq -r '.[] | select(.unit|test("call|search|request|prompt";"i")) | [.provider, .model_or_service, .dimension, (.price|tostring), .unit, (.tier//"")] | @tsv' generated/pricing.json

Provider-specific billing quirks that change the arithmetic: xAI bills reasoning tokens on every Grok call and applies its ≥200k-token long-context rate to the whole request; Gemini's 3.6–3.8 Flash prices double on 2027-01-01 and its free tier covers most Flash/Live/TTS/embedding models; Anthropic and OpenAI charge cache writes (1.25×) on their newest models while xAI and Gemini implicit caching have none (Gemini explicit caches pay storage per token-hour). Full tables and cost models: pricing comparison.

# Q9. Where do I look for … ?