Concepts
Versioning
How the API changes over time, and what counts as a breaking change.
The version is in the path
The API version is part of the URL: https://api.zuse.live/v2/.... A version is stable: a request that works against a version today keeps working against it.
| Version | Status | Style |
|---|---|---|
| v2 | Current. | Resources: GET /v2/professionals, GET /v2/licenses, POST /v2/enrichments. |
| v1 | Retired on October 5, 2026. | Operations: POST /v1/verify, POST /v1/source, POST /v1/enrich. |
Any request to a /v1 path is answered with 410 and the code version_retired. v1 was an early-access version that was withdrawn within days of v2 shipping, before general availability.
Moving a v1 request to v2
| v1 | v2 |
|---|---|
POST /v1/verify | GET /v2/licenses |
POST /v1/source | GET /v2/professionals, or GET /v2/practices for profession: "premises" |
POST /v1/enrich | POST /v2/enrichments |
What is different in v2: reads are GET with query parameters instead of POST with a body; every response uses one envelope (data, pagination, meta, billing); errors are { "error": { "code", "message", "request_id" } }; dates are ISO 8601 (2027-08-31); and the filter practice_type is named specialty_type.
One name for each operation, everywhere
Each operation has one name people see, one operation in billing and usage, and the same price on every channel.
| Name | operation | REST | MCP tool | Slack |
|---|---|---|---|---|
| Nearby | source | GET /v2/professionals, GET /v2/practices | source_professionals | nearby 90013 techs |
| License check | verify | GET /v2/licenses, /v2/licenses/{id}, /v2/people/{id}, /v2/clinics/{ref} | verify_license, get_clinic | check Jane Doe CA |
| Background | enrich | POST /v2/enrichments | enrich_person | background 3 |
| Intro notes | brief | POST /v2/briefs | research_brief | intro 3 |
| Web search | web | POST /v2/web-searches | find_people_on_web | nearby 85281 groomers, web |
| Contact | contact | POST /v2/contacts | find_contact | contact 3 |
| Nearby clinics | clinics | GET /v2/clinics | find_clinics | clinics 85004 emergency |
| Clinic research | clinic_research | POST /v2/clinic-research | research_clinic | research 2 |
Changes that do not need a new version
These can ship to an existing version at any time. Write clients that tolerate them:
- New endpoints.
- New optional request parameters.
- New fields in a response.
- New values in an open-ended list, such as a new entry in
red_flags, a new specialty type, or a new errorcode. - New MCP tools.
In practice: ignore response fields you do not recognize, do not fail on an unfamiliar red_flags value, and treat an unknown error code by its HTTP status.
Changes that do need a new version
These are breaking and ship only under a new path:
- Removing or renaming an endpoint, a parameter, or a response field.
- Changing the type or meaning of an existing field.
- Adding a required parameter.
- Changing what an
outcomevalue means.
Retiring a version
v2 is not scheduled for retirement. From v2 on, a version is retired only after it is announced in the changelog, and its responses carry Deprecation and Sunset headers from that announcement until the day it stops answering.
Data is not versioned
The index itself changes continuously as boards are re-ingested and jurisdictions are added. A response can therefore differ from one day to the next for the same request. That is the data changing, not the API.
MCP
The MCP server reports its own version in serverInfo during initialize, and negotiates the protocol version with the client. Tool arguments follow the same compatibility rules as request parameters.