# Warpmetrics API

Base URL: https://api.warpmetrics.com

## Authentication

API key in the Authorization header:

    Authorization: Bearer wm_live_<your_key>

Get your API key at https://warpmetrics.com/app/api-keys

## Endpoints

### Health

    GET /health
    → { "status": "ok", "timestamp": "..." }

### Ingest events (SDK → API)

    POST /v1/events
    Auth: API key
    Rate limit: 1000/min

Send runs, groups, calls, links, and outcomes in a single batch:

    {
      "runs": [{
        "id": "wm_run_...",
        "label": "code-review",
        "name": "Review PR #42",
        "link": "https://github.com/org/repo/pull/42"
      }],
      "groups": [{
        "id": "wm_grp_...",
        "label": "planning",
        "name": "Planning phase"
      }],
      "calls": [{
        "id": "wm_call_...",
        "provider": "openai",
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "..."}],
        "response": "...",
        "tokens": { "prompt": 150, "completion": 80, "total": 230 },
        "cost": 0.0023,
        "duration": 1200,
        "status": "success",
        "endedAt": "2026-02-08T12:00:00Z"
      }],
      "links": [{
        "parentId": "wm_run_...",
        "childId": "wm_call_...",
        "type": "call"
      }],
      "outcomes": [{
        "refId": "wm_run_...",
        "name": "completed",
        "reason": "All checks passed",
        "source": "ci",
        "tags": ["approved"],
        "metadata": {},
        "timestamp": "2026-02-08T12:00:05Z"
      }]
    }

Response:

    { "success": true, "data": { "received": 5, "processed": 5 } }

### Query data

All query endpoints accept API key or session auth.
Rate limit: 200/min.

    GET /v1/runs                        List runs
    GET /v1/runs/:id                    Get run detail
    GET /v1/runs/:id/calls              Get calls in a run
    GET /v1/groups                      List groups
    GET /v1/calls                       List calls
    GET /v1/outcomes                    List outcomes
    GET /v1/outcomes/classifications    Get outcome classifications
    GET /v1/stats                       Summary statistics
    GET /v1/stream                      Real-time event stream (SSE)

### ID formats

    Runs:    wm_run_<cuid>
    Groups:  wm_grp_<cuid>
    Calls:   wm_call_<cuid>

### Error format

    { "success": false, "error": { "message": "...", "code": "..." } }

Error codes: VALIDATION_ERROR, UNAUTHORIZED, RATE_LIMITED, NOT_FOUND, INTERNAL_ERROR

## SDK

Most users don't call the API directly. Use the SDK:

    npm install @warpmetrics/warp

    import { warp, run, add, outcome } from '@warpmetrics/warp';
    import OpenAI from 'openai';

    const openai = warp(new OpenAI());
    const r = run('my-agent');
    const res = await openai.chat.completions.create({ model: 'gpt-4o', messages: [...] });
    add(r, res);
    outcome(r, 'completed');

Docs: https://warpmetrics.com/llms.txt
SDK: https://www.npmjs.com/package/@warpmetrics/warp