API reference

Base address: https://ambientprecision.com. Authenticate with Authorization: Bearer <api key>. Keys are made at /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:

{
  "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`.

{ "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.