HTTP API

The SDKs are thin clients over a small public REST API. Call it directly from any language. The base URL is https://api.promptflip.dev.

Authentication

Send your API key as a bearer token on every request. Create one from Settings → API Keys in the app; keys are prefixed sk_.

Authorization: Bearer sk_...

An API key fetches prompts from the workspace it belongs to — a key created in a workspace serves that workspace's prompts; a personal key serves your personal workspace.

Fetch a prompt

POST /v1/prompts/{key}/fetch — resolve a prompt by key. Every field in the body is optional: inputs for [[placeholders]], assignment_key for sticky A/B assignment, and environment to scope the lookup.

curl -X POST https://api.promptflip.dev/v1/prompts/welcome-message/fetch \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "name": "Alice" },
    "assignment_key": "user-123",
    "environment": "prod"
  }'

A 200 returns the resolved text plus the metadata you need to report results against this run:

{
  "text": "Welcome aboard, Alice!",
  "run_id": "run_9f3c...",
  "model": "gpt-4o-mini",
  "version_id": 7,
  "experiment_id": 3,
  "variant_id": 12
}

Report run results

PATCH /v1/runs/{run_id}/result — attach telemetry to a run. Send any of tokens, latency_ms, and a metrics object of custom numeric values. Returns 204 No Content.

curl -X PATCH https://api.promptflip.dev/v1/runs/run_9f3c.../result \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": 320,
    "latency_ms": 840,
    "metrics": { "converted": 1 }
  }'

Errors

Non-2xx responses use standard status codes:

A 422 carries a structured body so clients can react without parsing prose:

{
  "detail": {
    "error_code": "missing_inputs",
    "names": ["plan"],
    "detail": "Prompt requires inputs that were not provided."
  }
}