Skip to main content

Endpoint Reference

The Platform API lives under the /v1 prefix. Base URL:
This page is the complete endpoint index. Full request and response shapes live on each API detail page.

Authentication

Every request except a small number of public endpoints carries an API key:
In multi-user deployments you must also identify the end user:
X-End-User-Id is not decorative. When calling /v1/chat/*, /v1/agents/run, /v1/sessions*, or /v1/files* with an API key, omitting it returns 400 with this exact message:
Failing loudly beats merging silently: one API key usually fronts many end users, and session history, sandbox files, and memory are all partitioned by this header. Without it everyone shares one partition — cross-user bleed costs far more than one extra header.OAuth app callers are exempt, because the authorization flow already established identity.

All endpoints

Runs and sessions

agents/run and sessions/:id/events share the same execution path. The only difference is whether state persists:
  • One-shot tasks use agents/run — stateless
  • Multi-turn conversations use sessions — the server keeps context

Agents

publish submits for review; it does not go live directly. When a published agent ships a new version the old one stays online while the new one queues for review — so a successful publish does not mean users see the change yet. Confirm with get_submission_status (MCP) or the pending-submission field on the agent detail.

Environments (sandbox templates)

Files

Uploads are two-step: get a direct URL, PUT the bytes to object storage, then register. Large files never traverse the API server and are not bound by request body limits. Limits are listed in Limits.

Usage and models

GET /v1/meters is the only unauthenticated /v1 endpoint — pricing has to be visible before anyone signs in.

OAuth scopes

Third-party apps integrate over OAuth and are granted scopes.
Session and environment operations reuse agents:write rather than minting sessions:* / environments:*. They all mean “act as this app on this app’s agents.” Splitting them out would add two options nobody understands to the consent screen without creating a real permission boundary.

Request example

Streaming responses

agents/run, chat/completions, and sessions/:id/events all return text/event-stream. Event names use dotted hierarchical naming (aligned with the OpenAI Responses API). The full vocabulary is in SSE Events.
The stream terminator is data: [DONE]. It is not a JSON event — calling JSON.parse on it throws. Your parse loop must check for that line first.

Known boundaries

Without these three lines you would spend hours debugging “why don’t webhooks fire” or “why didn’t the skill take effect” when the root cause is that the feature is not wired yet. Admitting the gap is cheaper than letting you chase something that does not exist.

SSE Events

The complete streaming event vocabulary

Error Codes

Every business code and status derivation

Authentication

API keys and OAuth

Environment Variables

SDK and integration configuration
Verified 2026-08-11. Sources: services/core/src/routes/platform-api/ (index.ts, agents.ts, sessions.ts, environments.ts, files.ts), services/core/src/index.ts (/v1 mount).