PromptLab API Documentation

A Jam for Tiger tool

PromptLab is a Jam for Tiger tool for running prompts through OpenAI, Gemini, and Claude models via sync and async APIs. All runs are persisted, visible in the PromptLab UI, and queryable via the API.

Base URL: https://promptlab.jamfortiger.com
All endpoints are under /api. Bearer token required on all routes except /api/healthz.
Auth header: Authorization: Bearer <API_AUTH_TOKEN>

Two API surfaces

Providers & Models

provider: "openai" (sync default)

provider: "gemini"

provider: "claude"

POST /api/run — Synchronous API

Blocks until the model responds. Returns text directly in a single HTTP call. Ideal for Google Sheets, shell one-liners, and simple scripts.

Request — application/json

Response 200

{
  "text": "Model response text...",
  "citations": [
    { "index": 1, "url": "https://example.com", "title": "Title", "domain": "example.com" }
  ],
  "citations_grouped_text": "example.com (1 reference)\n[1] Title\nhttps://example.com",
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "web_search_enabled": false,
  "duration_ms": 3241
}

Response 400 / 401 / 500

{
  "errorMessage": "Provider error detail",
  "run_id": "550e8400-e29b-41d4-a716-446655440000"
}

curl — minimal

curl -X POST https://promptlab.jamfortiger.com/api/run \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarise this in 3 bullet points."}'

curl — Claude with system prompt

curl -X POST https://promptlab.jamfortiger.com/api/run \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Review this clause for risks.",
    "system_prompt": "You are a legal analyst. Be concise.",
    "provider": "claude",
    "model": "claude-sonnet-4-5",
    "temperature": 0.2,
    "max_output_tokens": 800
  }'

curl — Gemini with web search

curl -X POST https://promptlab.jamfortiger.com/api/run \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Latest news on LLM context window sizes",
    "provider": "gemini",
    "model": "gemini-2.5-flash",
    "web_search": true
  }'

curl — chain from a previous run

curl -X POST https://promptlab.jamfortiger.com/api/run \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Translate the above into French.",
    "source_run_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

POST /api/runs — Async API

Returns immediately with status: "processing". Poll GET /api/runs/:id until status is "completed" or "failed". Supports both application/json and multipart/form-data (file upload).

Request — JSON (application/json)

Request — File upload (multipart/form-data)

Same fields as above but sent as form fields. Replace promptText with a file upload:

When a file is uploaded: promptText is omitted from all responses. Only promptFile (the filename) is returned.

curl — JSON

curl -X POST https://promptlab.jamfortiger.com/api/runs \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "Explain Kubernetes in plain English.",
    "provider": "openai",
    "model": "gpt-4o",
    "temperature": 0.3,
    "maxOutputTokens": 600,
    "webSearchEnabled": false
  }'

curl — file upload

curl -X POST https://promptlab.jamfortiger.com/api/runs \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -F "promptFile=@/path/to/prompt.txt" \
  -F "provider=openai" \
  -F "model=gpt-4o" \
  -F "temperature=0.3" \
  -F "maxOutputTokens=1000" \
  -F "webSearchEnabled=false"

Initial response (status: processing)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "provider": "openai",
  "model": "gpt-4o",
  "promptFile": "prompt.txt",
  "promptText": null,
  "createdAt": "2025-05-17T00:19:00.000Z"
}

Polling pattern

RUN_ID="550e8400-e29b-41d4-a716-446655440000"
while true; do
  RESULT=$(curl -s -H "Authorization: Bearer $API_AUTH_TOKEN" \
    https://promptlab.jamfortiger.com/api/runs/$RUN_ID)
  STATUS=$(echo $RESULT | jq -r '.status')
  if [ "$STATUS" != "processing" ]; then
    echo $RESULT | jq '{status, rawResponseText, tokensTotal, durationSecs, errorMessage}'
    break
  fi
  sleep 2
done

Completed run response fields

GET /api/runs — List runs

Returns all runs ordered by newest first. Summary objects only (no rawResponseText).

curl -s -H "Authorization: Bearer $API_AUTH_TOKEN" \
  https://promptlab.jamfortiger.com/api/runs | jq '[.[] | {id, status, model, durationSecs}]'

GET /api/runs/:id — Run detail

Full run detail including rawResponseText, all token counts, citations, and errorMessage.

curl -s -H "Authorization: Bearer $API_AUTH_TOKEN" \
  https://promptlab.jamfortiger.com/api/runs/550e8400-e29b-41d4-a716-446655440000

PATCH /api/runs/:id/notes — Update notes

curl -X PATCH https://promptlab.jamfortiger.com/api/runs/550e8400-e29b-41d4-a716-446655440000/notes \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Good result — use for blog post"}'

GET /api/healthz — Health check

No auth required.

curl https://promptlab.jamfortiger.com/api/healthz
# {"status":"ok"}

Use cases

• Google Sheets formula: Use POST /api/run from Apps Script. =RUN_PROMPT(A2) as a custom formula.
• Simple shell script: POST /api/run, get text back immediately. No polling needed.
• Large file processing: Upload a .txt or .md file via multipart to POST /api/runs. No need to inline content in JSON.
• Chaining runs: Use source_run_id (sync) or sourceRunId (async) to feed a previous run's response into the next prompt.
• Web search + citations: Set web_search=true. citations_grouped_text gives a copy-ready formatted block.
• Automated evaluation: Fire multiple POST /api/runs, poll each for completion, compare rawResponseText and token counts.
• Structured extraction: Set system_prompt to instruct JSON output. Claude and GPT-4o are strong at this.
• Annotate runs: After completion, PATCH /api/runs/:id/notes to label runs for filtering in the UI.

Notes & behaviour

• The sync API (/api/run) blocks for the full model response — typical latency 3–30s.
• The async API (/api/runs) responds in ~100ms with status: "processing"; poll every 2s until complete.
• Web search: OpenAI uses web_search_preview; Gemini uses Google Search grounding with citations; Claude does not support web search.
• Temperature is ignored for OpenAI o-series models (o3, o3-mini, o4-mini). Use reasoning / reasoningLevel instead.
• An unknown provider or a model that does not belong to the selected provider returns a 500 error.
• Context window limits: 128K tokens (gpt-4o, gpt-4o-mini), 200K (claude, o-series), 1M (gpt-4.1, gemini-2.5), 2M (gemini-1.5-pro).
• All runs are saved to Prompt Lab history and visible in the UI regardless of which API was used.
• The UI login password (APP_PASSWORD) is separate and does not affect API access.