SDK and raw HTTP examples

Small snippets for the common integration paths. Adapters should stay thin and emit through the public Session API.

SDK helpers

Python HTTP client

agent.pypython

import os
import httpx

user_goal = "Book Tuesday at 2pm Pacific, but stop at confirmation"
api_url = os.environ.get("PROMPTETHEUS_API_URL", "http://127.0.0.1:4318")
headers = {
    "Authorization": f"Bearer {os.environ['PROMPTETHEUS_API_KEY']}",
    "Content-Type": "application/json",
}

with httpx.Client(base_url=api_url, headers=headers) as client:
    client.post(
        "/api/traces",
        json={
            "id": "trace_python_1",
            "agent": "browser-agent",
            "project_id": "proj_acmemeet",
            "user_goal": user_goal,
        },
    ).raise_for_status()

    client.post(
        "/api/traces/trace_python_1/events",
        json={
            "events": [
                {
                    "type": "user_message",
                    "session_id": "trace_python_1",
                    "timestamp": "2026-01-01T00:00:00Z",
                    "seq": 0,
                    "idempotency_key": "trace_python_1:dev:0",
                    "payload": {"content": user_goal},
                },
                {
                    "type": "goal_check",
                    "session_id": "trace_python_1",
                    "timestamp": "2026-01-01T00:00:01Z",
                    "seq": 1,
                    "idempotency_key": "trace_python_1:dev:1",
                    "payload": {
                        "passed": False,
                        "mismatches": ["Selected 2:00 AM instead of 2:00 PM"],
                    },
                },
            ]
        },
    ).raise_for_status()

Artifact upload

curlbash

curl -sS -X POST http://127.0.0.1:4318/api/traces/trace_curl_1/artifacts \
  -H "Authorization: Bearer pt_dev_key" \
  -H "Content-Type: image/png" \
  -H "X-Promptetheus-Filename: screenshot.png" \
  -H "X-Promptetheus-Artifact-Type: screenshot" \
  --data-binary @screenshot.png

Generic event batch

events.jsonjson

{
  "events": [{
    "type": "llm_call",
    "session_id": "trace_curl_1",
    "timestamp": "2026-01-01T00:00:02Z",
    "seq": 2,
    "idempotency_key": "trace_curl_1:dev:2",
    "payload": {
        "model": "gpt-5",
        "prompt_ref": "prompt_01",
        "input_tokens": 240,
        "output_tokens": 80,
        "latency_ms": 1260
    }
  }]
}

Raw HTTP

Create trace

curlbash

curl -sS -X POST http://127.0.0.1:4318/api/traces \
  -H "Authorization: Bearer pt_dev_key" \
  -H "Content-Type: application/json" \
  -d '{"user_goal":"Book a room for Tuesday","agent":"demo-agent","id":"trace_curl_1"}'

Append events

curlbash

curl -sS -X POST http://127.0.0.1:4318/api/traces/trace_curl_1/events \
  -H "Authorization: Bearer pt_dev_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "user_message",
      "session_id": "trace_curl_1",
      "timestamp": "2026-01-01T00:00:00Z",
      "seq": 0,
      "idempotency_key": "trace_curl_1:dev:0",
      "payload": {"content": "Book Tuesday"}
    }]
  }'

Analyze with console JWT

curlbash

curl -sS -X POST http://127.0.0.1:4318/api/traces/trace_curl_1/analyze \
  -H "Authorization: Bearer pt_console_token"