PromptRails
View as Markdown

API Reference

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

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.

Open API Documentation →

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:

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:

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:

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:

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

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

List Response

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

Error Response

{
  "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.

EndpointMethodPurpose
/api/v1/chat/sessions/{sessionId}/messages/streamPOSTPost a chat message and stream the run in one request.
/api/v1/executions/{executionId}/streamGETSubscribe to an execution started elsewhere (polling replacement).

Event types

EventPayloadEmitted 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, Python, and Go 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:

ParameterDefaultDescription
page1Page number (1-based)
limit20Items per page (max varies by endpoint)
GET /api/v1/agents?page=2&limit=10

Error Codes

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