HTTP API

The app is a browser client of this API, and the command line sends the same commands. These pages map the surface as it is in the code today.

Base URL

Every route sits under /api/v1. On a local install:

http://127.0.0.1:8001/api/v1

On the public instance, from a signed-in browser session:

https://app.promptpotter.com/api/v1

Pages

First calls, on a local install

A local install with no sign-in provider configured answers without a session. A campaign needs a backend to score against, by default at http://127.0.0.1:8000.

# 1. the service is up
curl http://127.0.0.1:8001/api/v1/health

# 2. mint a campaign on a dataset that ships with the install
curl -X POST http://127.0.0.1:8001/api/v1/commands/mint-campaign \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind": "mint-campaign", "payload": {"dataset_name": "gsm8k"}}'

# 3. which campaign and cycle that launched
curl http://127.0.0.1:8001/api/v1/sessions/active

# 4. read it, then follow it
curl http://127.0.0.1:8001/api/v1/campaigns/{campaign_id}/cycles/{cycle_id}/dashboard
curl -N http://127.0.0.1:8001/api/v1/campaigns/{campaign_id}/cycles/{cycle_id}/events:subscribe

Errors

Every error answers in one envelope. A body that fails validation is a 422 with request_invalid; a request without a session, where one is required, is a 401.

{
  "error": "request_invalid",
  "message": "…",
  "error_id": "…",
  "details": …
}

Canonical reference

The generated reference is served by the app itself, with every schema: /docs for the interactive page and /openapi.json for the document, on a local install at http://127.0.0.1:8001 and on app.promptpotter.com.