# API reference

Base address: `https://ambientprecision.com`. Authenticate with `Authorization: Bearer <api key>`. Keys are made at [/console/keys](/console/keys).

## POST /v1/handoff

| Field | Type | |
|---|---|---|
| `version` | string | `ap-latest` (default), `ap-preview`, or pinned `ap-1.0.0` |
| `state` | string, object or array | The situation. Questions may point into it with backticked paths such as ```order.items[0].name```. |
| `questions` | object | Keyed by your own ids (1 to 20). Several questions become one card. |
| `webhook_url` | string, optional | Public https address, called once when every question is answered. |
| `expires_in` | integer, optional | Seconds, 60 to 2,592,000. Default 7 days. |
| `machine` | object, optional | `{ answers: { <id>: <machine answer> } }`. Hidden from the person until they lock, then shown beside their number. |

Each question: `type` (`likelihood`, `levels`, `pick`), `instructions` (string or object), `criteria` (for `levels` an ordered array of 2 to 10 steps, each a string or `{ what, examples }`; for `pick` an object of up to 255 options mapped to descriptions; we recommend an `other` option).

Returns `201`:

```json
{
  "version": "ap-1.0.0",
  "ticket": "hf_3f9a…",
  "status": "waiting",
  "card_url": "https://ambientprecision.com/t?h=hc_…",
  "questions": ["approve"],
  "answers": {},
  "timing": { "opened_at": null, "answered_at": null }
}
```

## GET /v1/handoff/:ticket

Same shape. `status` is `waiting`, `answered` or `expired`. Answers fill in as the person lands each one.

## GET /v1/versions

Lists aliases and what each resolves to. No key needed.

## Errors

| Status | Meaning |
|---|---|
| 401 | Missing, unknown or revoked key. |
| 422 | A field is wrong. `error.field` names it, for example `questions.tone.criteria`. |
| 429 | Over 20 requests a second for this key, or the monthly allowance is used. Honour `retry-after`. |
| 503 | Briefly overloaded. Honour `retry-after`. |

```json
{ "error": { "code": "invalid_field", "field": "questions.tone.criteria", "message": "levels needs an ordered array of 2 to 10 steps" } }
```

## Published limits (early access)

- 20 requests a second per key, counted per server instance.
- 20 questions per call; 64 KB per body; levels 2 to 10 steps; pick up to 255 options.
- 1,000 human answers a month free.