> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API Overview

> Authentication, base URL, and conventions for the Agent API

The Agent API exposes the Polpo data plane through your Cloud project endpoint.

## Base URL

```text theme={null}
https://{project}.polpo.cloud/v1
```

## 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_`.

```http theme={null}
Authorization: Bearer sk_live_abc123
```

<Warning>Never expose a project API key in browser or mobile application code. Call Polpo from a backend or an authenticated server-side proxy.</Warning>

## Response format

Most data-plane endpoints return an envelope:

```json theme={null}
{
  "ok": true,
  "data": {
    "name": "backend-dev",
    "model": "anthropic/claude-sonnet-4-5"
  }
}
```

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.

```json theme={null}
{
  "ok": false,
  "error": "Agent not found",
  "code": "NOT_FOUND"
}
```

## 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.

```bash theme={null}
curl https://{project}.polpo.cloud/v1/chat/completions \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "backend-dev",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'
```