Skip to main content

​
Base URL

https://api.polpo.sh

​
Authentication

The Polpo API uses two authentication methods:

​
Session Auth (Control Plane)

Used for managing organizations, projects, and API keys. Requires a session token from Better Auth. 
Authorization: Bearer <session_token>

​
API Key Auth (Data Plane)

Used for agent operations — completions, tasks, missions, events. Requires a project API key. 
Authorization: Bearer sk_live_...

​
Response Format

All responses return JSON. Successful responses return the resource directly. Errors return: 
{
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

​
Common Error Codes

CodeStatusDescription
unauthorized401Missing or invalid authentication
invalid_api_key401API key not found or revoked
not_found404Resource doesn’t exist
conflict409Resource already exists (duplicate slug)
bad_request400Missing required parameter
internal_error500Server error

​
Rate Limits

Free tier: 10 requests/second per API key. Rate limit headers: 
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
Retry-After: 1

​
OpenAPI Spec

The full OpenAPI 3.1 specification is available at: 
GET /v1/openapi.json