Endpoint Reference
The Platform API lives under the/v1 prefix. Base URL:
Authentication
Every request except a small number of public endpoints carries an API key: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.
Known boundaries
Related pages
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).
