# API reference

Base URL: `https://labs.greatwork.company/v1`. JSON in, JSON out. Authenticate with `Authorization: Bearer gwl_...` (or `X-Api-Key`).

## Run a model

`POST /v1/run`

| Field | Required | Description |
|---|---|---|
| `model` | yes | Model id like `sieve-1`, or the bare name `sieve` for the newest version. |
| `input` | yes | Text (string), a batch (array of strings), or media (URL, data URL, or multipart file). |
| *options* | per model | Named fields next to `input`, listed on each model's page. Unknown fields are rejected with `unknown_param`, so typos don't pass silently. |

Shortcuts that do the same thing: `POST /v1/models/{id}/run` and `POST /v1/{id}` (e.g. `POST /v1/sieve-1` with `{"input": "..."}`).

Response:

```json
{
  "id": "run_...",
  "object": "run",
  "model": "veil-1",
  "created": 1763510400,
  "output": {
    "redacted": "Call [PERSON] at [PHONE]",
    "spans": [
      "..."
    ],
    "counts": {
      "person": 1,
      "phone": 1
    }
  },
  "usage": {
    "units": 1,
    "unit": "text",
    "cost_usd": "0.00002",
    "cost_micros": 20
  },
  "latency_ms": 41
}
```

Response headers: `X-Request-Id` (the run id), `X-Cost-USD`, `X-Balance-USD` (after this call), `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.

### Output conventions

- **Classifications** have `label` and `score` for the answer, and `labels` (every label with its score, best first) or `scores` (label to score).
- **Spans** (entities, PII) are `{type, text, start, end, score}` with character offsets into your input, `end` exclusive.
- **Boxes** are `{x, y, width, height}` in pixels of the original image.
- **Scores** are probabilities from 0 to 1 unless a field says otherwise. Booleans like `flagged` use the `threshold` option.

### Media inputs

- `https://` or `http://` URLs on the public internet (we download them; private addresses are refused). 20-second download limit.
- Data URLs: `data:image/png;base64,...`.
- Multipart: `-F model=ink-1 -F input=@photo.jpg`. Other options go in their own fields; arrays and objects as JSON strings.
- Raw bytes: `POST /v1/run?model=ink-1` with `Content-Type: image/jpeg` and the file as the body.
- Images up to 10 MB; audio up to 25 MB and 5 minutes.

## Cold starts

Models load on first use and stay loaded while they're busy. A call to a model nobody has used in a while takes 2 to 6 seconds while it loads, and its response includes `"cold_start": true`; calls after that take tens of milliseconds for text models. If you call a model rarely and latency matters, a cheap call at startup warms it.

## Estimate a cost

<a id="estimate"></a>`POST /v1/estimate` takes the same body as `/v1/run` and returns the most the call can cost, without running it or touching your balance. No key needed.

```json
{
  "object": "estimate",
  "model": "sort-1",
  "units": 4,
  "unit": "label",
  "max_cost_usd": "0.00004",
  "max_cost_micros": 40,
  "note": "You're billed for the units the model actually uses, never more than this."
}
```

## Models

- `GET /v1/models`: every model with its price, category and modality. No key needed.
- `GET /v1/models/{id}`: one model with options, output fields, limits, caveats and real example requests and outputs.

## Account and usage

- `GET /v1/account`: balance, month-to-date spend, monthly cap, auto top-up settings, and the calling key's own limit and spend.
- `GET /v1/usage?days=30`: calls, units and cost per day per model.
- `GET /v1/runs?limit=50` and `GET /v1/runs/{id}`: recent calls (metadata only: we never store inputs or outputs).

## Idempotency

Send `Idempotency-Key: <any unique string>` on a POST and a retry with the same key and body returns the first response (with `Idempotent-Replayed: true`) instead of running and charging again. Keys last 24 hours. The same key with a different body is a `409 idempotency_key_reused`.

## Rate limits

25 requests per second per account. Batch inputs count as one request, so a batch of 64 texts is the fastest way to process volume. Over the limit you get `429 rate_limited` with `Retry-After`.

## Errors

Every error has the same shape and an HTTP status that tells you what to do:

```json
{
  "error": {
    "type": "payment_required",
    "code": "insufficient_balance",
    "message": "Not enough credit: this call can cost up to $0.00002 and the available balance is $0.0.",
    "add_credit_url": "https://labs.greatwork.company/dashboard/billing",
    "docs_url": "https://labs.greatwork.company/docs/errors#insufficient_balance",
    "request_id": "req_..."
  }
}
```

See [all error codes](https://labs.greatwork.company/docs/errors). Errors are never charged.

## Billing rules

- Before a call runs we hold its maximum cost (from the input size). You're billed the units the model used, never more than the hold.
- Failed calls (4xx and 5xx) cost nothing.
- Audio holds the cost of 5 minutes and settles to the real duration.
