Old words and new

Searches, runs and results: what each old path, field and code is called now, and what still answers.

On 2026-10-19 the API took the words the product uses: a search is what a client needs, a run is one attempt at it ("Search now"), and its results are the homes that fit. Brief, match and shortlist were the old words.

Every old path still answers exactly as it did, so nothing you built breaks. Each answer also carries Deprecation (when the path became old) and Link (its successor, with your own ids filled in). There is no Sunset: v1 keeps answering until a v2 replaces it. Move when it suits you; idempotency keys, cursors and ETags work across both.

Paths

Old path	Its successor
`GET /api/v1/briefs`	`/api/v1/searches`
`POST /api/v1/briefs`	`/api/v1/searches`
`POST /api/v1/briefs/draft`	`/api/v1/searches/draft`
`GET /api/v1/briefs/{searchId}`	`/api/v1/searches/{searchId}`
`PUT /api/v1/briefs/{searchId}`	`/api/v1/searches/{searchId}`
`POST /api/v1/searches/{searchId}/matches`	`/api/v1/searches/{searchId}/runs`
`GET /api/v1/searches/{searchId}/matches`	`/api/v1/searches/{searchId}/runs`
`GET /api/v1/matches`	`/api/v1/runs`
`GET /api/v1/matches/{matchId}`	`/api/v1/runs/{runId}`
`PUT /api/v1/matches/{matchId}/shortlist`	`/api/v1/runs/{runId}/results`
`POST /api/v1/briefs/{searchId}/matches`	`/api/v1/searches/{searchId}/runs`
`GET /api/v1/briefs/{searchId}/matches`	`/api/v1/searches/{searchId}/runs`
`POST /api/v1/matches/{matchId}/shares`	`/api/v1/runs/{runId}/shares`
`GET /api/v1/matches/{matchId}/shares`	`/api/v1/runs/{runId}/shares`
`GET /api/v1/matches/{matchId}/shares/{shareId}`	`/api/v1/runs/{runId}/shares/{shareId}`
`POST /api/v1/matches/{matchId}/shares/{shareId}/email`	`/api/v1/runs/{runId}/shares/{shareId}/email`
`DELETE /api/v1/matches/{matchId}/shares/{shareId}`	`/api/v1/runs/{runId}/shares/{shareId}`
`GET /api/v1/search-runs/{id}/pdf`	`/api/v1/runs/{runId}/pdf`

Fields

A new path answers the new names. An old path answers the old ones, in the old order. Where a field was added beside its old name on a path that did not move, both answer with the same value.

Old	Where	Now
`briefId`, `briefVersion`	A run, and a run in a list	`searchId`, `searchVersion`
`run`	A run: its live execution	`execution`
`shortlist`, `counts.shortlisted`	A run	`results`, `counts.results`
`links.brief`, `links.shortlist`, `links.pdf`	A run	`links.search`, `links.results`, `links.pdf` (now `/runs/{runId}/pdf`)
`matchId`, `links.match`	A share	`runId`, `links.run`
`links.matches`	A search (both answer)	`links.runs`
`brief`	A draft (both answer)	`search`
`matches`, `lastMatchAt`	Org usage (both answer)	`runs`, `lastRunAt`
`matches`	A limit move (send either, not two different counts)	`runs`

Error codes

An old path answers its old code; the new path answers the new one.

On an old path	On the new path
`brief-unrunnable`	`search-unrunnable`
`match-not-ready`	`run-not-ready`

What did not change

Scopes: briefs:read, briefs:write, search:read and search:run keep their names.
Webhook event types and payloads, such as match.completed and run.succeeded.
The headless /api/v1/search family and its executions, now under Headless runs. There, and in run.* webhooks, a run still means one execution.
Enum values, such as kind: "market" and a notice's match-gone.