Skip to main content
The Agent API is how you interact with your Polpo project — chat with agents, create tasks, run missions, and stream events. All endpoints are OpenAI-compatible where applicable.

​
Base URL

https://api.polpo.sh/v1
This is the project endpoint provisioned when you run polpo deploy. Every request targets this base URL.

​
Authentication

All endpoints require a project API key passed as a Bearer token.
​
Authorization
string
required
Bearer token using your project API key. Keys start with sk_live_ (production) or sk_test_ (sandbox).
Authorization: Bearer sk_live_abc123...
Project API keys are scoped to a single project. Generate them from the Dashboard or via the Platform API. Live keys access production resources; test keys access the sandbox environment.

​
Response format

All responses return JSON. Successful responses return the resource directly: 
{
  "id": "agt_abc123",
  "name": "backend-dev",
  "role": "Backend engineer",
  "model": "anthropic:claude-sonnet-4-5"
}
Errors return a consistent shape: 
{
  "error": "Agent not found",
  "code": "not_found"
}

​
Common error codes

CodeStatusDescription
unauthorized401Missing or invalid API key
invalid_api_key401API key not found or revoked
not_found404Resource does not exist
bad_request400Missing or invalid parameter
conflict409Resource already exists
rate_limited429Too many requests
internal_error500Server error

​
Streaming

Endpoints that support streaming (chat completions, task execution, mission execution) return Server-Sent Events (SSE) when stream: true is set. The stream follows the OpenAI convention: 
data: {"choices":[{"delta":{"content":"Hello"}}]}

data: {"choices":[{"delta":{"content":" world"}}]}

data: [DONE]
Set Accept: text/event-stream in your request headers when streaming.

​
OpenAI compatibility

The chat completions endpoint (POST /v1/chat/completions) follows the OpenAI API format exactly. You can use any OpenAI-compatible client library by pointing it at your Polpo base URL.

​
Quick start examples

curl https://api.polpo.sh/v1/chat/completions \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "backend-dev",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'
Never expose your API key in client-side code. Use a backend proxy or edge function to keep your key server-side.