API reference
The reference is generated from the OpenAPI 3.1 documents the services are tested against.
| API | Host | Who calls it | Reference | OpenAPI |
|---|---|---|---|---|
| Retrieval | api.masterdb.ai |
an AI company’s systems, every request signed | Retrieval API | retrieval.json |
| Verification | verify.masterdb.ai (and the same paths on api.masterdb.ai) |
anyone, no account | Verification API | public.json |
| Business | api.masterdb.ai |
a business’s own systems, signed with an integration key | Business API | business.json |
| Hosted MCP endpoints | mcp.masterdb.ai, mcp.business.masterdb.ai |
MCP clients (MCP servers) | Hosted MCP endpoints | mcp.json |
The sandbox serves each under sandbox.api.masterdb.ai (The sandbox). The portals’ own APIs are not public interfaces and are not documented here.
Also generated on every build:
- Fields, filters and sort keys — every collection’s allow-list.
- Error codes — every stable code, its status and meaning.
- Test vectors — the files every verifier is held to.
Postman
Section titled “Postman”A Postman collection of the retrieval, verification and business APIs, generated from the same OpenAPI documents, with an environment for the sandbox and one for production: collection · sandbox environment · production environment.
Its pre-request script signs every request with RFC 9421 from the variable signing_key, and signs only with a test key made by masterdb keygen (CLI): paste the private JWK it prints, after taking its public half as a sandbox key in the AI Portal (The sandbox) and setting your key’s grant as the value of the MDB-Sandbox-Key header. Any other key is refused. A production key belongs in your own signing system, never in a Postman variable — in production, use the SDK. The verification API needs no key.
Conventions on every API
Section titled “Conventions on every API”- A version in the path (
/v1/). Within a version, changes are additive only: new endpoints, new optional request members, new response members. Ignore members you do not know. See the deprecation policy. - Errors are RFC 9457 problems with a stable
code(Error codes). Idempotency-Keyon everyPOSTthat creates something.- Timestamps are RFC 3339 in UTC; money is a decimal string with its currency, never a floating-point number, in every request and every record. (Search rows, which are an index projection, carry prices as numbers.)
- One host per trust boundary, so the read path never sits behind the same door as a portal session.
What is absent on purpose
Section titled “What is absent on purpose”There is no list-all, no bulk fetch and no export of records to an AI company; no endpoint that says how a business was verified, a take rate, or gross or net amounts across the two sides; and no endpoint that publishes without a seal.