Live now · Get your API key

API reference

The full Ambient HTTP API surface, covering base URL, auth, compatibility dialects, and a generated table of every endpoint in the live OpenAPI spec.

This is the reference index for the Ambient HTTP API: every endpoint the live OpenAPI spec exposes. The two endpoints most integrations touch, Chat Completions and Models, each have a field-by-field page.

Basics#

Base URL https://api.ambient.xyz (OpenAI-style paths under /v1)
Auth Authorization: Bearer <key>; keys from app.ambient.xyz/keys
No-auth exception GET /v1/models works without a key
Content type application/json
Spec openapi.json, "Ambient Public HTTP API"

Prerequisites#

Get an API key through app.ambient.xyz/keys, or create and fund an API-only account through Headless x402 subscriptions without using the Ambient UI.

For speed and flexibility, we recommend using direct API calls. These allow you to control thinking tokens (balancing speed and latency) and perform Deep Research directly. The streaming Python demo covers reasoning and non-reasoning modes; place your API key in a file named ambient_api_key.txt in the same directory. The condensed API reference contains Python examples of all functions.

Integration options#

OpenAI SDK

Point the official OpenAI SDK at Ambient's base URL. Ideal if you already use OpenAI's SDK or prefer its interface. Python and JavaScript examples.

Anthropic SDK

Point the official Anthropic SDK at Ambient and use the Messages API format. Python and JavaScript examples.

Direct API calls

Make HTTP requests directly, with no SDK. Full control, any language. The interactive API docs list every endpoint and schema and let you try requests in the browser.

Compatibility#

The API speaks the two dominant dialects, so official SDKs work by swapping the base URL:

  • POST /v1/chat/completions accepts the standard OpenAI Chat Completions parameters (plus Ambient extensions). Setup in the OpenAI SDK guide.
  • POST /v1/messages and POST /v1/messages/count_tokens implement Anthropic Messages. Setup in the Anthropic SDK guide.
  • POST /v1/responses (the OpenAI Responses API) works for simple string input, message arrays with string content, and SSE streaming. It does not accept typed input_text content parts or namespace-style tool definitions, so clients that require them (including the Codex CLI) cannot route through it.

All endpoints#

Anthropic
POST /v1/messages/count_tokens Count Tokens
POST /v1/messages Messages
Completions
POST /v1/chat/completions Chat Completions
POST /v1/completions Completions
Models
GET /v1/models List Models
GET /v1/models/{model_id} Get Model
Assistants
GET /v1/assistants List Assistants
POST /v1/assistants Create Assistant
GET /v1/assistants/{assistant_id} Get Assistant
POST /v1/assistants/{assistant_id} Update Assistant
DELETE /v1/assistants/{assistant_id} Delete Assistant
Threads
GET /v1/threads List Threads
POST /v1/threads Create Thread
GET /v1/threads/{thread_id} Get Thread
POST /v1/threads/{thread_id} Update Thread
DELETE /v1/threads/{thread_id} Delete Thread
Runs
GET /v1/threads/{thread_id}/runs List Runs
POST /v1/threads/{thread_id}/runs Create Run
GET /v1/threads/{thread_id}/runs/{run_id} Get Run
POST /v1/threads/{thread_id}/runs/{run_id} Update Run
DELETE /v1/threads/{thread_id}/runs/{run_id} Delete Run
GET /v1/threads/{thread_id}/runs/{run_id}/steps Get Run Steps
GET /v1/threads/{thread_id}/runs/{run_id}/steps/{step_id} Get Run Step
Messages
GET /v1/threads/{thread_id}/messages List Messages
POST /v1/threads/{thread_id}/messages Create Message
GET /v1/threads/{thread_id}/messages/{message_id} Get Message
POST /v1/threads/{thread_id}/messages/{message_id} Update Message
DELETE /v1/threads/{thread_id}/messages/{message_id} Delete Message
Responses
GET /v1/responses List Response
POST /v1/responses Create Response
GET /v1/responses/{response_id} Get Response
DELETE /v1/responses/{response_id} Delete Response
GET /v1/responses/{response_id}/thread Get Thread
POST /v1/responses/{response_id}/cancel Cancel Response
Research
GET /v1/research List Research
POST /v1/research Conduct research on a topic
POST /v1/research/generate-pdf Generate a research report PDF
GET /v1/research/{research_id} Get research details
DELETE /v1/research/{research_id} Delete a research record
GET /v1/research/{research_id}/actions Stream research actions in real-time
Tools
POST /v1/tools Execute tool calls directly
Referrals
GET /referral/dashboard Get Referral Dashboard

42 operations in Ambient Public HTTP API v0.1.0. Current as of 2026-07-04; the live spec is at api.ambient.xyz/openapi.json.

Beyond chat completions and models, the spec also exposes an Assistants/Threads/Runs suite, the Responses API, a Research API, and direct tool execution. For those groups, the interactive spec below is the reference.

Interactive spec of record#

The server publishes its own always-current, schema-exact reference: