Skip to main content
The Agent API exposes the Polpo data plane through your Cloud project endpoint.

​
Base URL

​
Authentication

Send a project API key as either a Bearer token or an x-api-key header. Keys start with sk_live_ or sk_test_.
Never expose a project API key in browser or mobile application code. Call Polpo from a backend or an authenticated server-side proxy.

​
Response format

Most data-plane endpoints return an envelope:
The chat completions endpoint is the exception: it returns the OpenAI chat completion shape directly. Errors use error and code; resource API codes are generally uppercase, while Cloud authentication errors can use lowercase codes.

​
Streaming

POST /v1/chat/completions streams OpenAI-compatible data: chunks when stream is true. The Cloud-only POST /v1/tasks/{id}/execute endpoint streams runtime events. Mission execution returns JSON; observe the resulting tasks through task endpoints or the project event stream.

​
OpenAI compatibility

Only POST /v1/chat/completions is wire-compatible with the OpenAI chat completions format. Polpo-specific fields such as agent, loop, and sandbox are not represented by the standard OpenAI client API. The request model field can override the selected agent’s model for that call; it does not select the agent. Use @polpo-ai/sdk or raw HTTP when selecting an agent.