# MasterDB Developers

> MasterDB is where verified businesses publish what they sell and do — products, Business & Brand files, events, jobs and updates — each record sealed by the business, and where AI companies retrieve it with signed requests and receive signed receipts. Everything MasterDB serves can be checked without trusting MasterDB. These are the developer documents for both sides.

Every page is available as Markdown at the URLs below. `llms-full.txt` is all of them in one file. The API reference is generated from the OpenAPI 3.1 documents, linked in the Reference section as JSON.

## Start here

- [MasterDB for developers](https://docs.masterdb.ai/index.md): Integrate with MasterDB as an AI company that retrieves what businesses publish, or as a business, or its integrator, that publishes it.
- [Concepts](https://docs.masterdb.ai/concepts.md): The ideas every integration meets — parties, records, seals, certificates, rows, receipts, the AI policy, blocking, billing and verification — in plain words.
- [The sandbox](https://docs.masterdb.ai/sandbox.md): A complete second environment over a fictional corpus, identical to production in every envelope, receipt, seal and error, for testing both sides of an integration.

## For AI companies

- [Quickstart for AI companies](https://docs.masterdb.ai/ai-companies/quickstart.md): A first signed search and fetch against the sandbox, in TypeScript or Python, with a sandbox key taken in the AI Portal.
- [Keys](https://docs.masterdb.ai/ai-companies/keys.md): Retrieval keys — how an AI company makes, registers, rotates and revokes the keys its systems sign every request with.
- [Signing requests](https://docs.masterdb.ai/ai-companies/signing-requests.md): Exactly how every request to MasterDB is signed with RFC 9421 HTTP Message Signatures and an RFC 9530 Content-Digest, what the server checks, and a complete implementation in Python.
- [Search](https://docs.masterdb.ai/ai-companies/search.md): Find candidates in one collection with your own text query, structured filter and sort — exactly one country, at most 50 rows, no pagination, and a signed receipt.
- [Fetch a record](https://docs.masterdb.ai/ai-companies/fetch.md): Get one record of any type exactly as the business sealed it, with its seal, MasterDB's sidecar, the business's sealed AI policy, provenance and a receipt.
- [Verify what you received](https://docs.masterdb.ai/ai-companies/verify.md): Check rows, records, receipts and certificates without trusting MasterDB — offline with the verifier libraries, or through the public verify endpoint that needs no account.
- [Receipts](https://docs.masterdb.ai/ai-companies/receipts.md): MasterDB's signed statement of what it served, to whom, when and which version — on every search and fetch, listable for reconciliation, and folded into the transparency log.
- [AI policy](https://docs.masterdb.ai/ai-companies/ai-policy.md): What each business permits an AI to do with its data and on its behalf, and the contexts it does not want its data used in — as bits on every row and as a sealed record on every fetch — and the AI-company Terms every delivery travels under.
- [Blocking is invisible](https://docs.masterdb.ai/ai-companies/blocking.md): A business may block an AI company's group. On MasterDB's authenticated surfaces the blocked company sees fewer rows and nothing else — and what that does and does not hide.
- [Usage and billing](https://docs.masterdb.ai/ai-companies/usage-and-billing.md): What counts as a billable query, how your usage is reported, how the prepaid stop works, and what is never billed.
- [Ads and sponsored items](https://docs.masterdb.ai/ai-companies/ads.md): Ask for an ad pool, show what you choose with its label, and confirm each render within ten minutes and each click within 24 hours — plus sponsored and promoted rows in ordinary search, confirmed against the search's receipt. Net prices only.
- [MCP servers](https://docs.masterdb.ai/ai-companies/mcp.md): masterdb-mcp, the self-hosted MCP server an AI company runs with its own key — install, configuration, keys, tools, results, retries and verification — and the hosted public server; and why MasterDB never hosts a billable one.
- [Verifier libraries](https://docs.masterdb.ai/ai-companies/verifier-libraries.md): The open-source libraries (TypeScript and Python, Apache 2.0) that check everything MasterDB signs — seals, rows, receipts, certificates, the key chain, batch proofs and mandates — without an account.
- [The masterdb command line](https://docs.masterdb.ai/ai-companies/cli.md): Verify a record, a fetched response or a receipt from a terminal, fetch and check MasterDB's key set, and make and use test keys.
- [Rate limits and errors](https://docs.masterdb.ai/ai-companies/rate-limits-and-errors.md): The two layers of rate limiting with their figures, the per-key cost budget, and how every refusal is reported — RFC 9457 problems with a stable code to branch on.

## For businesses

- [Publishing on MasterDB](https://docs.masterdb.ai/businesses/overview.md): How a business, or the integrator working for it, gets its products, Business & Brand file, events, jobs and updates to AI companies — sealed, or not published.
- [Publishing through the portal](https://docs.masterdb.ai/businesses/portal-publishing.md): Drafts, validation, the diff, and the save that seals — how a person publishes from the Business Portal.
- [Sealing with a passkey](https://docs.masterdb.ai/businesses/passkey-sealing.md): What a passkey seal is, what it proves, how keys are enrolled, revoked and recovered, and why it cannot be phished.
- [Pushes and mandates](https://docs.masterdb.ai/businesses/pushes.md): Path A — your own system publishes batches sealed with your integration key, under a mandate a person sealed with their passkey. Keys, mandates, the batch seal, outcomes, the price-shock hold, read-back and withdrawal.
- [Large pushes and bulk files](https://docs.masterdb.ai/businesses/large-pushes.md): How a push of more than 50 records is accepted, then processed — polling its status, resuming one that stopped, the bulk-file route for very large loads, and the limits.
- [Imports](https://docs.masterdb.ai/businesses/imports.md): A CSV import merges into your product drafts — only the columns you provide — and publishes nothing until a person reviews the result and seals it.
- [Images](https://docs.masterdb.ai/businesses/images.md): How images are uploaded, checked, re-encoded and served — and what AI companies can learn from them.
- [Geocoding](https://docs.masterdb.ai/businesses/geocoding.md): How an address in a Business & Brand file, event or job becomes a coordinate — in MasterDB's signed sidecar, never in your sealed bytes — and when a coordinate is held for review.
- [Your AI policy](https://docs.masterdb.ai/businesses/ai-policy.md): The sealed record of what you permit AIs to do with your data and on your behalf, and the contexts you do not want it used in — how it is set, how it reaches every AI company, and what it can and cannot enforce.
- [Holds](https://docs.masterdb.ai/businesses/holds.md): The three kinds of hold — a push held for your confirmation, a record held for review, and a business on hold — what each stops, what keeps working, and how each is lifted.
- [What an AI company sees](https://docs.masterdb.ai/businesses/what-ai-companies-see.md): Exactly what AI companies receive about your business, what they never receive, how they find you, and how blocking works from your side.
- [Choosing which emails you get](https://docs.masterdb.ai/businesses/emails.md): Each person chooses how MasterDB emails them — each time, grouped, a daily summary or off — in Settings → Notifications.
- [MCP for businesses](https://docs.masterdb.ai/businesses/mcp.md): The hosted business-side MCP server — draft, publish (which hands you to the portal to seal), status and receipts — which can never seal; and machine publishing with an integration key.

## Reference

- [API reference](https://docs.masterdb.ai/reference.md): The reference for MasterDB's public APIs, generated from their OpenAPI 3.1 documents on every build — never hand-written — with the conventions every API shares.
- [Fields, filters and sort keys](https://docs.masterdb.ai/reference/search-fields.md): For each collection, the text fields a query can match, every filter field with its operators, and every sort key. Generated from the allow-lists the retrieval service enforces.
- [AI policy key](https://docs.masterdb.ai/reference/ai-policy-key.md): The key to the ai_policy_bits every search row carries — each bit of the use, action and blocked masks by name, and the blocked-context codes bc1–bc10 with their meanings. Served at GET /v1/ai-policy-key.
- [The source line](https://docs.masterdb.ai/reference/source-line.md): Specification, version 1: the one line of provenance an AI cites beside an answer built from a MasterDB record, and what the public verify page answers for it.
- [Key custody](https://docs.masterdb.ai/reference/key-custody.md): MasterDB's signed statement of who holds each business key — hosted (MasterDB holds it for the business) or self (the business holds it) — published beside the ADL Certificate, and how the verifier libraries check it.
- [Error codes](https://docs.masterdb.ai/reference/errors.md): Every stable error code MasterDB answers with, its HTTP status and what it means. Generated from the code the services use.
- [Test vectors](https://docs.masterdb.ai/reference/test-vectors.md): The test vectors and the broken-record corpus every MasterDB verifier is held to — good artefacts to accept, broken ones to refuse for a named reason. Download them and hold your own verifier to them.
- [Retrieval API (OpenAPI 3.1)](https://docs.masterdb.ai/reference/retrieval.json): Search, fetch, the ads pool and confirmations, receipts, usage and the AI-company Terms — every request signed.
- [Verification API (OpenAPI 3.1)](https://docs.masterdb.ai/reference/public.json): Certificates, the verify endpoint, the signed key set, projection specifications, the AI policy key and the transparency log — no account.
- [Business API (OpenAPI 3.1)](https://docs.masterdb.ai/reference/business.json): A business's own systems: sealed batch pushes, sealed withdrawals and deletions, catalogue read-back, push attempts, analytics.
- [Hosted MCP endpoints (OpenAPI 3.1)](https://docs.masterdb.ai/reference/mcp.json): The MCP servers MasterDB hosts: the public verification reads, and the business side — Streamable HTTP, one endpoint each.

## Security

- [Security model](https://docs.masterdb.ai/threat-model.md): What MasterDB guarantees, what it does not claim, the protections against each kind of attacker, and how anyone can check what MasterDB serves.

## Versions and support

- [Changelog](https://docs.masterdb.ai/changelog.md): The versions of MasterDB's public APIs and signed formats in force, and how changes an integration could notice are announced.
- [Deprecation policy](https://docs.masterdb.ai/deprecation-policy.md): How MasterDB's APIs and signed formats change — additive within a version, twelve months' notice before anything is removed, and signed artefacts readable forever.
- [Support](https://docs.masterdb.ai/support.md): How to reach MasterDB's developer support — a question about an integration, a problem in the sandbox or these documents, or a security report.

## Optional

- [Everything above in one file](https://docs.masterdb.ai/llms-full.txt)