{ "info": { "_postman_id": "6f0b8a52-3f7e-4c1e-9d8a-2b5e7c1d4a90", "name": "MasterDB", "description": "MasterDB’s public APIs, generated from the OpenAPI documents (clients/postman/generate.mjs). Reference and guides: https://docs.masterdb.ai\n\n**Signing.** Every retrieval and business request is signed by the collection’s pre-request script with RFC 9421 HTTP Message Signatures, from the variable `signing_key`. **It signs only with a test key made by `masterdb keygen`** (an Ed25519 private JWK marked `\"x-masterdb-test\": true`) and refuses any other: use this collection in the sandbox. 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.\n\n**Setup.** Choose the *MasterDB sandbox* environment, run `masterdb keygen`, register the public half in the sandbox AI Portal (or, for the business API, the sandbox Business Portal with a mandate), and paste the private JWK into `signing_key`. The identifiers in the requests are from the sandbox corpus.\n\nRequests that publish (`/v1/publish/…`) need a body your system builds — each record’s exact bytes and a batch seal made with your integration key (the SDK’s `sealBatch`); the example bodies show the shape only.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// MasterDB collection pre-request script: signs the request with RFC 9421 HTTP Message", "// Signatures and an RFC 9530 Content-Digest, exactly as the SDKs do.", "//", "// The key is the collection or environment variable `signing_key`: a private JWK made by", "// `masterdb keygen` — Ed25519, marked \"x-masterdb-test\": true. ANY OTHER KEY IS REFUSED.", "// This collection is for trying the API in the sandbox with a test key; a production key", "// belongs in your own signing system, never in a Postman variable.", "//", "// Self-contained: Ed25519, SHA-512 and SHA-256 are implemented below in plain JavaScript", "// (BigInt), so nothing is fetched and no sandbox library is needed. Not constant-time:", "// fine for a test key in a test tool, and one more reason it refuses anything else.", "//", "// SIGNING_RULES (method, path pattern, tag) is written in by clients/postman/generate.mjs", "// from the OpenAPI documents' security requirements; a request matching none is sent", "// unsigned (the public verification API needs no key).", "/* global pm */", "/* eslint-disable no-bitwise */", "(function masterdbSign() {", " const SIGNING_RULES = [[\"POST\",\"^/v1/search$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/products/search$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/business-files/search$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/events/search$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/jobs/search$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/updates/search$\",\"mdb-retrieval\"],[\"GET\",\"^/v1/records/[^/]+$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/ads/pool$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/ads/render$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/ads/click$\",\"mdb-retrieval\"],[\"GET\",\"^/v1/receipts$\",\"mdb-retrieval\"],[\"GET\",\"^/v1/directory$\",\"mdb-retrieval\"],[\"GET\",\"^/v1/usage$\",\"mdb-retrieval\"],[\"GET\",\"^/v1/terms$\",\"mdb-retrieval\"],[\"GET\",\"^/v1/terms/[^/]+$\",\"mdb-retrieval\"],[\"GET\",\"^/v1/businesses/[^/]+/messaging-form$\",\"mdb-retrieval\"],[\"POST\",\"^/v1/messages$\",\"mdb-message\"],[\"GET\",\"^/v1/certificates/[^/]+$\",null],[\"GET\",\"^/v1/certificates/[^/]+/keys$\",null],[\"GET\",\"^/v1/certificates/[^/]+/key-custody$\",null],[\"GET\",\"^/v1/directory/counts$\",null],[\"POST\",\"^/v1/verify$\",null],[\"POST\",\"^/v1/verify/claim$\",null],[\"GET\",\"^/.well-known/keys$\",null],[\"GET\",\"^/v1/projections/[^/]+/[^/]+$\",null],[\"GET\",\"^/v1/ai-policy-key$\",null],[\"GET\",\"^/v1/spec$\",null],[\"GET\",\"^/v1/log/checkpoint$\",null],[\"GET\",\"^/v1/log/proof$\",null],[\"GET\",\"^/v1/log/consistency$\",null],[\"GET\",\"^/v1/vocabularies/[^/]+$\",null],[\"GET\",\"^/.well-known/http-message-signatures-directory$\",null],[\"GET\",\"^/.well-known/ai-registry$\",null],[\"GET\",\"^/v1/verify/[^/]+$\",null],[\"GET\",\"^/.well-known/masterdb-keys$\",null],[\"POST\",\"^/v1/publish/[^/]+$\",\"mdb-push\"],[\"GET\",\"^/v1/pushes/[^/]+$\",\"mdb-business-read\"],[\"POST\",\"^/v1/bulk-uploads$\",\"mdb-push\"],[\"POST\",\"^/v1/bulk-imports$\",\"mdb-push\"],[\"POST\",\"^/v1/publish/[^/]+/withdraw$\",\"mdb-push\"],[\"POST\",\"^/v1/publish/[^/]+/delete$\",\"mdb-push\"],[\"GET\",\"^/v1/catalogue$\",\"mdb-business-read\"],[\"GET\",\"^/v1/catalogue/[^/]+$\",\"mdb-business-read\"],[\"GET\",\"^/v1/push-attempts$\",\"mdb-business-read\"],[\"GET\",\"^/v1/seal-context$\",\"mdb-business-read\"],[\"GET\",\"^/v1/analytics/daily$\",\"mdb-business-read\"],[\"GET\",\"^/v1/analytics/who-is-asking$\",\"mdb-business-read\"]];", "", " // ── Bytes ──────────────────────────────────────────────────────────────", " const utf8 = (s) => {", " const bin = unescape(encodeURIComponent(s));", " const out = new Uint8Array(bin.length);", " for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);", " return out;", " };", " const concat = (...parts) => {", " const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));", " let o = 0;", " for (const p of parts) {", " out.set(p, o);", " o += p.length;", " }", " return out;", " };", " const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';", " const b64 = (bytes) => {", " let s = '';", " for (let i = 0; i < bytes.length; i += 3) {", " const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);", " s += B64[(n >> 18) & 63] + B64[(n >> 12) & 63] + (i + 1 < bytes.length ? B64[(n >> 6) & 63] : '=') + (i + 2 < bytes.length ? B64[n & 63] : '=');", " }", " return s;", " };", " const b64url = (bytes) => b64(bytes).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');", " const fromB64url = (text) => {", " const s = text.replace(/-/g, '+').replace(/_/g, '/');", " const out = [];", " let buf = 0;", " let bits = 0;", " for (const c of s) {", " if (c === '=') break;", " const v = B64.indexOf(c);", " if (v < 0) throw new Error('signing_key: not base64url');", " buf = (buf << 6) | v;", " bits += 6;", " if (bits >= 8) {", " bits -= 8;", " out.push((buf >> bits) & 255);", " }", " }", " return new Uint8Array(out);", " };", "", " // ── SHA-2 (FIPS 180-4); round constants derived from the primes ─────────", " const primes = (n) => {", " const out = [];", " for (let c = 2; out.length < n; c++) if (out.every((p) => c % p !== 0)) out.push(c);", " return out;", " };", " const iroot = (x, k) => {", " // floor(x^(1/k)) for BigInt x, by Newton's method", " let r = 1n << BigInt(Math.ceil(x.toString(2).length / Number(k)) + 1);", " for (;;) {", " const next = ((k - 1n) * r + x / r ** (k - 1n)) / k;", " if (next >= r) return r;", " r = next;", " }", " };", " const frac = (p, root, bits) => iroot(BigInt(p) << BigInt(bits * Number(root)), root) & ((1n << BigInt(bits)) - 1n);", "", " const SHA256_K = primes(64).map((p) => Number(frac(p, 3n, 32)));", " const SHA256_H = primes(8).map((p) => Number(frac(p, 2n, 32)));", " const sha256 = (msg) => {", " const len = msg.length;", " const padded = new Uint8Array(((len + 9 + 63) >> 6) << 6);", " padded.set(msg);", " padded[len] = 0x80;", " const bitLen = BigInt(len) * 8n;", " for (let i = 0; i < 8; i++) padded[padded.length - 1 - i] = Number((bitLen >> BigInt(8 * i)) & 255n);", " const h = SHA256_H.slice();", " const w = new Array(64);", " const rotr = (x, n) => (x >>> n) | (x << (32 - n));", " for (let o = 0; o < padded.length; o += 64) {", " for (let i = 0; i < 16; i++) w[i] = ((padded[o + 4 * i] << 24) | (padded[o + 4 * i + 1] << 16) | (padded[o + 4 * i + 2] << 8) | padded[o + 4 * i + 3]) >>> 0;", " for (let i = 16; i < 64; i++) {", " const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);", " const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);", " w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;", " }", " let [a, b, c, d, e, f, g, hh] = h;", " for (let i = 0; i < 64; i++) {", " const t1 = (hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + SHA256_K[i] + w[i]) >>> 0;", " const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;", " hh = g;", " g = f;", " f = e;", " e = (d + t1) >>> 0;", " d = c;", " c = b;", " b = a;", " a = (t1 + t2) >>> 0;", " }", " [a, b, c, d, e, f, g, hh].forEach((v, i) => (h[i] = (h[i] + v) >>> 0));", " }", " const out = new Uint8Array(32);", " h.forEach((v, i) => {", " out[4 * i] = v >>> 24;", " out[4 * i + 1] = (v >>> 16) & 255;", " out[4 * i + 2] = (v >>> 8) & 255;", " out[4 * i + 3] = v & 255;", " });", " return out;", " };", "", " const M64 = (1n << 64n) - 1n;", " const SHA512_K = primes(80).map((p) => frac(p, 3n, 64));", " const SHA512_H = primes(8).map((p) => frac(p, 2n, 64));", " const sha512 = (msg) => {", " const len = msg.length;", " const padded = new Uint8Array(((len + 17 + 127) >> 7) << 7);", " padded.set(msg);", " padded[len] = 0x80;", " const bitLen = BigInt(len) * 8n;", " for (let i = 0; i < 16; i++) padded[padded.length - 1 - i] = Number((bitLen >> BigInt(8 * i)) & 255n);", " const h = SHA512_H.slice();", " const w = new Array(80);", " const rotr = (x, n) => ((x >> n) | (x << (64n - n))) & M64;", " for (let o = 0; o < padded.length; o += 128) {", " for (let i = 0; i < 16; i++) {", " let v = 0n;", " for (let j = 0; j < 8; j++) v = (v << 8n) | BigInt(padded[o + 8 * i + j]);", " w[i] = v;", " }", " for (let i = 16; i < 80; i++) {", " const s0 = rotr(w[i - 15], 1n) ^ rotr(w[i - 15], 8n) ^ (w[i - 15] >> 7n);", " const s1 = rotr(w[i - 2], 19n) ^ rotr(w[i - 2], 61n) ^ (w[i - 2] >> 6n);", " w[i] = (w[i - 16] + s0 + w[i - 7] + s1) & M64;", " }", " let [a, b, c, d, e, f, g, hh] = h;", " for (let i = 0; i < 80; i++) {", " const t1 = (hh + (rotr(e, 14n) ^ rotr(e, 18n) ^ rotr(e, 41n)) + ((e & f) ^ (~e & M64 & g)) + SHA512_K[i] + w[i]) & M64;", " const t2 = ((rotr(a, 28n) ^ rotr(a, 34n) ^ rotr(a, 39n)) + ((a & b) ^ (a & c) ^ (b & c))) & M64;", " hh = g;", " g = f;", " f = e;", " e = (d + t1) & M64;", " d = c;", " c = b;", " b = a;", " a = (t1 + t2) & M64;", " }", " [a, b, c, d, e, f, g, hh].forEach((v, i) => (h[i] = (h[i] + v) & M64));", " }", " const out = new Uint8Array(64);", " h.forEach((v, i) => {", " for (let j = 0; j < 8; j++) out[8 * i + j] = Number((v >> BigInt(8 * (7 - j))) & 255n);", " });", " return out;", " };", "", " // ── Ed25519 (RFC 8032) ─────────────────────────────────────────────────", " const P = 2n ** 255n - 19n;", " const L = 2n ** 252n + 27742317777372353535851937790883648493n;", " const mod = (a, m = P) => ((a % m) + m) % m;", " const pow = (b, e) => {", " let r = 1n;", " b = mod(b);", " while (e > 0n) {", " if (e & 1n) r = mod(r * b);", " b = mod(b * b);", " e >>= 1n;", " }", " return r;", " };", " const inv = (a) => pow(a, P - 2n);", " const D2 = mod(2n * -121665n * inv(121666n));", " const BASE = [15112221349535400772501151409588531511454012693041857206046113283949847762202n, 46316835694926478169428394003475163141307993866256225615783033603165251855960n];", " const ext = ([x, y]) => [x, y, 1n, mod(x * y)];", " const add = ([x1, y1, z1, t1], [x2, y2, z2, t2]) => {", " const a = mod((y1 - x1) * (y2 - x2));", " const b = mod((y1 + x1) * (y2 + x2));", " const c = mod(t1 * D2 * t2);", " const d = mod(2n * z1 * z2);", " const e = b - a;", " const f = d - c;", " const g = d + c;", " const h = b + a;", " return [mod(e * f), mod(g * h), mod(f * g), mod(e * h)];", " };", " const mul = (s, point) => {", " let q = [0n, 1n, 1n, 0n];", " let p = point;", " while (s > 0n) {", " if (s & 1n) q = add(q, p);", " p = add(p, p);", " s >>= 1n;", " }", " return q;", " };", " const encodePoint = ([x, y, z]) => {", " const zi = inv(z);", " const ax = mod(x * zi);", " let ay = mod(y * zi);", " const out = new Uint8Array(32);", " for (let i = 0; i < 32; i++) {", " out[i] = Number(ay & 255n);", " ay >>= 8n;", " }", " if (ax & 1n) out[31] |= 0x80;", " return out;", " };", " const leInt = (bytes) => bytes.reduceRight((acc, b) => (acc << 8n) | BigInt(b), 0n);", " const leBytes = (n) => {", " const out = new Uint8Array(32);", " for (let i = 0; i < 32; i++) {", " out[i] = Number(n & 255n);", " n >>= 8n;", " }", " return out;", " };", " const ed25519 = (seed) => {", " const h = sha512(seed);", " const a = h.slice(0, 32);", " a[0] &= 248;", " a[31] &= 127;", " a[31] |= 64;", " const scalar = leInt(a);", " const publicKey = encodePoint(mul(scalar, ext(BASE)));", " return {", " publicKey,", " sign: (msg) => {", " const r = mod(leInt(sha512(concat(h.slice(32), msg))), L);", " const R = encodePoint(mul(r, ext(BASE)));", " const k = mod(leInt(sha512(concat(R, publicKey, msg))), L);", " return concat(R, leBytes(mod(r + k * scalar, L)));", " },", " };", " };", "", " // ── Which tag, if any ──────────────────────────────────────────────────", " const rawUrl = pm.variables.replaceIn(pm.request.url.toString());", " const m = /^(https?):\\/\\/([^/?#]+)([^?#]*)(?:\\?([^#]*))?$/.exec(rawUrl);", " if (m === null) throw new Error(`MasterDB signing: not an absolute URL: ${rawUrl}`);", " const [, scheme, authorityRaw, pathRaw, query] = m;", " const path = pathRaw === '' ? '/' : pathRaw;", " const method = pm.request.method.toUpperCase();", " const rule = SIGNING_RULES.find(([mm, re]) => mm === method && new RegExp(re).test(path));", " if (rule === undefined || rule[2] === null) return; // the public verification API: unsigned", "", " // ── The key: a test key, or nothing ────────────────────────────────────", " const keyText = pm.variables.get('signing_key');", " if (!keyText) throw new Error('MasterDB signing: set the variable signing_key to a test key made by `masterdb keygen`');", " let jwk;", " try {", " jwk = typeof keyText === 'string' ? JSON.parse(keyText) : keyText;", " } catch (e) {", " throw new Error('MasterDB signing: signing_key is not a JSON Web Key');", " }", " if (jwk['x-masterdb-test'] !== true) throw new Error('MasterDB signing: signing_key is not a test key (made by `masterdb keygen`). A production key belongs in your own signing system, never in a Postman variable.');", " if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.d !== 'string') throw new Error('MasterDB signing: this collection signs with Ed25519 test keys only');", " const key = ed25519(fromB64url(jwk.d));", " const x = b64url(key.publicKey);", " if (jwk.x !== undefined && jwk.x !== x) throw new Error('MasterDB signing: signing_key x does not match its d');", " const keyid = b64url(sha256(utf8(`{\"crv\":\"Ed25519\",\"kty\":\"OKP\",\"x\":\"${x}\"}`)));", "", " // ── The body, exactly as it will be sent ───────────────────────────────", " let body;", " if (pm.request.body && pm.request.body.mode === 'raw' && pm.request.body.raw) {", " const resolved = pm.variables.replaceIn(pm.request.body.raw);", " pm.request.body.update(resolved);", " body = utf8(resolved);", " }", "", " // ── RFC 9421 ───────────────────────────────────────────────────────────", " let authority = authorityRaw.toLowerCase();", " const defaultPort = scheme === 'https' ? ':443' : ':80';", " if (authority.endsWith(defaultPort)) authority = authority.slice(0, -defaultPort.length);", " const components = [", " ['@method', method],", " ['@authority', authority],", " ['@path', path],", " ];", " if (query !== undefined && query !== '') components.push(['@query', `?${query}`]);", " if (body !== undefined && body.length > 0) {", " const digest = `sha-256=:${b64(sha256(body))}:`;", " pm.request.headers.upsert({ key: 'Content-Digest', value: digest });", " components.push(['content-digest', digest]);", " }", " const created = Math.floor(Date.now() / 1000);", " const nonce = `${pm.variables.replaceIn('{{$guid}}')}${pm.variables.replaceIn('{{$guid}}')}`.replace(/-/g, '');", " const params = `(${components.map(([n]) => `\"${n}\"`).join(' ')});created=${created};expires=${created + 300};nonce=\"${nonce}\";keyid=\"${keyid}\";tag=\"${rule[2]}\"`;", " const base = `${components.map(([n, v]) => `\"${n}\": ${v}`).join('\\n')}\\n\"@signature-params\": ${params}`;", " pm.request.headers.upsert({ key: 'Signature-Input', value: `sig1=${params}` });", " pm.request.headers.upsert({ key: 'Signature', value: `sig1=:${b64(key.sign(utf8(base)))}:` });", "})();", "" ] } } ], "variable": [ { "key": "baseUrl", "value": "https://sandbox.api.masterdb.ai", "type": "string" }, { "key": "signing_key", "value": "", "type": "secret", "description": "A TEST key only: the private JWK printed by `masterdb keygen`." } ], "item": [ { "name": "Retrieval API — AI companies", "description": "The read path. Every request is signed with RFC 9421 by a\nretrieval key the AI company registered in the AI Portal (`tag=\"mdb-retrieval\"`);\nidentity comes only from the key. Every search and fetch returns a receipt: MasterDB's\nsigned statement of what it served, to whom and when.\n\nThe sandbox alone also accepts `Authorization: Bearer ` in place of\na signature, for one hour after a key is registered (the token comes back once, with the\nregistration), so a developer can see a response before writing a signer.\nProduction never accepts a bearer token.\n\nThere is no list endpoint, no \"all records for a business\", no batch fetch and no\nexport: a fetch takes one id. A search returns at most 50 rows and has no\nsecond page; if the answer is not in the 50, refine the criteria and search\nagain. Billing counts a search that returns at least one row and a fetch that returns\na record; refusals and failures are never billed. A prepay company whose\nallowance is spent is answered `402` `allowance_exhausted` — and `503`\n`unavailable` with `Retry-After` in the moment the allowance cannot be checked (the stop\nfails closed; never billed); a key over its\nrequest rate or its per-minute query-cost budget `429` `rate_limited` with\n`Retry-After`. Rows and records from a business that blocked your group are\nabsent, and nothing anywhere says so.\n\nA request body is at most 16 KiB (64 KiB on the ads routes). A larger one, declared in\n`Content-Length` or sent chunked without it, is answered `413` `record_too_large` and is\nnot read past the limit; until 5 October 2026 a declared length over the limit answered\n`400` `request_invalid`.\n\nErrors are RFC 9457 problem details with a stable `code` on every response. The version is in the path; changes within `v1` are additive only.", "item": [ { "name": "Search", "description": "Find candidates in one collection, with your own query, filter and sort.", "item": [ { "name": "Search one collection", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/search", "host": [ "{{baseUrl}}" ], "path": [ "v1", "search" ] }, "body": { "mode": "raw", "raw": "{\n \"collection\": \"products\",\n \"q\": \"trail running shoes\",\n \"query_by\": [\n \"product_name\",\n \"tags\"\n ],\n \"filter\": {\n \"all\": [\n {\n \"country\": \"US\"\n },\n {\n \"price_amount\": {\n \"lte\": 150\n }\n },\n {\n \"availability\": \"available\"\n }\n ]\n },\n \"sort_by\": \"price_amount:asc\",\n \"limit\": 25,\n \"client_query_id\": \"q-2026-10-01-0001\",\n \"session_ref\": \"9f1c2e7a-conv\",\n \"topic_keywords\": [\n \"trail running\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Finds candidates in one collection — `products`, `business_files`, `events`, `jobs`\nor `updates` — with the caller's own text query, structured filter and sort. The\nfilter must name exactly one country and the sort is mandatory:\nMasterDB never chooses an order, so a caller that wants relevance order writes\n`_text_match:desc`. Only the fields, operators and sort keys of the collection's\nallow-list exist; anything else is refused with a reason, never rewritten silently.\nThe answer is at most 50 short rows, each with its `adl_*` fields and the business's AI\npolicy in force (`ai_policy_bits`: what it permits, and the blocked contexts bc1–bc10 —\nthe key is `GET /v1/ai-policy-key`), and a signed receipt. Rows from businesses that blocked\nyour group are simply absent; nothing says so.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Search products", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/products/search", "host": [ "{{baseUrl}}" ], "path": [ "v1", "products", "search" ] }, "body": { "mode": "raw", "raw": "{\n \"q\": \"trail running shoes\",\n \"filter\": {\n \"all\": [\n {\n \"country\": \"US\"\n },\n {\n \"price_amount\": {\n \"lte\": \"150.00\"\n }\n },\n {\n \"on_sale\": true\n }\n ]\n },\n \"sort_by\": \"_text_match:desc,price_amount:asc\",\n \"limit\": 10\n}", "options": { "raw": { "language": "json" } } }, "description": "The typed address for `POST /v1/search` with `collection: products`, routed inside the\nsame service with no redirect and no added latency. It exists so this page\nshows only the products fields, filters and sort keys. `price_amount` and\n`price_currency` apply to the one country the filter names.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Search business files", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/business-files/search", "host": [ "{{baseUrl}}" ], "path": [ "v1", "business-files", "search" ] }, "body": { "mode": "raw", "raw": "{\n \"q\": \"independent bookshop\",\n \"filter\": {\n \"all\": [\n {\n \"country\": \"IE\"\n },\n {\n \"has_locations\": true\n },\n {\n \"location_geo\": {\n \"near\": {\n \"lat\": 53.3438,\n \"lng\": -6.2546,\n \"radius_km\": 5\n }\n }\n }\n ]\n },\n \"sort_by\": \"_text_match:desc\"\n}", "options": { "raw": { "language": "json" } } }, "description": "The typed address for `POST /v1/search` with `collection: business_files`: a business's\nBusiness & Brand Identity file for a set of countries — what it is, what it sells,\nwhere it has locations, how it delivers and takes payment. The five \"represent us\"\ntexts are never on a search row; they come with a fetch.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Search events", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/events/search", "host": [ "{{baseUrl}}" ], "path": [ "v1", "events", "search" ] }, "body": { "mode": "raw", "raw": "{\n \"q\": \"wine tasting\",\n \"filter\": {\n \"all\": [\n {\n \"country\": \"US\"\n },\n {\n \"start_at\": {\n \"gte\": \"2026-10-01T00:00:00Z\",\n \"lt\": \"2026-10-08T00:00:00Z\"\n }\n },\n {\n \"city\": \"Portland\"\n }\n ]\n },\n \"sort_by\": \"start_at:asc\"\n}", "options": { "raw": { "language": "json" } } }, "description": "The typed address for `POST /v1/search` with `collection: events`: things a business\nis running, in person or online, with their dates, place and price range.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Search jobs", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/jobs/search", "host": [ "{{baseUrl}}" ], "path": [ "v1", "jobs", "search" ] }, "body": { "mode": "raw", "raw": "{\n \"q\": \"pastry chef\",\n \"filter\": {\n \"all\": [\n {\n \"country\": \"IE\"\n },\n {\n \"employment_type\": {\n \"in\": [\n \"full_time\",\n \"part_time\"\n ]\n }\n },\n {\n \"salary_min\": {\n \"gte\": \"30000\"\n }\n }\n ]\n },\n \"sort_by\": \"salary_max:desc\",\n \"limit\": 20\n}", "options": { "raw": { "language": "json" } } }, "description": "The typed address for `POST /v1/search` with `collection: jobs`: openings a business\nhas published, with how and where the work is done and what it pays.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Search updates", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/updates/search", "host": [ "{{baseUrl}}" ], "path": [ "v1", "updates", "search" ] }, "body": { "mode": "raw", "raw": "{\n \"q\": \"opening hours\",\n \"filter\": {\n \"all\": [\n {\n \"country\": \"GB\"\n },\n {\n \"relevant_until\": {\n \"gte\": \"2026-10-01T00:00:00Z\"\n }\n }\n ]\n },\n \"sort_by\": \"published_at:desc\"\n}", "options": { "raw": { "language": "json" } } }, "description": "The typed address for `POST /v1/search` with `collection: updates`: news a business\nhas published about itself, with how long it stays relevant.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] } ] }, { "name": "Records", "description": "Fetch one record exactly as the business sealed it.", "item": [ { "name": "Fetch one record", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/records/mdb_xmomas3i3kzkdwyqpfoxou5rea", "host": [ "{{baseUrl}}" ], "path": [ "v1", "records", "mdb_xmomas3i3kzkdwyqpfoxou5rea" ] }, "description": "Returns one record of any of the five types exactly as the business sealed it: the\nbytes verbatim, the seal, MasterDB's signed sidecar, the business's sealed AI policy\nrecord in force now (`ai_policy` — what proves a row's `ai_policy_bits`), the \"represent us\" texts for a business file, provenance (with the\nsource line to cite) and a receipt. For a business file with\nauthorised endpoints, `endpoints` says whether MasterDB still stands behind that section\ntoday: `suspended` means continuous domain assurance lost control of one of its domains —\nuse none of its checkout, order, booking or API addresses. A record from a\nbusiness that blocked your group, a withdrawn record and one\nthat never existed all answer the same 404 with the same body, no sooner than 20 ms\nafter arrival, so none can be told from another. One id per call: there is no\nbatch fetch.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] } ] }, { "name": "Ads", "description": "The ad and sponsored-item pool, and the render and click confirmations.", "item": [ { "name": "Get the ad pool for a context", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/ads/pool", "host": [ "{{baseUrl}}" ], "path": [ "v1", "ads", "pool" ] }, "body": { "mode": "raw", "raw": "{\n \"country\": \"US\",\n \"keywords\": [\n \"running shoes\",\n \"trail running\"\n ],\n \"formats\": [\n \"card\",\n \"compact\"\n ],\n \"sort_by\": \"net_price:desc\",\n \"max_per_campaign\": 2,\n \"size\": 5,\n \"session_ref\": \"9f1c2e7a-conv\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Returns up to 20 ads for one country and a few subject keywords, ordered by the sort\nyou state (refused without one) and optionally capped per campaign. Keywords\nare an exact filter, never a text query, and must be subject terms — never the\nuser's question, never a user or conversation id (Rule 43). Each ad comes with its\nwhole creative, the advertiser's seal, signed links to its images (valid fifteen\nminutes; fetch them server-side, never from an end user's browser), the net price you\nwould earn for it, its label and a render token; gross prices never leave MasterDB.\nThe sort keys are `net_price`, `published_at`, `keyword_matches` and `random` (seeded\nby the pool's `retrieval_id`), each `:asc` or `:desc`, up to three. The pool\ncarries a receipt like every other response. An ad already rendered in the\nconversation (`session_ref`) is left out of its pools for 60 minutes unless its\nadvertiser allows repeats. You choose what to render; confirm each render\nwith `POST /v1/ads/render` within ten minutes.\n\n**Each item verifies on its own** (ADL spec): an ad is rendered alone, so\nit carries the exact bytes the advertiser sealed (`record_base64`), its signed index row\n(`row`: the advertiser's seal inline as `adl_origin_seal`, the destination as `adl_dest`,\na hash per image as `adl_creative`, and the advertiser's `ai_policy_bits`, as on every\nsearch row) and the advertiser's sealed AI policy (`ai_policy`, as every fetch carries it). Check the row's signature, that its `adl_origin` is the hash of those bytes, the\nseal over them, and that every text and link in `creative` is the sealed one; hash each\nimage you fetch against `adl_creative`. The SDKs' `verifyAdItem` / `verify_ad_item` does\nall of it from public data, and `POST /v1/verify {ad_item}` answers the same question.\nNo fetch of an ad is needed, and none is offered.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Confirm a render", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Required on every POST that creates something. 1–255 printable\nASCII characters. The same key with the same request replays the first answer; with a\ndifferent request it is `idempotency_key_reused` (422); while the first is still in\nflight it is `idempotency_in_progress` (409).\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/ads/render", "host": [ "{{baseUrl}}" ], "path": [ "v1", "ads", "render" ] }, "body": { "mode": "raw", "raw": "{\n \"render_token\": {\n \"payloadType\": \"application/vnd.masterdb.render.v1+json\",\n \"payload\": \"eyJ0b2tlbl9pZCI6InJ0XzEifQ==\",\n \"signatures\": [\n {\n \"keyid\": \"AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4\",\n \"sig\": \"3q2+7w==\"\n }\n ]\n },\n \"format\": \"card\",\n \"session_ref\": \"9f1c2e7a-conv\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Confirms that you rendered an ad — with the render token from the pool — or a\nsponsored or promoted row from a search, with that search's `retrieval_id`, the row's\nid and the search's receipt, which must show the row served with its `sponsored`\nmarker (a row served unmarked is never charged). The region that minted the token, or\nserved the search, decides (a confirmation that reaches another region is forwarded\nto it and its answer relayed unchanged), checks the ten-minute window and single use\non MasterDB's clock, turns the reserve into spend — for a sponsored row, reserves and\nconfirms in one step — and returns a click token, valid 24 hours, and for a\nsponsored or promoted row the label to show (`Sponsored`, `Promoted event`, `Promoted\nvacancy`, `Promoted update`). A second render of the same item in one conversation is\naccepted but neither charged nor paid, unless its advertiser allows repeats.\nA late render is answered `200` with `accepted: false` and `reason: window_expired`,\na row whose budget ran out with `budget_exhausted`, and a replay with `token_reused`:\nrecorded, never billed, never paid.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Confirm a click", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Required on every POST that creates something. 1–255 printable\nASCII characters. The same key with the same request replays the first answer; with a\ndifferent request it is `idempotency_key_reused` (422); while the first is still in\nflight it is `idempotency_in_progress` (409).\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/ads/click", "host": [ "{{baseUrl}}" ], "path": [ "v1", "ads", "click" ] }, "body": { "mode": "raw", "raw": "{\n \"click_token\": {\n \"payloadType\": \"application/vnd.masterdb.click.v1+json\",\n \"payload\": \"eyJ0b2tlbl9pZCI6ImN0XzEifQ==\",\n \"signatures\": [\n {\n \"keyid\": \"AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4\",\n \"sig\": \"3q2+7w==\"\n }\n ]\n },\n \"session_ref\": \"9f1c2e7a-conv\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Confirms that a person clicked a rendered ad, with the click token from the render\nconfirmation (valid 24 hours) and your conversation reference. A repeat click on the\nsame ad from the same conversation within 15 minutes is recorded and not billed.\nMasterDB is never in the redirect path: send the person to the destination yourself.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] } ] }, { "name": "Receipts and usage", "description": "Your own receipts and usage, for reconciliation.", "item": [ { "name": "List your own receipts", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/receipts?from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z", "host": [ "{{baseUrl}}" ], "path": [ "v1", "receipts" ], "query": [ { "key": "from", "value": "2026-10-01T00:00:00Z", "disabled": false, "description": "Start of the window, inclusive (RFC 3339 UTC or a date)." }, { "key": "to", "value": "2026-10-02T00:00:00Z", "disabled": false, "description": "End of the window, exclusive (RFC 3339 UTC or a date)." }, { "key": "key_id", "value": "", "disabled": true, "description": "Only receipts for requests signed by this key." }, { "key": "ai_company_uuid", "value": "", "disabled": true, "description": "Only receipts for this legal entity of your group." }, { "key": "cursor", "value": "", "disabled": true, "description": "The opaque `next_cursor` of the previous page." } ] }, "description": "Returns the receipts MasterDB issued to your own keys in a time window, per key and\nper legal entity, so you can reconcile what you asked for against what you were\nbilled. Only ever your own: the key that signs this request decides whose receipts\nthese are.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Read your usage", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/usage?from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z", "host": [ "{{baseUrl}}" ], "path": [ "v1", "usage" ], "query": [ { "key": "from", "value": "2026-10-01T00:00:00Z", "disabled": false, "description": "Start of the window, inclusive (RFC 3339 UTC or a date)." }, { "key": "to", "value": "2026-10-02T00:00:00Z", "disabled": false, "description": "End of the window, exclusive (RFC 3339 UTC or a date)." } ] }, "description": "Your usage read model: queries and fetches by day, by key, by legal entity and\nby collection, and the pricing tiers consumed, as at the end of the last complete\nhour. Never which businesses matched and never another company's figures. **No\nfigure about blocks** — no count, band or aggregate, here or anywhere on the AI side.\n\nThese are the figures the AI Portal shows, read from the same hourly read model: a count below 50 is the band `<50`. The window is whole UTC\ndays, the last 30 when neither bound is given.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] } ] }, { "name": "Terms", "description": "The AI-company Terms in force and every past version.", "item": [ { "name": "Read the Terms in force", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/terms", "host": [ "{{baseUrl}}" ], "path": [ "v1", "terms" ] }, "description": "The AI-company Terms in force now: the text, its version and its hash. The use\nconditions every delivery travels under — once, in one chat, no training, no caching\n— are stated here once and referenced by version, not repeated on every response.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] }, { "name": "Read a past version of the Terms", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/terms/3", "host": [ "{{baseUrl}}" ], "path": [ "v1", "terms", "3" ] }, "description": "Any past version of the AI-company Terms, so the version a receipt names can always be\nread in the words that governed it.\n\nSigned by the collection's pre-request script with `tag=\"mdb-retrieval\"`." }, "response": [] } ] } ] }, { "name": "Verification API — public, no key", "description": "The public verification surface: unauthenticated,\nCDN-cached, and never rate-limited so as to block a checker. It answers three questions,\neach with a signed statement — is this the real business, is this record what the\nbusiness published, and did the business ever say this — and serves every key,\ncertificate, projection specification, log checkpoint and proof a verifier needs.\nRequiring an account to verify is the mistake this surface does not make.\n\nEvery lookup about a record requires possession of the record — its bytes or its hash,\nnever a bare id — so the public surface cannot be used as an oracle for which ids exist. The same paths are also served on `api.masterdb.ai`.\n\nCORS: every route answers any origin (`Access-Control-Allow-Origin: *`, the\npreflight for `POST /v1/verify` included) and never allows credentials — the surface is\npublic and the same for every caller, so a browser page may read the AI policy key, the key\nset, a certificate or a vocabulary, and post a record or an ad item to `POST /v1/verify`.", "item": [ { "name": "Certificates", "description": "Is this the real business, or the real AI company?", "item": [ { "name": "Read a certificate", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/certificates/6c1658dd-fa53-4f12-8a18-6eee69f5ca99", "host": [ "{{baseUrl}}" ], "path": [ "v1", "certificates", "6c1658dd-fa53-4f12-8a18-6eee69f5ca99" ] }, "description": "Returns the ADL certificate of a business or an AI company — a DSSE envelope signed by\nMasterDB's issuance key — with its status, the date that status took effect, and the\nstatement in plain words (\"Verified by MasterDB on 25 June 2026.\"). The certificate says\nwho the subject is, its legal name and country, that MasterDB verified it and since when,\nand its status — never how it was verified. A certificate revoked for compromise says so with the effective\ndate; a closed business says closed on, and its history stays valid. A certificate\nMasterDB withdrew (`withdrawn`, with its `status_reason`, e.g. `approval_reversed` — a\nreversed verification approval) no longer stands from its effective date; it is\nnot a compromise, and seals made before it stay valid. Every earlier\nissuance comes with it, newest first, each with its `cert_id`: a seal names the issuance\nit was made under and is judged against the one in force at `sealed_at`, and a\nrevocation's effective date may precede its issue. Public by design.\n\n**For a person (not part of the API).** A browser sending `Accept: text/html`, or `?format=html`, receives a\nhuman-readable page instead; this is not part of the API, and the response below is always the JSON. The page is a simple one:\nthe legal name, the country, the verification status and since when (and nothing on how the\nsubject was verified, and no trading name, which MasterDB does not verify), the certificate id,\nthe issuer and its validity, and how to check\nthe certificate (a link to the JSON and to docs.masterdb.ai). The page is one self-contained\ndocument: inline CSS, no script and no external request, served with a content-security-policy\nthat allows nothing else. Every other caller — no `Accept`, `*/*`, `application/json`, or\n`?format=json` — gets the JSON below, byte for byte as it was before the page existed. The\nresponse varies by `Accept`. A browser that asks for the page of an unknown certificate gets\na short HTML page with the same `404`.\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Read a business's public sealing and integration keys", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/certificates/6c1658dd-fa53-4f12-8a18-6eee69f5ca99/keys", "host": [ "{{baseUrl}}" ], "path": [ "v1", "certificates", "6c1658dd-fa53-4f12-8a18-6eee69f5ca99", "keys" ] }, "description": "A business's public keys beside its certificate, so a seal can be verified\noffline from public data alone: every sealing passkey and integration key its register\nhas held, current and past — an old seal is judged against the key as it was at\n`sealed_at` — each with its `key_id` (the RFC 7638 thumbprint of the key), `purpose`\n(`sealing`: a person's passkey; `integration`: a business system's key), `kind`, the\npublic key as a JWK (a passkey also as registered, COSE) and the instants that bound it.\nNothing names a person. `signed` is a DSSE envelope (`business-keys.v1`) by MasterDB's\nstatement key over `{v: 1, uuid, cert_id, issued_at, keys}`; it is the only part a\nverifier trusts (the verifier libraries' `verifyPublishedKeys` / `verify_published_keys`,\nand `publishedKeys` / `published_keys` on the seal check). An AI company's uuid answers\n404, as an unknown one does.\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Read who holds each of a business's keys", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/certificates/6c1658dd-fa53-4f12-8a18-6eee69f5ca99/key-custody", "host": [ "{{baseUrl}}" ], "path": [ "v1", "certificates", "6c1658dd-fa53-4f12-8a18-6eee69f5ca99", "key-custody" ] }, "description": "MasterDB's signed word on who holds the private half of each of a business's keys,\nbeside its certificate: `hosted` — the key MasterDB issued to the verified business and\nholds for it (standard publishing: a seal by it proves MasterDB signed on a confirmed\nrequest of a person with a grant, not that a person of the business signed) — or `self`,\na key the business holds (a person's passkey, an integration key). Each `statement` is a\nDSSE envelope (`key-custody.v1`) signed, like the certificate, by both halves of MasterDB's\nissuance key over `{v: 1, business_uuid, key_id, custody, issued_at, effective_from}`; it\nis the only part a verifier trusts (the verifier libraries' `verifyKeyCustodyStatements` /\n`verify_key_custody_statements`, and `keyCustody` / `key_custody` on the seal check,\nwhich then names the custody of the seal's key at `sealed_at`). Every issuance is listed,\nnewest first, each served byte for byte as issued: a statement is re-issued, never edited,\nwhen a key's custody changes, and the one in force at an instant is the latest\n`effective_from` at or before it. A key with no statement is not listed, and a verifier\nreports it `unstated`. A business with none yet answers an empty list; an AI company's\nuuid answers 404, as an unknown one does. Custody is a statement of its own because\n`certificate.v1` admits no new member; certificate v2 carries it (verifier 1.1).\n\nUnsigned: the public verification API needs no key." }, "response": [] } ] }, { "name": "Verification", "description": "Is this record what the business published, and did it ever say this?", "item": [ { "name": "Verify a record and its seal", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/verify", "host": [ "{{baseUrl}}" ], "path": [ "v1", "verify" ] }, "body": { "mode": "raw", "raw": "{\n \"record_base64\": \"eyJzY2hlbWEiOiJtYXN0ZXJkYi9wcm9kdWN0cy8xIn0=\",\n \"seal\": {\n \"payloadType\": \"application/vnd.masterdb.seal.v2+json\",\n \"payload\": \"eyJ2IjoyfQ==\",\n \"signatures\": [\n {\n \"keyid\": \"0aWsmgFfrC73s0FnNjVRKhUR9B_jfREbJn8DnuxdT1g\",\n \"sig\": \"3q2+7w==\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "Checks a record you hold against its seal: the seal's signature against the business's\nkey register as it stood at `sealed_at`, the hash over the exact bytes (or, for a\npushed record, its inclusion proof in the sealed batch), the certificate in force at\n`sealed_at`, the AI policy version in force at `sealed_at`, and the scope — the\nkey's mandate, or with the record's sidecar the person's grant at acceptance. Send an\nindex row as well and it is checked too: its projection signature, that it came from\nthese bytes, and — with the sidecar — a re-run of the published projection compared byte\nfor byte. Send the business's sealed AI policy record (a fetch's `ai_policy.record`, its\nexact bytes, and `ai_policy.seal`) with the `ai_policy_bits` a search row carried, and the\nbits are checked against the sealed named booleans: the answer's `ai_policy_bits`. The answer is a statement signed by MasterDB's statement key; a check that fails\nis a 200 with `valid: false` and the reason, the same reason codes the open-source\nverifiers use. You must send the record itself; a bare id is never accepted, so nobody\ncan use this to learn which records exist, and nothing here says whether a record is\nserved. The log inclusion is the seal's own leaf in the transparency log — a\n`seal` leaf over the SHA-256 of the canonical seal object, as publish appends it —\nproven against a signed checkpoint; leaves are sequenced hourly, so a fresh seal is\n`not_in_log` for up to an hour. The seal key's own `key_added` leaf is checked too\n(`checks.key_event`): recomputed from the business's register and proven from the log, `ok`\nwith `key_event` saying where it is, or `missing` with a line in `warnings` — the seal stands,\nunless the request says `key_events: require`, which refuses it (`key_event_missing`).\n\nOr send an ad pool item alone, exactly as `POST /v1/ads/pool` served it (`ad_item`): its sealed bytes, the seal inside its signed row and the row are checked as above, the\nanswer's `ad` says whether every text and link the item would show is the sealed one, and\n`ai_policy_bits` checks the advertiser's AI policy the item carries.\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Check a source line (the verify page)", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/verify/mdb_xmomas3i3kzkdwyqpfoxou5rea?origin=sha256:9f2c4e1a7b3d5f6e8a0c2b4d6f8e1a3c5b7d9f0e2a4c6b8d0f1e3a5c7b9d2f4e", "host": [ "{{baseUrl}}" ], "path": [ "v1", "verify", "mdb_xmomas3i3kzkdwyqpfoxou5rea" ], "query": [ { "key": "origin", "value": "sha256:9f2c4e1a7b3d5f6e8a0c2b4d6f8e1a3c5b7d9f0e2a4c6b8d0f1e3a5c7b9d2f4e", "disabled": false, "description": "The record's `adl_origin` — SHA-256 of its exact bytes. Possession of the record, never a bare id." }, { "key": "cert", "value": "", "disabled": true, "description": "The `cert_id` the source line carries (a row's `adl_origin_cert`); checked against the one the record's seal named." }, { "key": "served_at", "value": "", "disabled": true, "description": "When the record was served (the receipt's `served_at`); checked against when this version was the one served." }, { "key": "format", "value": "", "disabled": true, "description": "`html` or `json`; without it, a browser's `Accept: text/html` gets the page and anything else the JSON." } ] }, "description": "Where a source line's verify URL lands (the specification is\n): the one line of provenance an AI cites — `record`, `origin`,\n`cert`, `served`, `verify`. It answers whether the business published a record with\nthis id and these exact bytes, whether that version was the one served at `served_at`,\nwhether the line's certificate is the one the seal named, and the business's\ncertificate today; for a Business & Brand Identity file served now, its\nauthorised-endpoints section as MasterDB stands behind it today and when control of\neach domain was last confirmed. HTML for a person, JSON for a machine;\nthe JSON carries the answer signed by the statement key as its own payload type,\n`application/vnd.masterdb.verify-page.v1+json` (never `verify-statement`, which is\n`POST /v1/verify`'s answer alone). An unknown id and a hash that does not match answer the same\n`404`, so the page is no oracle for which records exist. The full cryptographic check\nis `POST /v1/verify` with the record's bytes and its seal.\n\nUnsigned: the public verification API needs no key." }, "response": [] } ] }, { "name": "Keys", "description": "MasterDB's own keys and signing-key directories.", "item": [ { "name": "Read MasterDB's signed key set", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/.well-known/keys", "host": [ "{{baseUrl}}" ], "path": [ ".well-known", "keys" ] }, "description": "MasterDB's own public keys — root, issuance, projection, every region's receipt key,\nsidecar, statement and the log checkpoint key — past and present, each with its\nvalidity window and any compromise date, as a JWK Set that is itself a signed document,\nso an edited file cannot add a key. The signed payload `{v, issued_at, keys,\ncertificates}` carries every key's certificate: roots certify roots (cross-certified\nsuccession) and issuance keys, issuance keys certify the working keys, so the whole\nchain to the pinned trust anchors travels in one document; long-lived links carry both\nsignature slots, P-256 and ML-DSA-65. A verifier trusts only the signed payload\n— `keys` beside it is a convenience copy — and can check a receipt from any date\nagainst it.\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Read MasterDB's key directory of AI companies", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/.well-known/masterdb-keys", "host": [ "{{baseUrl}}" ], "path": [ ".well-known", "masterdb-keys" ] }, "description": "The live retrieval public keys of the verified AI companies that chose to be listed\n(the AI Portal's `setKeyDirectoryListing`), with each company's name and certificate,\nso a business's site or firewall can recognise their fetches. A company is\nlisted only while its certificate is active; a key until its revocation takes effect\n(a key in its rotation overlap shows when it stops); `source: directory_import` marks\na key imported from the company's own signature directory. The body is signed by the\nstatement key as its own payload type, `application/vnd.masterdb.key-directory.v1+json`.\n\nUnsigned: the public verification API needs no key." }, "response": [] } ] }, { "name": "Specifications", "description": "Projection specifications, envelope specifications and vocabularies.", "item": [ { "name": "Read a projection specification", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/projections/products/1", "host": [ "{{baseUrl}}" ], "path": [ "v1", "projections", "products", "1" ] }, "description": "The published, versioned, hash-pinned specification of how a record of one type becomes\nits index row: the field map, the canonical form and the row rule, the machine-readable\n`definition` whose RFC 8785 hash every row of that version carries as `adl_proj`, and\nthe fields its row signature leaves out. Anyone can re-run it and compare byte for\nbyte with a row they were served. The path is the one the pinned specification\nnames (`platform/projections/v1.json`).\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Read the key to the AI policy bits", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/ai-policy-key", "host": [ "{{baseUrl}}" ], "path": [ "v1", "ai-policy-key" ] }, "description": "The key to `ai_policy_bits`, which every search row carries: for each blocked\ncontext its code (`bc1`–`bc10`), number, name, plain-English meaning, bit of the `blocked`\nmask and the `ai_policy_schema` it appeared in — and, beside them, every bit of the `use`\nand `action` masks by name. A code is never reused or renamed; a retired context keeps its\nnumber. The same key is in the developer documentation and in `@masterdb/shared` and the\nverifier libraries; this read is for a system that decodes bits without them. Public,\nunauthenticated, cacheable for a day.\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Read the envelope specifications and test vectors", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/spec", "host": [ "{{baseUrl}}" ], "path": [ "v1", "spec" ] }, "description": "What a verifier is written from: every envelope payload type MasterDB makes or\naccepts, and every hash-pinned document with its version, URL and hash — each projection\ntype version (the hash every row of it carries as `adl_proj`, served at\n`/v1/projections/{type}/{version}`) and each vocabulary version. The index also lists the envelope formats' prose\nspecifications, test vectors and the corpus of deliberately broken records;\n`test_vectors_url` is absent where they are not published.\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Read a controlled vocabulary", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/vocabularies/countries?version=2", "host": [ "{{baseUrl}}" ], "path": [ "v1", "vocabularies", "countries" ], "query": [ { "key": "version", "value": "2", "disabled": false, "description": "" } ] }, "description": "One of the platform's controlled vocabularies — the product taxonomy, countries,\ncurrencies, time zones, languages — as a versioned document owned by MasterDB, the\none source the publish service validates against and the portals and SDKs read:\n`platform/vocabularies/{name}/v{N}.json` (`time_zones` is the `timezones` file). The latest\nversion unless you ask for another; conditional requests with the ETag (the RFC 8785 hash\nof the version).\n\nUnsigned: the public verification API needs no key." }, "response": [] } ] }, { "name": "Transparency log", "description": "The log's checkpoints and inclusion proofs.", "item": [ { "name": "Read the latest log checkpoint", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/log/checkpoint", "host": [ "{{baseUrl}}" ], "path": [ "v1", "log", "checkpoint" ] }, "description": "The transparency log's latest signed checkpoint in the C2SP signed-note format —\norigin `masterdb.ai/log/v1`, tree size and root hash, signed by the `masterdb-log`\nkey. Compare checkpoints over time and MasterDB cannot edit or truncate the log without\nit showing. A checkpoint is served only once its signature verifies under the\nlog's key (the `log_checkpoint` key of `/.well-known/keys`); before the first one, 404.\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Read an inclusion proof", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/log/proof?leaf=sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae®ion=us-east4&name=202610010930", "host": [ "{{baseUrl}}" ], "path": [ "v1", "log", "proof" ], "query": [ { "key": "leaf", "value": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "disabled": false, "description": "The leaf hash." }, { "key": "region", "value": "us-east4", "disabled": false, "description": "For a receipt, with `name`, its region — known from the receipt itself — so the receipt index is not consulted." }, { "key": "name", "value": "202610010930", "disabled": false, "description": "For a receipt, with `region`, its minute list's name (`YYYYMMDDHHmm` of `served_at`, or that with `-{instance}`)." } ] }, "description": "The inclusion proof of a leaf in the log. For a receipt the proof has two levels: the\nreceipt's path inside its region's one-minute batch, served from the stored leaf list,\nthen that batch root's inclusion in the log. Leaves are typed: seal, receipt\nbatch, certificate, key event, checkpoint.\n\nUnsigned: the public verification API needs no key." }, "response": [] }, { "name": "Read a consistency proof between two tree sizes", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/log/consistency?first=1040000&second=1048576", "host": [ "{{baseUrl}}" ], "path": [ "v1", "log", "consistency" ], "query": [ { "key": "first", "value": "1040000", "disabled": false, "description": "The older tree size, as the first checkpoint you hold states it." }, { "key": "second", "value": "1048576", "disabled": false, "description": "The newer tree size (default the latest)." } ] }, "description": "The RFC 9162 consistency proof that the log of `first` leaves is a prefix of the log of\n`second` leaves (default: the latest checkpoint's size, whose signed note is then included).\nAnyone holding two checkpoints they fetched at different times can check, with the proof and the\npublished `log_checkpoint` key, that MasterDB neither edited nor truncated the log between them. Fetch checkpoints at `GET /v1/log/checkpoint`; the verifier libraries check the proof\n(`verifyLogConsistency` / `verify_log_consistency` take the two notes and `proof`). `404` unless\n1 ≤ `first` ≤ `second` ≤ the latest size; `400` for a size that is not a positive integer.\n\nUnsigned: the public verification API needs no key." }, "response": [] } ] } ] }, { "name": "Business API — a business’s own systems", "description": "The business machine API, for a business's own\nintegration, a Shopify-style connector or an agency's feed — ADL Path A. There is no\nbearer token: every request is signed with RFC 9421 by an integration key the business\ngenerated and registered (`tag=\"mdb-push\"`), and what authorises that key is a\npublishing mandate an admin sealed with their passkey, scoped to record types and\ncountries and valid for at most 92 days.\n\nReads — the catalogue read-back, push attempts and analytics — are signed with the tag\n`mdb-business-read` instead, and need a registered key but no mandate.\n\nSealed, or not published: every record is sealed by the business, a batch with\none Merkle root, and a record whose seal does not verify is refused with a reason that\nnames the seal. A push replaces the record; there is no merge on this path. Nothing\npublishes without a seal, and a bare `DELETE` is refused.", "item": [ { "name": "Publishing", "description": "Sealed batch pushes, withdrawals and deletes.", "item": [ { "name": "Push a sealed batch", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Required on every POST that creates something. 1–255 printable\nASCII characters. The same key with the same request replays the first answer; with a\ndifferent request it is `idempotency_key_reused` (422); while the first is still in\nflight it is `idempotency_in_progress` (409).\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/publish/products", "host": [ "{{baseUrl}}" ], "path": [ "v1", "publish", "products" ] }, "body": { "mode": "raw", "raw": "{\n \"batch_seal\": {\n \"payloadType\": \"application/vnd.masterdb.batch-seal.v2+json\",\n \"payload\": \"eyJ2IjoyLCJzZXEiOjQyfQ==\",\n \"signatures\": [\n {\n \"keyid\": \"0aWsmgFfrC73s0FnNjVRKhUR9B_jfREbJn8DnuxdT1g\",\n \"sig\": \"3q2+7w==\"\n }\n ]\n },\n \"records\": [\n \"eyJzY2hlbWEiOiJtYXN0ZXJkYi9wcm9kdWN0cy8xIiwiYnVzaW5lc3NfcHJvZHVjdF9pZCI6IlRSLTU1MjEifQ==\",\n \"eyJzY2hlbWEiOiJtYXN0ZXJkYi9wcm9kdWN0cy8xIiwiYnVzaW5lc3NfcHJvZHVjdF9pZCI6IlRSLTU1MjIifQ==\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Publishes a batch of records of one type, each exactly the bytes the business sealed,\nunder one batch seal: a Merkle root over the records' raw bytes signed with the\nbusiness's own key, carrying the per-key sequence number `seq` that must be greater\nthan the last accepted one (so a stolen key cannot roll a price back by replaying an\nold seal) and a `sealed_at` within five minutes of receipt. Each record is validated\nwith every reason at once and answered `accepted`, `updated` or `rejected`; a push\nreplaces the record it names. A push that would move more than a fifth of the\ncatalogue's prices is held for the owner (the price-shock hold). Only `products` is published through this route.\n\nEvery record is also held to the scope rule (text naming another company or brand,\nor directing how other sources are treated, is `scope_violation`; a brand the business\nsells belongs in its Business & Brand Identity file's `brands_sold`) and to a malware and phishing check (`url_flagged`), and a `display_domain` must be its `destination_url`'s own host\n(`display_domain_mismatch`) — each a per-record rejection, never the batch's.\n\n**Back-pressure**: the per-key caps stamped on the mandate — records per\nhour and bytes per day — are judged before the body is parsed, and a request over\neither is answered `429 rate_limited` with `Retry-After`. A mandate with a source\nallow-list (CIDR ranges and `AS` numbers) is honoured only from inside it\n(`403 source_not_allowed`).\n\n**Accepted, then processed**. Everything that must refuse a batch is checked\nbefore the answer: the request signature, the key, the mandate and its caps, the\nverified business, the batch seal, its Merkle root over the records, the certificate,\nthe AI policy version, `seq`, and the business's fair use. Then:\n\n- **up to 50 records** are processed inside the request and answered **`200`** with\n every outcome (`PublishOutcome`), as before;\n- **51 to 10,000 records** are stored for processing and answered **`202`** at once with\n the push's status (`PushStatus`) and a `Location` header: poll\n `GET /v1/pushes/{push_id}` until `state` is `complete` (or `held`, or `failed`). The\n records are checked and published in chunks of 200 in the background; a notice tells\n the business's owners and admins when it finishes.\n\nIf background processing cannot be reached, a push of up to 500 records is processed\ninside its request (`200`). A larger one is answered `503` with `Retry-After: 60` and\n`retry_after_seconds`: send the same batch again later; a batch that was already accepted\nis kept and resumes.\nFor more than 10,000 records, upload a bulk file (`POST /v1/bulk-uploads`, then\n`POST /v1/bulk-imports`).\n\n**A push that does not answer, or stops** (a timeout, a dropped connection, a `5xx`, a\n`failed` status): every record of the batch has a row in `GET /v1/push-attempts` and on\nits status — `rejected` with its reasons, or `pending` — and each `pending` row becomes\n`accepted`, `updated` or `held` in the same commit that publishes (or holds) its record.\nSending the **exact batch again** (the same `batch_seal` and records, a new request\nsignature — accepted after the five-minute `sealed_at` window too, since it was accepted\nbefore) resumes it: the records it already settled keep their outcome, the rest are\ncompleted, and nothing is published twice. A push still being processed is only reported.\nAny other batch under the same `seq` is refused (`seq_not_increasing`).\n\nSigned by the collection's pre-request script with `tag=\"mdb-push\"`." }, "response": [] }, { "name": "Withdraw a record, sealed", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Required on every POST that creates something. 1–255 printable\nASCII characters. The same key with the same request replays the first answer; with a\ndifferent request it is `idempotency_key_reused` (422); while the first is still in\nflight it is `idempotency_in_progress` (409).\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/publish/products/withdraw", "host": [ "{{baseUrl}}" ], "path": [ "v1", "publish", "products", "withdraw" ] }, "body": { "mode": "raw", "raw": "{\n \"document_base64\": \"eyJyZWNvcmRfaWQiOiJtZGJfZHE1am5xYXRuZW1ucWo0ZzN4bWd6Z3BvaWsiLCJhY3Rpb24iOiJ3aXRoZHJhdyJ9\",\n \"seal\": {\n \"payloadType\": \"application/vnd.masterdb.seal.v2+json\",\n \"payload\": \"eyJ2IjoyfQ==\",\n \"signatures\": [\n {\n \"keyid\": \"0aWsmgFfrC73s0FnNjVRKhUR9B_jfREbJn8DnuxdT1g\",\n \"sig\": \"3q2+7w==\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "Takes a record out of serving with a tiny sealed document `{record_id, action:\nwithdraw, at}` signed by the business — never an HTTP verb on a bare id. The record of\ntruth is never removed and history stays; the published pointer moves and the fan-out\nremoves the rows and mirror documents from every region within seconds.\n\nSigned by the collection's pre-request script with `tag=\"mdb-push\"`." }, "response": [] }, { "name": "Delete a record, sealed", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Required on every POST that creates something. 1–255 printable\nASCII characters. The same key with the same request replays the first answer; with a\ndifferent request it is `idempotency_key_reused` (422); while the first is still in\nflight it is `idempotency_in_progress` (409).\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/publish/products/delete", "host": [ "{{baseUrl}}" ], "path": [ "v1", "publish", "products", "delete" ] }, "body": { "mode": "raw", "raw": "{\n \"document_base64\": \"eyJyZWNvcmRfaWQiOiJtZGJfZHE1am5xYXRuZW1ucWo0ZzN4bWd6Z3BvaWsiLCJhY3Rpb24iOiJkZWxldGUifQ==\",\n \"seal\": {\n \"payloadType\": \"application/vnd.masterdb.seal.v2+json\",\n \"payload\": \"eyJ2IjoyfQ==\",\n \"signatures\": [\n {\n \"keyid\": \"0aWsmgFfrC73s0FnNjVRKhUR9B_jfREbJn8DnuxdT1g\",\n \"sig\": \"3q2+7w==\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "Deletes a record with a sealed document `{record_id, action: delete, at}`. Deletion\nmeans deletion: the record leaves serving in seconds and its bytes are purged\nfrom the master copy and backups within 30 days; only its fingerprints — the hashes\nand log leaves — stay, which is what lets the public disavowal check still say when a\nrecord with that hash was live.\n\nSigned by the collection's pre-request script with `tag=\"mdb-push\"`." }, "response": [] } ] }, { "name": "Pushes", "description": "A push's status while it is processed, and the bulk-file route for very large loads.", "item": [ { "name": "Read a push's status and its per-record outcomes", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/pushes/bat_7d3a4e8f9b6c1a2b3c4d5e6f?outcome=rejected", "host": [ "{{baseUrl}}" ], "path": [ "v1", "pushes", "bat_7d3a4e8f9b6c1a2b3c4d5e6f" ], "query": [ { "key": "outcome", "value": "rejected", "disabled": false, "description": "" }, { "key": "cursor", "value": "", "disabled": true, "description": "The opaque `next_cursor` of the previous page." } ] }, "description": "A push or bulk import accepted then processed: its totals, its progress and a page\nof its records' outcomes in leaf order (100 a page; `next_cursor` for the next). With\n`outcome`, only the records with that outcome — e.g. `rejected`, to fix and send again.\nPoll every `poll_after_seconds` while it is present. A push that has completed no step for\nten minutes carries `stalled: true` and a `resume` instruction (send the exact batch again —\na bulk import, the same import request again; what it already published is not published\ntwice). Signed with `mdb-business-read`: any live integration key of the business may read it.\n\nSigned by the collection's pre-request script with `tag=\"mdb-business-read\"`." }, "response": [] }, { "name": "Get a signed upload for a bulk file", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Required on every POST that creates something. 1–255 printable\nASCII characters. The same key with the same request replays the first answer; with a\ndifferent request it is `idempotency_key_reused` (422); while the first is still in\nflight it is `idempotency_in_progress` (409).\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/bulk-uploads", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bulk-uploads" ] }, "body": { "mode": "raw", "raw": "{\n \"record_type\": \"products\"\n}", "options": { "raw": { "language": "json" } } }, "description": "The bulk-file route for very large loads, step 1: a signed upload (valid one hour) for one file of up to 100,000 records and 256 MiB. The file\nis newline-delimited: **one record a line, each line the base64 of the record's exact\nbytes** (`application/x-ndjson`); line *i* is leaf *i* of the batch seal's Merkle tree.\nPOST the file to `url` as `multipart/form-data` with every member of `fields`, then the\nfile as `file`. The key needs a live mandate for the record type. Uploaded files are\ndeleted after 7 days, or as soon as their import completes.\n\nAnswered `503` with `Retry-After` (60 seconds) and `reason: staging_unavailable` where the\nupload area cannot be written, and `503` with a longer `Retry-After` where bulk import is\nnot available.\n\nSigned by the collection's pre-request script with `tag=\"mdb-push\"`." }, "response": [] }, { "name": "Import an uploaded bulk file under its batch seal", "request": { "method": "POST", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Required on every POST that creates something. 1–255 printable\nASCII characters. The same key with the same request replays the first answer; with a\ndifferent request it is `idempotency_key_reused` (422); while the first is still in\nflight it is `idempotency_in_progress` (409).\n" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/bulk-imports", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bulk-imports" ] }, "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"bup_5f1c0e9a8b7d6c5b4a3f2e1d\",\n \"batch_seal\": {\n \"payloadType\": \"application/vnd.masterdb.batch-seal.v2+json\",\n \"payload\": \"eyJ2IjoyLCJzZXEiOjQzfQ==\",\n \"signatures\": [\n {\n \"keyid\": \"0aWsmgFfrC73s0FnNjVRKhUR9B_jfREbJn8DnuxdT1g\",\n \"sig\": \"3q2+7w==\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "The bulk-file route, step 2: the uploaded file's `upload_id` and the batch seal over its\nrecords — the same seal as a push's (`tree_size` the number of lines, `root` the Merkle\nroot over the records' raw bytes, a `seq` above the key's last). The seal, the key, the\nmandate and its caps (over the file's bytes and records), the certificate, the AI policy\nversion and fair use are checked here; the file is then read once in the background, and\nif its records are not exactly the ones the seal names the import is `failed` with\n`seal_invalid` before any record is checked. Otherwise it is processed as a queued push:\npoll `GET /v1/pushes/{push_id}`. The same request again answers the import's status, and\nresumes one that stopped. Answered `503` with `Retry-After` where bulk import is not available\n(the upload area cannot be written, `reason: staging_unavailable`), and where background\nprocessing cannot be reached (the import is kept: send the same request again).\n\nSigned by the collection's pre-request script with `tag=\"mdb-push\"`." }, "response": [] } ] }, { "name": "Catalogue", "description": "Read back what you published — a manifest, not an export.", "item": [ { "name": "Read back your catalogue manifest", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/catalogue?type=products", "host": [ "{{baseUrl}}" ], "path": [ "v1", "catalogue" ], "query": [ { "key": "cursor", "value": "", "disabled": true, "description": "The opaque `next_cursor` of the previous page." }, { "key": "type", "value": "products", "disabled": false, "description": "" } ] }, "description": "The manifest of what your business has published — ids, your own `business_product_id`,\n`last_updated` and `source` (manual, import or api) — in cursor pages, rate-limited above\n1,000 records. It is how a connector reconciles its own state with MasterDB's; it is\nnot an export, and the only full-record path is the account export in the Business\nPortal.\n\nSigned by the collection's pre-request script with `tag=\"mdb-business-read\"`." }, "response": [] }, { "name": "Read back one of your records", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/catalogue/mdb_xmomas3i3kzkdwyqpfoxou5rea", "host": [ "{{baseUrl}}" ], "path": [ "v1", "catalogue", "mdb_xmomas3i3kzkdwyqpfoxou5rea" ] }, "description": "One of your own records as stored, by MasterDB's record id or by your own\n`business_product_id` — the bytes you sealed, the seal, the sidecar and where it is\nlive. Only your own business's records are ever returned here.\n\nSigned by the collection's pre-request script with `tag=\"mdb-business-read\"`." }, "response": [] } ] }, { "name": "Push attempts", "description": "The ingestion audit.", "item": [ { "name": "Read the ingestion audit", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/push-attempts?from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z&status=rejected", "host": [ "{{baseUrl}}" ], "path": [ "v1", "push-attempts" ], "query": [ { "key": "from", "value": "2026-10-01T00:00:00Z", "disabled": false, "description": "Start of the window, inclusive (RFC 3339 UTC or a date)." }, { "key": "to", "value": "2026-10-02T00:00:00Z", "disabled": false, "description": "End of the window, exclusive (RFC 3339 UTC or a date)." }, { "key": "status", "value": "rejected", "disabled": false, "description": "" }, { "key": "cursor", "value": "", "disabled": true, "description": "The opaque `next_cursor` of the previous page." } ] }, "description": "Every row a push tried to publish in a window, with its outcome and reason — a seal\nfailure is its own category, distinct from a validation failure — so a rejected push\nis visible within seconds.\n\nSigned by the collection's pre-request script with `tag=\"mdb-business-read\"`." }, "response": [] } ] }, { "name": "Seal context", "description": "What a seal must name — the certificate and the AI policy version in force.", "item": [ { "name": "Read the certificate and the AI policy version a seal must name", "request": { "method": "GET", "header": [ { "key": "MDB-Sandbox-Key", "value": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl", "description": "Sandbox only. The `sandbox_key_grant` the portal answered when the\nkey was taken there: MasterDB's signed statement of the key and its party,\nwhich holds no secret. The sandbox does not know a key taken in the portal\nuntil a request carries its grant: the first signed request with it\ncreates the matching party in the sandbox and registers the key there, and is then\nverified like any other. Send it on every sandbox request: without it the first request\nwith a new key is refused `401` `key_unknown`. A key production has revoked stays refused\nwith its grant. Production ignores the header.\n" } ], "url": { "raw": "{{baseUrl}}/v1/seal-context", "host": [ "{{baseUrl}}" ], "path": [ "v1", "seal-context" ] }, "description": "What the next seal must name: `cert_id`, the business's certificate\nin force (a seal naming any other is refused), and `ai_policy_version`, the business's\nown AI policy version in force — the live generation of its AI policy record, 0 before\none is sealed. A seal binds the version in force at `sealed_at` (seal format 2's\n`ai_policy_version`; format 1 named `terms_version`); an AI policy record's own\nseal names the version it creates, `next_ai_policy_version`. Before this read a pushing\nsystem learned the version only from a refusal (`seal_invalid` with an\n`ai_policy_version` extension). Any live integration key of the business may read it.\n\nSigned by the collection's pre-request script with `tag=\"mdb-business-read\"`." }, "response": [] } ] }, { "name": "Analytics", "description": "Your own figures.", "item": [ { "name": "Read your daily figures", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/analytics/daily?from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z", "host": [ "{{baseUrl}}" ], "path": [ "v1", "analytics", "daily" ], "query": [ { "key": "from", "value": "2026-10-01T00:00:00Z", "disabled": false, "description": "Start of the window, inclusive (RFC 3339 UTC or a date)." }, { "key": "to", "value": "2026-10-02T00:00:00Z", "disabled": false, "description": "End of the window, exclusive (RFC 3339 UTC or a date)." } ] }, "description": "Your business's own figures per day, per country and per AI group (one name per group)\n— searches that returned your records, fetches, ad renders, clicks and spend — as at\nthe end of the last complete hour. Never an impression figure MasterDB cannot know,\nnever share of showings.\n\nSigned by the collection's pre-request script with `tag=\"mdb-business-read\"`." }, "response": [] }, { "name": "See which AI groups retrieved your records", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/analytics/who-is-asking?country=US", "host": [ "{{baseUrl}}" ], "path": [ "v1", "analytics", "who-is-asking" ], "query": [ { "key": "country", "value": "US", "disabled": false, "description": "" } ] }, "description": "The AI groups that retrieved your business's records over the last 30 days, by name,\nwith counts, country as the axis. It is what the business-side block decision\nis made from.\n\nSigned by the collection's pre-request script with `tag=\"mdb-business-read\"`." }, "response": [] } ] } ] } ] }