API Reference

Complete REST API reference. All endpoints accept and return JSON. Authentication via Authorization: Bearer <api_key> header.

Authentication

All endpoints except project creation and health check require a valid API key in the Authorization header:

Authorization: Bearer po_live_abc1234567890...

The API key determines which project and environment the request is scoped to.

Base URL

https://your-api-url  (default: http://localhost:3001)

Health Check

GET/health

Returns server health status. No authentication required.

// Response
{ "status": "ok", "timestamp": "2024-01-15T10:30:00Z" }

Projects

POST/api/v1/projects

Create a new project. Returns the project and an initial API key. No auth required.

// Request body
{ "name": "My AI App" }

// Response
{
  "data": {
    "project": { "id": "uuid", "name": "My AI App" },
    "apiKey": "po_live_abc1234567890..."  // ⚠️ Only shown ONCE
  }
}
GET/api/v1/projects/me

Get the current project info (based on API key).

Prompts

POST/api/v1/prompts

Create a new prompt.

// Request body
{
  "slug": "welcome-email",     // unique within project
  "name": "Welcome Email",
  "description": "Generates welcome emails"  // optional
}

// Response
{
  "data": {
    "id": "uuid",
    "slug": "welcome-email",
    "name": "Welcome Email",
    "description": "Generates welcome emails"
  }
}
GET/api/v1/prompts

List all prompts in the project.

GET/api/v1/prompts/:id

Get a single prompt by ID, including versions and deployments.

DELETE/api/v1/prompts/:id

Delete a prompt and all associated versions and deployments.

Versions

POST/api/v1/prompts/:promptId/versions

Create a new version. Auto-deploys to the dev environment.

// Request body
{
  "systemPrompt": "You are a helpful assistant...",
  "userTemplate": "Hello {{userName}}, welcome to {{plan}}!",
  "model": "gpt-4",           // optional, default: "gpt-4"
  "temperature": 0.7,          // optional, default: 0.7
  "maxTokens": 500,            // optional
  "metadata": { "author": "team-ai" }  // optional
}

// Response
{
  "data": {
    "id": "uuid",
    "versionNumber": 3,
    "systemPrompt": "You are a helpful assistant...",
    "userTemplate": "Hello {{userName}}, welcome to {{plan}}!",
    "model": "gpt-4",
    "temperature": 0.7
  }
}
GET/api/v1/prompts/:promptId/versions

List all versions for a prompt (ordered newest first).

Deployments

POST/api/v1/prompts/:promptId/promote

Promote a version to an environment. Creates or updates the deployment.

// Request body
{
  "environment": "production",
  "versionId": "version-uuid"
}

// Response
{
  "data": {
    "environment": "production",
    "activeVersionId": "version-uuid",
    "promotedAt": "2024-01-15T10:30:00Z"
  }
}
POST/api/v1/prompts/:promptId/rollback

Rollback an environment to the previous version.

// Request body
{ "environment": "production" }

SDK Resolve (Internal)

GET/api/v1/prompts/:slug/resolve

Resolves the active version for a prompt slug. Used internally by the SDK. Environment is determined automatically by the API key.

// Response
{
  "data": {
    "slug": "welcome-email",
    "versionNumber": 3,
    "systemPrompt": "You are a helpful assistant...",
    "userTemplate": "Hello {{userName}}!",
    "model": "gpt-4",
    "temperature": 0.7,
    "maxTokens": null,
    "metadata": {}
  }
}

API Keys

GET/api/v1/api-keys

List all API keys for the project (prefix only, never the full key).

POST/api/v1/api-keys

Create a new API key. The full key is returned once.

// Request body
{
  "environment": "staging",   // 'dev', 'staging', or 'production'
  "label": "CI/CD key"       // optional
}

// Response
{
  "data": {
    "id": "uuid",
    "keyPrefix": "po_live_xyz9",
    "environment": "staging",
    "fullKey": "po_live_xyz9876543210..."  // ⚠️ Only shown ONCE
  }
}
DELETE/api/v1/api-keys/:id

Revoke an API key (soft delete — sets revokedAt).