# API Reference

> Interactive API reference for PromptRails with request/response examples, authentication details, and endpoint documentation.

Source: https://0.0.0.0:8080/docs/rest-api-reference

PromptRails provides a comprehensive REST API for managing agents, prompts, executions, and all platform resources.

## Interactive Documentation

Our API documentation is powered by Scalar and includes the full OpenAPI specification with request/response examples, authentication flows, and live testing capabilities.

## Base URL

The API base URL depends on your deployment:

- **Cloud**: `https://api.promptrails.ai`

All API endpoints are prefixed with `/api/v1/`.

## Authentication

### API Key Authentication

Include your API key in the `X-API-Key` header:

```bash
curl -H "X-API-Key: pr_live_abc123..." \
     https://api.promptrails.ai/api/v1/agents
```

### JWT Authentication

For user-based authentication (dashboard, frontend), include the JWT token in the `Authorization` header:

```bash
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
     https://api.promptrails.ai/api/v1/agents
```

### Workspace Header

Most endpoints require a workspace context. Include the `X-Workspace-ID` header:

```bash
curl -H "X-API-Key: pr_live_abc123..." \
     -H "X-Workspace-ID: 2NxAbc123def456ghi789jkl" \
     https://api.promptrails.ai/api/v1/agents
```

When using an API key, the workspace is inferred from the key's workspace if not explicitly provided.

## Request Format

All request bodies must be JSON with `Content-Type: application/json`:

```bash
curl -X POST https://api.promptrails.ai/api/v1/agents \
  -H "X-API-Key: pr_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "type": "simple",
    "description": "A simple agent"
  }'
```

## Response Format

All responses use a standard JSON envelope:

### Success Response

```json
{
  "data": {
    "id": "2NxAbc123def456ghi789jkl",
    "name": "My Agent",
    "type": "simple",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Agent created successfully"
}
```

### List Response

```json
{
  "data": [
    { "id": "...", "name": "Agent 1" },
    { "id": "...", "name": "Agent 2" }
  ],
  "message": "",
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3
  }
}
```

### Error Response

```json
{
  "data": null,
  "error": "Agent not found",
  "message": "The requested agent does not exist"
}
```

## Streaming (Server-Sent Events)

Two endpoints stream agent execution events over SSE. Set
`Accept: text/event-stream` on the request; the server emits frames in
the canonical `event: <name>\ndata: <json>\n\n` format.

| Endpoint                                            | Method | Purpose                                                            |
| --------------------------------------------------- | ------ | ------------------------------------------------------------------ |
| `/api/v1/chat/sessions/{sessionId}/messages/stream` | POST   | Post a chat message and stream the run in one request.             |
| `/api/v1/executions/{executionId}/stream`           | GET    | Subscribe to an execution started elsewhere (polling replacement). |

### Event types

| Event        | Payload                             | Emitted when                                         |
| ------------ | ----------------------------------- | ---------------------------------------------------- |
| `execution`  | `{ execution_id, user_message_id }` | First frame of a chat stream. Correlate with traces. |
| `thinking`   | `{ content }`                       | Intermediate reasoning between tool rounds.          |
| `tool_start` | `{ id, name }`                      | A tool is about to execute.                          |
| `tool_end`   | `{ id, name, summary }`             | A tool finished. `summary` is short display text.    |
| `content`    | `{ content }`                       | Delta of the final assistant response.               |
| `done`       | `{ output, token_usage, time }`     | Terminal. Full output and token accounting.          |
| `error`      | `{ message }`                       | Terminal. Surfaces a server-side error.              |

Each of the three official SDKs exposes typed wrappers — see the
[JavaScript](/docs/javascript-sdk#stream-a-chat-turn),
[Python](/docs/python-sdk#stream-a-chat-turn), and
[Go](/docs/go-sdk#stream-a-chat-turn) guides. Unknown event names are
safe to ignore so older clients keep working as new frames are added.

## Pagination

List endpoints support pagination via query parameters:

| Parameter | Default | Description                             |
| --------- | ------- | --------------------------------------- |
| `page`    | 1       | Page number (1-based)                   |
| `limit`   | 20      | Items per page (max varies by endpoint) |

```bash
GET /api/v1/agents?page=2&limit=10
```

## Error Codes

| HTTP Status | Description                                           |
| ----------- | ----------------------------------------------------- |
| `400`       | Bad Request -- Invalid parameters or request body     |
| `401`       | Unauthorized -- Missing or invalid authentication     |
| `402`       | Payment Required -- Plan limit exceeded               |
| `403`       | Forbidden -- Insufficient permissions                 |
| `404`       | Not Found -- Resource does not exist                  |
| `409`       | Conflict -- Resource already exists or state conflict |
| `422`       | Unprocessable Entity -- Validation error              |
| `429`       | Too Many Requests -- Rate limit exceeded              |
| `500`       | Internal Server Error -- Server-side error            |

## Related Topics

- [API Keys & Scopes](/docs/api-keys-and-scopes) -- Authentication setup
- [Python SDK](/docs/python-sdk) -- Python client library
- [JavaScript SDK](/docs/javascript-sdk) -- JavaScript client library