Skip to the documentation
liviamatchAPI

Versioning and changes

The version is in the path. A breaking change is a new version beside the old one, never an edit.

The version is the v1 in every path. A path is a promise to everyone who ever saved it, so a breaking change is a v2 route beside the old one, and v1 keeps answering as it does now.

What counts as breaking

Never in v1May happen in v1
Removing or renaming a field, an endpoint or a codeAdding an endpoint, a field, an optional parameter or a scope
Changing a field's type or what a value meansAdding a value to an enum a field already holds (handle unknown ones)
Making an optional parameter requiredAdding an error code to an endpoint, or a header to an answer
Changing a status code on an existing outcomeReordering fields, or changing the wording of a message

So write clients that ignore fields they do not know and treat an unfamiliar enum value as "other". A full-access key gains each new scope the day it ships; a key that lists its scopes does not.

Staying current

  • openapi.json is built from the same reference as these pages, on every deploy. Regenerate your client from it.
  • GET /api/v1/status names the build that answers, and GET /api/v1/health says whether it is healthy.
  • The changelog lists the changes an integrator would notice.

Changelog

DateChange
2026-10-19The API speaks searches, runs and results (old words and new). New paths: /searches/{id}/runs (Search now), /runs, /runs/{id}, /runs/{id}/results, /runs/{id}/shares and /runs/{id}/pdf. Added fields: a search's links.runs, a draft's search, usage's runs and lastRunAt, and a limit move's runs. Every old path, /briefs, /matches and /search-runs/{id}/pdf among them, answers exactly as before plus Deprecation and Link. The headless runs section is now Headless runs.
2026-10-14Tokens and dollars are Livia staff's. A run's usage (costUsd, inputTokens, outputTokens, and the same on each byService row), the spend report's usage and byDay, each ai in GET /api/v1/org/usage, and a summary alternative's costUsd are in the answer only when the key's maker is Livia staff, and omitted otherwise, never null. Calls, failures and each service's mode stay for everyone.
2026-10-06The agent journey. Clients (/clients), briefs (/searches, and /searches/draft from words), what a brief can match against (/data-sets), matches (/searches/{id}/matches, /matches, /matches/{id}, and the shortlist at /matches/{id}/shortlist), and shares (/matches/{id}/shares, read, email and stop under it). Six scopes: clients:read, clients:write, briefs:read, briefs:write, shares:read, shares:write. GET /api/v1/search/usage gains allowance: the matches used and left this month. A new guide, From a client to a shared shortlist.
2026-10-05The places doors (browser-only) say whose places they answer in attribution, and a provider that fails answers 502 places-failed instead of an empty list or a 500. A place from OpenStreetMap has a photon: id that carries its own coordinates.
2026-10-02This reference and GET /api/v1/openapi.json, generated from the code. POST /api/v1/places/details now answers a bad body with issues and invalid-json like every other door, and the places typeahead ignores a blank lat or lng instead of reading it as 0.
2026-09-27A key is limited by its own requests a minute and an optional monthly cap; the per-address limit was removed. POST /api/v1/transcriptions (browser-only).
2026-09-26The search API: POST /api/v1/search, runs, Idempotency-Key, ETag and If-Match, cursor paging, the run pool, DELETE and spend. API keys, then scopes and organization keys. GET /api/v1/me and the org doors: /org, /org/usage, /org/audit, invitations, members and limits.