API Reference

PromptLab API

The PromptLab REST API lets you resolve prompts, manage versions, configure traffic rules, and trigger deployments — all programmatically.

Base URL:https://api.promptlab.dev/v1

Authentication

All API requests require an API key passed in the Authorization header as a Bearer token. Generate API keys from your workspace settings.

bash

curl https://api.promptlab.dev/v1/prompts \
  -H "Authorization: Bearer pl_sk_live_your_api_key_here"

Keep your API key secret. Do not commit it to source control. Use environment variables — e.g. PROMPTLAB_API_KEY.

Rate Limits

Rate limits are enforced per API key. Limits vary by endpoint and plan.

Endpoint	Free	Pro
POST /resolve	10 req/s	500 req/s
GET /prompts	30 req/min	300 req/min
POST /versions	20 req/min	200 req/min
POST /deploy	5 req/min	60 req/min

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Resolve a Prompt

The core API. Given a prompt name and a user identifier, returns the correct prompt version based on your configured traffic rules.

POST/v1/resolve

bash

curl -X POST https://api.promptlab.dev/v1/resolve \
  -H "Authorization: Bearer pl_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "checkout-assistant",
    "user_id": "usr_8f3k2a",
    "context": {
      "cart_value": 42.50,
      "locale": "en-US"
    }
  }'

Response:

json

{
  "prompt": "checkout-assistant",
  "version": "v4",
  "content": "You are a helpful checkout assistant. Guide the user through their purchase. Be concise and friendly. Always suggest related products when the cart value is under $50.",
  "resolved_at": "2025-05-08T14:23:01Z",
  "traffic_rule": "experiment-april"
}

promptstringThe prompt name as configured in your workspace.required

user_idstringA stable identifier for the end user. Used for consistent hashing to ensure sticky assignment.required

contextobjectOptional key-value map passed to variable interpolation and targeting rules.

List Prompts

Retrieve all prompts in your workspace.

GET/v1/prompts

bash

curl https://api.promptlab.dev/v1/prompts \
  -H "Authorization: Bearer pl_sk_live_..."

Response:

json

{
  "prompts": [
    {
      "id": "prm_abc123",
      "name": "checkout-assistant",
      "active_version": "v4",
      "version_count": 7,
      "updated_at": "2025-05-08T14:00:00Z"
    },
    {
      "id": "prm_def456",
      "name": "support-bot",
      "active_version": "v2",
      "version_count": 3,
      "updated_at": "2025-04-30T09:12:00Z"
    }
  ],
  "total": 2
}

Create a Version

Save a new version of a prompt. Creating a version does not deploy it — use the Deploy endpoint to route traffic.

POST/v1/prompts/:prompt_id/versions

bash

curl -X POST https://api.promptlab.dev/v1/prompts/prm_abc123/versions \
  -H "Authorization: Bearer pl_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You are a helpful checkout assistant. Guide the user through their purchase. Be concise and friendly.",
    "message": "Remove product suggestion — A/B test showed no uplift"
  }'

Response:

json

{
  "version_id": "ver_xyz789",
  "version": "v5",
  "prompt_id": "prm_abc123",
  "content_hash": "sha256:a3f4...",
  "message": "Remove product suggestion — A/B test showed no uplift",
  "created_by": "usr_team_member",
  "created_at": "2025-05-08T15:10:00Z"
}

Deploy a Version

Configure traffic routing for a prompt. Supports gradual rollouts by specifying weights per version. Weights must sum to 100.

POST/v1/prompts/:prompt_id/deploy

bash

curl -X POST https://api.promptlab.dev/v1/prompts/prm_abc123/deploy \
  -H "Authorization: Bearer pl_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "traffic": [
      { "version": "v4", "weight": 90 },
      { "version": "v5", "weight": 10 }
    ],
    "label": "canary-v5-10pct"
  }'

Response:

json

{
  "deployment_id": "dep_mn0pqr",
  "prompt_id": "prm_abc123",
  "label": "canary-v5-10pct",
  "traffic": [
    { "version": "v4", "weight": 90 },
    { "version": "v5", "weight": 10 }
  ],
  "deployed_at": "2025-05-08T15:12:00Z",
  "deployed_by": "usr_team_member"
}

Rollback

Instantly revert to the previous stable deployment. Routes 100% of traffic back to the last fully-deployed version.

POST/v1/prompts/:prompt_id/rollback

bash

curl -X POST https://api.promptlab.dev/v1/prompts/prm_abc123/rollback \
  -H "Authorization: Bearer pl_sk_live_..."

Response:

json

{
  "rolled_back_to": "dep_prev_deployment_id",
  "version": "v4",
  "rolled_back_at": "2025-05-08T15:14:00Z"
}

Errors

The API uses standard HTTP status codes. All error responses include a machine-readable code and a human-readable message.

Status	Code	Meaning
400	invalid_request	Missing or malformed request body.
401	unauthorized	API key missing or invalid.
403	forbidden	API key lacks permission for this action.
404	not_found	Prompt or version does not exist.
422	weight_mismatch	Traffic weights do not sum to 100.
429	rate_limited	Too many requests. See Retry-After header.
500	internal_error	Something went wrong on our end.

Example error response:

json

{
  "error": {
    "code": "weight_mismatch",
    "message": "Traffic weights must sum to 100. Got 95.",
    "docs": "https://docs.promptlab.dev/errors#weight_mismatch"
  }
}