{ "openapi": "3.1.0", "info": { "title": "MasterDB Public Verification API", "version": "1.0.0", "summary": "Everything a verifier needs, without an account.", "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`.\n", "contact": { "name": "MasterDB developer documentation", "url": "https://docs.masterdb.ai" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-MasterDB" } }, "servers": [ { "url": "https://verify.masterdb.ai", "description": "Production, CDN-fronted." }, { "url": "https://api.masterdb.ai", "description": "The same paths on the retrieval host." }, { "url": "https://sandbox.api.masterdb.ai", "description": "Sandbox — sandbox roots, which a verifier accepts only by explicit opt-in." } ], "security": [], "tags": [ { "name": "Certificates", "description": "Is this the real business, or the real AI company?" }, { "name": "Verification", "description": "Is this record what the business published, and did it ever say this?" }, { "name": "Keys", "description": "MasterDB's own keys and signing-key directories." }, { "name": "Specifications", "description": "Projection specifications, envelope specifications and vocabularies." }, { "name": "Transparency log", "description": "The log's checkpoints and inclusion proofs." } ], "paths": { "/v1/certificates/{uuid}": { "get": { "operationId": "getCertificate", "tags": [ "Certificates" ], "summary": "Read a certificate", "x-mcp-tool": "certificate", "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", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "A `business_uuid` or an `ai_company_uuid`.", "schema": { "$ref": "#/components/schemas/Uuid" }, "example": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e" } ], "responses": { "200": { "description": "The certificate in force and its plain-words statement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateResponse" }, "example": { "subject": "business", "status": "active", "status_effective_from": "2026-06-25T10:00:00.000Z", "statement": "Verified by MasterDB on 25 June 2026.", "cert_id": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "issued_at": "2026-06-25T10:00:00.000Z", "certificate": { "payloadType": "application/vnd.masterdb.certificate.v1+json", "payload": "eyJ2IjoxLCJidXNpbmVzc191dWlkIjoiMGI3ZCJ9", "signatures": [ { "keyid": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA", "sig": "MEUCIQDx" } ] }, "history": [ { "cert_id": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "status": "active", "status_effective_from": "2026-06-25T10:00:00.000Z", "issued_at": "2026-06-25T10:00:00.000Z", "certificate": { "payloadType": "application/vnd.masterdb.certificate.v1+json", "payload": "eyJ2IjoxLCJidXNpbmVzc191dWlkIjoiMGI3ZCJ9", "signatures": [ { "keyid": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA", "sig": "MEUCIQDx" } ] } } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/certificates/{uuid}/keys": { "get": { "operationId": "getCertificateKeys", "tags": [ "Certificates" ], "summary": "Read a business's public sealing and integration 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", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "A `business_uuid`.", "schema": { "$ref": "#/components/schemas/Uuid" }, "example": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e" } ], "responses": { "200": { "description": "The business's public keys, signed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessKeysResponse" }, "example": { "uuid": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e", "cert_id": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "issued_at": "2026-10-01T12:00:00.000Z", "keys": [ { "key_id": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA", "purpose": "sealing", "kind": "passkey", "jwk": { "kty": "EC", "crv": "P-256", "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU", "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0" }, "cose": "pQECAyYgASFYIH_NzidwJ3...", "valid_from": "2026-08-01T00:00:00.000Z", "valid_until": null, "revocation_effective_from": null }, { "key_id": "7Hs2pQ9vLm4xZk1Nt8Rc5Yw3Bf6Ju0Ea2Di7Go9Ks1M", "purpose": "integration", "kind": "ed25519", "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" }, "valid_from": "2026-08-15T00:00:00.000Z", "valid_until": null, "revocation_effective_from": null } ], "signed": { "payloadType": "application/vnd.masterdb.business-keys.v1+json", "payload": "eyJ2IjoxLCJ1dWlkIjoiMGI3ZCJ9", "signatures": [ { "keyid": "QmStatementKeyThumbprint0000000000000000000", "sig": "c2lnbmF0dXJl" } ] } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/certificates/{uuid}/key-custody": { "get": { "operationId": "getKeyCustody", "tags": [ "Certificates" ], "summary": "Read who holds each of a business's keys", "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", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "A `business_uuid`.", "schema": { "$ref": "#/components/schemas/Uuid" }, "example": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e" } ], "responses": { "200": { "description": "Every key custody statement of the business, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyCustodyResponse" }, "example": { "uuid": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e", "statements": [ { "key_id": "7Hs2pQ9vLm4xZk1Nt8Rc5Yw3Bf6Ju0Ea2Di7Go9Ks1M", "custody": "hosted", "effective_from": "2026-10-03T09:00:00.000Z", "issued_at": "2026-10-03T09:00:00.000Z", "statement_id": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "statement": { "payloadType": "application/vnd.masterdb.key-custody.v1+json", "payload": "eyJ2IjoxLCJidXNpbmVzc191dWlkIjoiMGI3ZCJ9", "signatures": [ { "keyid": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA", "sig": "MEUCIQDx" }, { "keyid": "QmIssuanceMlDsaHalfThumbprint00000000000000", "sig": "c2lnbmF0dXJl" } ] } }, { "key_id": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdB", "custody": "self", "effective_from": "2026-08-01T00:00:00.000Z", "issued_at": "2026-09-20T10:00:00.000Z", "statement_id": "sha256:fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9", "statement": { "payloadType": "application/vnd.masterdb.key-custody.v1+json", "payload": "eyJ2IjoxLCJidXNpbmVzc191dWlkIjoiMGI3ZCJ9", "signatures": [ { "keyid": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA", "sig": "MEUCIQDy" }, { "keyid": "QmIssuanceMlDsaHalfThumbprint00000000000000", "sig": "c2lnbmF0dXJm" } ] } } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/verify": { "post": { "operationId": "verifyRecord", "tags": [ "Verification" ], "summary": "Verify a record and its seal", "x-mcp-tool": "verify", "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", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" }, "example": { "record_base64": "eyJzY2hlbWEiOiJtYXN0ZXJkYi9wcm9kdWN0cy8xIn0=", "seal": { "payloadType": "application/vnd.masterdb.seal.v2+json", "payload": "eyJ2IjoyfQ==", "signatures": [ { "keyid": "0aWsmgFfrC73s0FnNjVRKhUR9B_jfREbJn8DnuxdT1g", "sig": "3q2+7w==" } ] } } } } }, "responses": { "200": { "description": "The three checks and a signed statement of the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" }, "example": { "seal": { "valid": true, "path": "B", "key_id": "0aWsmgFfrC73s0FnNjVRKhUR9B_jfREbJn8DnuxdT1g", "cert_id": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "business_uuid": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e", "sealed_at": "2026-09-30T08:14:59.120Z", "record_type": "products", "ai_policy_version": 1, "format": 2, "checks": { "signature": "ok", "hash": "ok", "inclusion": "not_applicable", "schema": "ok", "key_validity": "ok", "certificate": "ok", "ai_policy": "ok", "scope": "not_checked" } }, "log_inclusion": { "included": false, "reason": "log_not_available" }, "statement": { "payloadType": "application/vnd.masterdb.verify-statement.v1+json", "payload": "eyJ2YWxpZCI6dHJ1ZX0=", "signatures": [ { "keyid": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA", "sig": "3q2+7w==" } ] } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/.well-known/keys": { "get": { "operationId": "getKeys", "tags": [ "Keys" ], "summary": "Read MasterDB's signed key set", "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", "responses": { "200": { "description": "The key set and its signed envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedKeySet" }, "example": { "keys": [ { "kty": "OKP", "crv": "Ed25519", "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo", "kid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4", "purpose": "receipt", "region": "us-east4", "valid_from": "2026-10-01T00:00:00.000Z", "valid_until": "2026-11-07T00:00:00.000Z" } ], "signed": { "payloadType": "application/vnd.masterdb.jwks.v1+json", "payload": "eyJrZXlzIjpbXX0=", "signatures": [ { "keyid": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA", "sig": "3q2+7w==" } ] } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/projections/{type}/{version}": { "get": { "operationId": "getProjection", "tags": [ "Specifications" ], "summary": "Read a projection specification", "x-mcp-tool": "projection", "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", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z_]{1,32}$" }, "example": "products" }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,5}$" }, "example": "1" } ], "responses": { "200": { "description": "The specification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectionSpec" }, "example": { "version": "products/1", "spec_version": 1, "sha256": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "record_type": "products", "field_map": { "product_name": "string(/product_name)", "price_{CC}": "number(/prices/*/amount) per /country" }, "rules": { "row": "One row per record." }, "unsigned_fields": [ "adl_row_sig", "sponsored", "sponsorship_id", "excluded_groups" ], "serve_time_fields": [ "freshness_expectation", "ai_policy_bits", "terms" ], "definition": { "spec_version": 1, "type": "products", "version": 1 } } } } }, "304": { "description": "Not modified." }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/ai-policy-key": { "get": { "operationId": "getAiPolicyKey", "tags": [ "Specifications" ], "summary": "Read the key to the AI policy bits", "x-mcp-tool": "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", "responses": { "200": { "description": "The key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiPolicyKey" }, "example": { "key_version": 1, "current_ai_policy_schema": 2, "rule": "A bit is set exactly when the sealed boolean of that name is true. …", "groups": { "use": [ { "name": "cite_as_source", "meaning": "Name the business (and MasterDB) as the source.", "bit": 0, "since_schema": 1 } ], "action": [ { "name": "answer", "meaning": "May use this data to answer.", "bit": 0, "since_schema": 1 } ] }, "blocked": [ { "number": 1, "code": "bc1", "name": "adult_sexual", "meaning": "Adult and sexual content: the business does not want its published data used to build a response in this context. A suppression list, not a rating of the business.", "bit": 0, "since_schema": 2 }, { "number": 2, "code": "bc2", "name": "alcohol", "meaning": "Alcohol: the business does not want its published data used to build a response in this context. A suppression list, not a rating of the business.", "bit": 1, "since_schema": 2 } ] } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/spec": { "get": { "operationId": "getSpec", "tags": [ "Specifications" ], "summary": "Read the envelope specifications and test vectors", "x-mcp-tool": "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", "responses": { "200": { "description": "The index of specifications.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecIndex" }, "example": { "payload_types": [ "application/vnd.masterdb.seal.v1+json", "application/vnd.masterdb.receipt.v1+json" ], "specifications": [ { "name": "projection/products", "version": 3, "url": "https://verify.masterdb.ai/v1/projections/products/3", "sha256": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, { "name": "vocabulary/countries", "version": 1, "url": "https://verify.masterdb.ai/v1/vocabularies/countries?version=1", "sha256": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" } ] } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/log/checkpoint": { "get": { "operationId": "getLogCheckpoint", "tags": [ "Transparency log" ], "summary": "Read the latest 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", "responses": { "200": { "description": "The checkpoint, as a signed note.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "masterdb.ai/log/v1\n1048576\nLCa0a2j/xo/5m0U8HTBBNBNCLXBkg7+g+YpeiGJm564=\n\n— masterdb-log Az3grlgtzPICa5OS8npVmf1Myq/5IZniMp+ZJurmRDeOoRDe4URYN7u5/Zhcyv2q1gGzGku9nTo+zyWE+xeMcTOAYQ8=\n" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/log/proof": { "get": { "operationId": "getLogProof", "tags": [ "Transparency log" ], "summary": "Read an inclusion proof", "x-mcp-tool": "log_proof", "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", "parameters": [ { "name": "leaf", "in": "query", "required": true, "description": "The leaf hash.", "schema": { "$ref": "#/components/schemas/Sha256" }, "example": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" }, { "name": "region", "in": "query", "required": false, "description": "For a receipt, with `name`, its region — known from the receipt itself — so the receipt index is not consulted.", "schema": { "type": "string", "pattern": "^[a-z]+-[a-z]+[0-9]+$" }, "example": "us-east4" }, { "name": "name", "in": "query", "required": false, "description": "For a receipt, with `region`, its minute list's name (`YYYYMMDDHHmm` of `served_at`, or that with `-{instance}`).", "schema": { "type": "string", "pattern": "^[0-9]{12}(?:-[A-Za-z0-9_-]{1,64})?$" }, "example": "202610010930" } ], "responses": { "200": { "description": "The proof.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InclusionProof" }, "example": { "leaf": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "leaf_type": "seal", "leaf_index": 734112, "tree_size": 1048576, "proof": [ "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" ], "checkpoint": "masterdb.ai/log/v1\n1048576\nLCa0a2j/xo/5m0U8HTBBNBNCLXBkg7+g+YpeiGJm564=\n" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/log/consistency": { "get": { "operationId": "getLogConsistency", "tags": [ "Transparency log" ], "summary": "Read a consistency proof between two tree sizes", "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", "parameters": [ { "name": "first", "in": "query", "required": true, "description": "The older tree size, as the first checkpoint you hold states it.", "schema": { "type": "integer", "minimum": 1 }, "example": 1040000 }, { "name": "second", "in": "query", "required": false, "description": "The newer tree size (default the latest).", "schema": { "type": "integer", "minimum": 1 }, "example": 1048576 } ], "responses": { "200": { "description": "The proof.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogConsistencyProof" }, "example": { "from_size": 1040000, "to_size": 1048576, "proof": [ "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" ], "checkpoint": "masterdb.ai/log/v1\n1048576\nLCa0a2j/xo/5m0U8HTBBNBNCLXBkg7+g+YpeiGJm564=\n" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/vocabularies/{name}": { "get": { "operationId": "getVocabulary", "tags": [ "Specifications" ], "summary": "Read a controlled vocabulary", "x-mcp-tool": "vocabularies", "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", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "taxonomy", "countries", "subdivisions", "currencies", "time_zones", "languages" ] }, "example": "countries" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "example": 2 } ], "responses": { "200": { "description": "The vocabulary.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vocabulary" }, "example": { "name": "countries", "version": 1, "published_at": "2026-09-29", "entries": [ { "id": "IE", "name": "Ireland" }, { "id": "US", "name": "United States" } ] } } } }, "304": { "description": "Not modified." }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/verify/{record_id}": { "parameters": [ { "name": "record_id", "in": "path", "required": true, "description": "The record id a source line cites.", "schema": { "$ref": "#/components/schemas/RecordId" }, "example": "bf_sqtfovjvveefzuq25eegf2" }, { "name": "origin", "in": "query", "required": true, "description": "The record's `adl_origin` — SHA-256 of its exact bytes. Possession of the record, never a bare id.", "schema": { "$ref": "#/components/schemas/Sha256" }, "example": "sha256:9f2c4e1a7b3d5f6e8a0c2b4d6f8e1a3c5b7d9f0e2a4c6b8d0f1e3a5c7b9d2f4e" }, { "name": "cert", "in": "query", "required": false, "description": "The `cert_id` the source line carries (a row's `adl_origin_cert`); checked against the one the record's seal named.", "schema": { "$ref": "#/components/schemas/Sha256" } }, { "name": "served_at", "in": "query", "required": false, "description": "When the record was served (the receipt's `served_at`); checked against when this version was the one served.", "schema": { "type": "string", "format": "date-time" } }, { "name": "format", "in": "query", "required": false, "description": "`html` or `json`; without it, a browser's `Accept: text/html` gets the page and anything else the JSON.", "schema": { "type": "string", "enum": [ "html", "json" ] } } ], "get": { "operationId": "verifySourceLine", "tags": [ "Verification" ], "summary": "Check a source line (the verify page)", "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", "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceLineAnswer" }, "example": { "v": 1, "record_id": "bf_sqtfovjvveefzuq25eegf2", "adl_origin": "sha256:9f2c4e1a7b3d5f6e8a0c2b4d6f8e1a3c5b7d9f0e2a4c6b8d0f1e3a5c7b9d2f4e", "record_type": "business_files", "valid": true, "status": "current", "business": { "business_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "Acme Fashion Ltd", "certificate_url": "https://verify.masterdb.ai/v1/certificates/7c9e6679-7425-40de-944b-e07fc1f90ae7", "certificate": { "cert_id": "sha256:3b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c", "status": "active", "status_effective_from": "2026-09-01T00:00:00.000Z", "statement": "Verified by MasterDB on 1 September 2026." } }, "version": { "generation": 3, "sealed_at": "2026-10-01T08:59:12.000Z", "published_at": "2026-10-01T09:00:00.000Z", "ended_at": null, "sealed_under_cert_id": "sha256:3b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c" }, "checks": { "cert": "matches", "served_at": "within" }, "endpoints": { "status": "live", "domains": [ { "domain": "acme.example", "state": "confirmed", "last_confirmed_at": "2026-10-02T06:00:00.000Z", "expires_on": "2027-02-20T10:00:00.000Z" } ] }, "source_line": "mdb-source/1 record=bf_sqtfovjvveefzuq25eegf2 origin=sha256:9f2c4e1a7b3d5f6e8a0c2b4d6f8e1a3c5b7d9f0e2a4c6b8d0f1e3a5c7b9d2f4e cert=sha256:3b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c served=2026-10-02T10:15:00.000Z verify=https://verify.masterdb.ai/v1/verify/bf_sqtfovjvveefzuq25eegf2?origin=sha256%3A9f2c4e1a7b3d5f6e8a0c2b4d6f8e1a3c5b7d9f0e2a4c6b8d0f1e3a5c7b9d2f4e&cert=sha256%3A3b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c&served_at=2026-10-02T10%3A15%3A00.000Z", "full_check": "POST /v1/verify with the record’s exact bytes and its seal checks the seal against the business’s register, its leaf in the transparency log and, with a served row, the projection.", "checked_at": "2026-10-02T10:15:03.000Z", "statement": { "payloadType": "application/vnd.masterdb.verify-page.v1+json", "payload": "eyJ2IjoxfQ", "signatures": [ { "keyid": "4kX1qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHU", "sig": "MEUCIQDx3q2" } ] } } }, "text/html": { "schema": { "type": "string" }, "example": "…" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/.well-known/masterdb-keys": { "get": { "operationId": "getMasterdbKeyDirectory", "tags": [ "Keys" ], "summary": "Read MasterDB's key directory of AI companies", "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", "responses": { "200": { "description": "The directory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterdbKeyDirectory" }, "example": { "v": 1, "issued_at": "2026-10-02T10:15:00.000Z", "companies": [ { "ai_company_uuid": "1c8e7d4f-3a5b-4d2c-8e9f-8a7b6c5d4e3f", "name": "Lumen AI Inc", "certificate_url": "https://verify.masterdb.ai/v1/certificates/1c8e7d4f-3a5b-4d2c-8e9f-8a7b6c5d4e3f", "keys": [ { "key_id": "L1BSyf0VsZoYxYTQE2NWgZhhPww06EQJ73k4cJoVnsI", "alg": "Ed25519", "public_key": { "kty": "OKP", "crv": "Ed25519", "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" }, "source": "directory_import", "valid_from": "2026-10-01T14:02:11.482Z", "valid_until": null } ] } ], "statement": { "payloadType": "application/vnd.masterdb.key-directory.v1+json", "payload": "eyJ2IjoxfQ", "signatures": [ { "keyid": "4kX1qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHU", "sig": "MEUCIQDx3q2" } ] } } } } }, "default": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "schemas": { "BusinessKeysResponse": { "type": "object", "required": [ "uuid", "cert_id", "issued_at", "keys", "signed" ], "properties": { "uuid": { "$ref": "#/components/schemas/Uuid" }, "cert_id": { "$ref": "#/components/schemas/Sha256", "description": "The certificate in force when the list was issued." }, "issued_at": { "$ref": "#/components/schemas/Timestamp" }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/PublishedBusinessKey" } }, "signed": { "$ref": "#/components/schemas/Envelope", "description": "`business-keys.v1` by the statement key over `{v: 1, uuid, cert_id, issued_at, keys}` (RFC 8785): the only part a verifier trusts." } } }, "KeyCustodyResponse": { "type": "object", "required": [ "uuid", "statements" ], "properties": { "uuid": { "$ref": "#/components/schemas/Uuid" }, "statements": { "type": "array", "description": "Every issuance of every key's statement, newest first. A key with no statement is not listed.", "items": { "type": "object", "required": [ "key_id", "custody", "effective_from", "issued_at", "statement_id", "statement" ], "properties": { "key_id": { "$ref": "#/components/schemas/KeyId" }, "custody": { "type": "string", "enum": [ "hosted", "self" ], "description": "`hosted`: MasterDB holds the key for the business. `self`: the business holds it." }, "effective_from": { "$ref": "#/components/schemas/Timestamp" }, "issued_at": { "$ref": "#/components/schemas/Timestamp" }, "statement_id": { "$ref": "#/components/schemas/Sha256", "description": "The `sha256:` of the statement's payload bytes." }, "statement": { "$ref": "#/components/schemas/KeyCustodyEnvelope", "description": "`key-custody.v1` by both halves of the issuance key: the only part a verifier trusts." } } } } } }, "PublishedBusinessKey": { "type": "object", "required": [ "key_id", "purpose", "kind", "jwk", "valid_from", "valid_until", "revocation_effective_from" ], "properties": { "key_id": { "$ref": "#/components/schemas/KeyId", "description": "The RFC 7638 thumbprint of the key." }, "purpose": { "type": "string", "enum": [ "sealing", "integration" ] }, "kind": { "type": "string", "enum": [ "passkey", "ed25519", "es256" ], "description": "`passkey`: a person's WebAuthn credential, ES256 (an `EC` P-256 JWK) or RS256 (an\n`RSA` JWK, 2048 bits or more, e = 65537 — what Windows Hello makes); its signatures\nare WebAuthn assertions. `ed25519` / `es256`: an integration key.\n" }, "jwk": { "type": "object", "description": "The public key as a JWK — `OKP`, `EC`, or (a passkey only) `RSA`." }, "cose": { "type": "string", "description": "A passkey's public key as registered (COSE, base64url) — EC2 ES256 or RSA RS256." }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "revocation_effective_from": { "type": [ "string", "null" ], "format": "date-time", "description": "Seals made at or after this instant are invalid; nothing sealed before it is." } } }, "SourceLineAnswer": { "type": "object", "required": [ "v", "record_id", "adl_origin", "record_type", "valid", "status", "business", "version", "checks", "full_check", "checked_at", "statement" ], "properties": { "v": { "const": 1 }, "record_id": { "$ref": "#/components/schemas/RecordId" }, "adl_origin": { "$ref": "#/components/schemas/Sha256" }, "record_type": { "type": "string" }, "valid": { "type": "boolean", "description": "The business published a record with these bytes, and nothing the line says contradicts that." }, "status": { "type": "string", "enum": [ "current", "pulled", "superseded", "withdrawn", "deleted" ], "description": "`current`: the version served now; otherwise why it stopped being served." }, "business": { "type": "object", "required": [ "business_uuid", "name", "certificate_url", "certificate" ], "properties": { "business_uuid": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "certificate_url": { "type": "string", "format": "uri" }, "certificate": { "type": [ "object", "null" ], "description": "The certificate in force today, as `GET /v1/certificates/{uuid}` gives it — never how the business was verified.", "required": [ "cert_id", "status", "status_effective_from", "statement" ], "properties": { "cert_id": { "$ref": "#/components/schemas/Sha256" }, "status": { "type": "string", "enum": [ "active", "closed", "suspended", "revoked", "withdrawn" ] }, "status_effective_from": { "type": "string", "format": "date-time" }, "statement": { "type": "string" } } } } }, "version": { "type": "object", "required": [ "generation", "sealed_at", "published_at", "ended_at", "sealed_under_cert_id" ], "properties": { "generation": { "type": "integer", "minimum": 1 }, "sealed_at": { "type": "string", "format": "date-time" }, "published_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "sealed_under_cert_id": { "type": [ "string", "null" ] } } }, "checks": { "type": "object", "required": [ "cert", "served_at" ], "properties": { "cert": { "type": "string", "enum": [ "matches", "differs", "not_given" ] }, "served_at": { "type": "string", "enum": [ "within", "outside", "not_given" ] } } }, "endpoints": { "type": "object", "description": "A Business & Brand Identity file served now — its authorised-endpoints section today.", "required": [ "status", "domains" ], "properties": { "status": { "type": "string", "enum": [ "live", "suspended" ] }, "suspended_at": { "type": "string", "format": "date-time" }, "suspend_reason": { "type": "string" }, "domains": { "type": "array", "items": { "type": "object", "required": [ "domain", "state", "last_confirmed_at", "expires_on" ], "properties": { "domain": { "type": "string" }, "state": { "type": "string", "enum": [ "confirmed", "lapsed" ] }, "last_confirmed_at": { "type": "string", "format": "date-time" }, "expires_on": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "source_line": { "type": "string", "description": "The line as MasterDB writes it for these facts (when `served_at` was given)." }, "full_check": { "type": "string" }, "checked_at": { "type": "string", "format": "date-time" }, "statement": { "$ref": "#/components/schemas/Envelope", "description": "`verify-page.v1` by the statement key over every other member (RFC 8785): the only part a verifier trusts." } } }, "MasterdbKeyDirectory": { "type": "object", "required": [ "v", "issued_at", "companies", "statement" ], "properties": { "v": { "const": 1 }, "issued_at": { "type": "string", "format": "date-time" }, "companies": { "type": "array", "items": { "type": "object", "required": [ "ai_company_uuid", "name", "certificate_url", "keys" ], "properties": { "ai_company_uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "certificate_url": { "type": "string", "format": "uri" }, "keys": { "type": "array", "items": { "type": "object", "required": [ "key_id", "alg", "public_key", "source", "valid_from", "valid_until" ], "properties": { "key_id": { "type": "string" }, "alg": { "type": "string", "enum": [ "Ed25519", "ES256" ] }, "public_key": { "type": "object" }, "source": { "type": "string", "enum": [ "portal", "directory_import" ] }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" } } } } } } }, "statement": { "$ref": "#/components/schemas/Envelope", "description": "`key-directory.v1` by the statement key over `{v: 1, issued_at, companies}` (RFC 8785): the only part a verifier trusts." } } }, "CertificateResponse": { "type": "object", "required": [ "subject", "status", "status_effective_from", "statement", "certificate" ], "properties": { "subject": { "type": "string", "enum": [ "business", "ai_company" ] }, "status": { "type": "string", "enum": [ "active", "closed", "suspended", "revoked", "withdrawn" ], "description": "`revoked`: key compromise, seals from `status_effective_from` are invalid. `withdrawn`: MasterDB withdrew its attestation from `status_effective_from`; seals before it stand." }, "status_reason": { "type": "string", "enum": [ "approval_reversed" ], "description": "Why MasterDB withdrew the certificate; present only when `status` is `withdrawn`." }, "status_effective_from": { "$ref": "#/components/schemas/Timestamp" }, "statement": { "type": "string", "description": "The statement in plain words — the status and the date it took effect (\"Verified by MasterDB on 25 June 2026.\"), never how the subject was verified." }, "cert_id": { "$ref": "#/components/schemas/Sha256", "description": "The `sha256:` of the certificate's payload bytes — what a seal names." }, "issued_at": { "$ref": "#/components/schemas/Timestamp" }, "certificate": { "$ref": "#/components/schemas/CertificateEnvelope" }, "history": { "type": "array", "description": "Every issuance, newest first (the one in force included), each served byte for byte as issued.", "items": { "type": "object", "required": [ "cert_id", "status", "status_effective_from", "issued_at", "certificate" ], "properties": { "cert_id": { "$ref": "#/components/schemas/Sha256" }, "status": { "type": "string", "enum": [ "active", "closed", "suspended", "revoked", "withdrawn" ] }, "status_reason": { "type": "string", "enum": [ "approval_reversed" ], "description": "On a `withdrawn` issuance only." }, "status_effective_from": { "$ref": "#/components/schemas/Timestamp" }, "issued_at": { "$ref": "#/components/schemas/Timestamp" }, "certificate": { "$ref": "#/components/schemas/CertificateEnvelope" } } } } } }, "VerifyRequest": { "type": "object", "additionalProperties": false, "description": "Either the record's exact bytes (base64, so nothing re-serialises them) and its seal —\nboth required then — optionally with an index row to check against the projection and the\nrecord's sidecar (as a fetch returns it) for the scope and the projection re-run; or an ad\npool item alone (`ad_item`), whose own sealed bytes, inline seal and signed row\nare what is checked.\n", "properties": { "ad_item": { "type": "object", "additionalProperties": true, "description": "An ad exactly as `POST /v1/ads/pool` served it (retrieval API `PoolAd`), posted alone.\nIts `record_base64` is the record, the seal inside its signed `row` (`adl_origin_seal`)\nis the seal, `row` is the row; the answer's `ad` is the whole item checked as the SDKs'\n`verifyAdItem` checks it (the creative shown is the sealed one), and `ai_policy_bits`\nchecks the advertiser's AI policy the item carries against the bits on its row.\n" }, "record_base64": { "type": "string", "contentEncoding": "base64", "maxLength": 204800 }, "seal": { "$ref": "#/components/schemas/RecordSeal" }, "row": { "type": "object", "additionalProperties": true, "description": "An index row as served, to re-run the projection against." }, "sidecar": { "$ref": "#/components/schemas/Envelope", "description": "The record version's sidecar (`sidecar.v2`, or `sidecar.v1`; signed by MasterDB's sidecar key), as `GET /v1/records/{id}` returns it." }, "ai_policy_bits": { "$ref": "#/components/schemas/AiPolicyBits", "description": "The `ai_policy_bits` a search row carried. Checked against this record, which must then be the business's sealed AI policy record; the answer's `ai_policy_bits`." }, "key_events": { "type": "string", "enum": [ "warn", "require" ], "description": "What to do when the seal's key has no `key_added` leaf proven in the transparency log, as the\nverifier libraries' `keyEvents`. `warn` (the default) keeps the seal and says so\n(`checks.key_event: missing`, a line in `warnings`); `require` refuses it, `key_event_missing`.\nA key added in the last hour has a staged leaf but no proof yet.\n" } } }, "VerifierReason": { "type": "string", "description": "Why a check failed — the stable reason codes every MasterDB verifier uses (`verifier/README.md`), shared with the open-source libraries and their broken-record corpus.", "enum": [ "envelope_malformed", "payload_type_mismatch", "payload_malformed", "version_unknown", "key_unknown", "signature_invalid", "key_mismatch", "hash_mismatch", "record_malformed", "record_type_mismatch", "key_not_valid", "key_compromised", "certificate_unknown", "certificate_invalid", "certificate_not_in_force", "certificate_withdrawn", "ai_policy_version_mismatch", "ai_policy_bits_mismatch", "out_of_scope", "mandate_invalid", "inclusion_invalid", "trust_chain_broken", "post_quantum_required", "projection_unknown", "row_signature_invalid", "receipt_row_mismatch", "checkpoint_invalid", "consistency_invalid", "projection_mismatch", "ad_mismatch", "key_event_missing" ] }, "Check": { "type": "string", "enum": [ "ok", "not_checked", "not_applicable" ] }, "VerifyResult": { "type": "object", "required": [ "seal", "log_inclusion", "statement" ], "properties": { "seal": { "type": "object", "required": [ "valid" ], "properties": { "valid": { "type": "boolean" }, "reason": { "$ref": "#/components/schemas/VerifierReason" }, "detail": { "type": "string" }, "path": { "type": "string", "enum": [ "A", "B", "key" ], "description": "A — a pushed record in a sealed batch; B — sealed by a person's passkey; key — a single seal by an integration key (a sealed withdraw or delete)." }, "key_id": { "$ref": "#/components/schemas/KeyId" }, "cert_id": { "$ref": "#/components/schemas/Sha256" }, "business_uuid": { "$ref": "#/components/schemas/BusinessUuid" }, "sealed_at": { "$ref": "#/components/schemas/Timestamp" }, "record_type": { "type": "string" }, "ai_policy_version": { "type": "integer", "minimum": 0, "description": "The AI policy version the seal binds (`terms_version` in a format 1 seal)." }, "format": { "type": "integer", "enum": [ 1, 2 ], "description": "The seal format — 2 (`seal.v2`, `batch-seal.v2`), or 1 for earlier seals." }, "checks": { "type": "object", "properties": { "signature": { "$ref": "#/components/schemas/Check" }, "hash": { "$ref": "#/components/schemas/Check" }, "inclusion": { "$ref": "#/components/schemas/Check" }, "schema": { "$ref": "#/components/schemas/Check" }, "key_validity": { "$ref": "#/components/schemas/Check" }, "certificate": { "$ref": "#/components/schemas/Check" }, "ai_policy": { "$ref": "#/components/schemas/Check" }, "scope": { "$ref": "#/components/schemas/Check" }, "key_event": { "type": "string", "enum": [ "ok", "missing", "not_checked", "not_applicable" ], "description": "The seal key's `key_added` leaf — `ok` proven into a signed checkpoint, `missing` not proven (only with `key_events` warn)." } } }, "key_event": { "type": "object", "description": "Where the seal key's `key_added` leaf is in the log, when `checks.key_event` is `ok`. The leaf's position is when the log heard of the key, not when the key was added.", "required": [ "leaf", "leaf_index", "tree_size" ], "properties": { "leaf": { "$ref": "#/components/schemas/Sha256" }, "leaf_index": { "type": "integer", "minimum": 0 }, "tree_size": { "type": "integer", "minimum": 1 } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "What a `warn` check found and let pass (a key with no proven `key_added` leaf)." } } }, "log_inclusion": { "type": "object", "required": [ "included" ], "properties": { "included": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "log_not_available", "not_in_log" ], "description": "Why there is no proof — the log has no checkpoint yet, or the seal's leaf is not in one (leaves are sequenced hourly)." }, "leaf": { "$ref": "#/components/schemas/Sha256" }, "leaf_index": { "type": "integer", "minimum": 0 }, "tree_size": { "type": "integer" }, "checkpoint": { "type": "string", "description": "The signed checkpoint the inclusion was proven against; fetch the proof itself at `GET /v1/log/proof?leaf=`." } } }, "projection": { "type": "object", "required": [ "matches", "signature_valid", "from_record", "rerun" ], "properties": { "matches": { "type": "boolean" }, "version": { "type": "string" }, "signature_valid": { "type": "boolean" }, "from_record": { "type": "boolean", "description": "The row's `adl_origin` is the hash of these record bytes." }, "rerun": { "type": "string", "enum": [ "matched", "differs", "not_run" ], "description": "The published projection re-run over the record and its sidecar, compared byte for byte (run when the sidecar is sent)." }, "reason": { "type": "string" } } }, "ai_policy_bits": { "type": "object", "description": "Present when `ai_policy_bits` was sent: whether the bits are the ones the\nsealed AI policy record's named booleans derive, at the version its own seal created —\nthe `purchase` bit alone may have been withheld. `reason` is a verifier reason\n(`ai_policy_bits_mismatch`, `record_malformed`), `seal_invalid` when the record's own seal\ndid not verify, or `record_type_mismatch` when the record is not an AI policy.\n", "required": [ "matches" ], "properties": { "matches": { "type": "boolean" }, "ai_policy_version": { "type": "integer", "minimum": 0 }, "ai_policy_schema": { "type": "integer", "minimum": 1 }, "blocked_codes": { "type": "array", "items": { "type": "string", "pattern": "^bc[1-9][0-9]*$" } }, "purchase_withheld": { "type": "boolean" }, "reason": { "type": "string" }, "detail": { "type": "string" } } }, "ad": { "type": "object", "description": "With `ad_item` only — the whole pool item as the SDKs' `verifyAdItem` checks it against the advertiser's register — the row, the sealed bytes, the seal, every text and link in `creative` the sealed one, and the AI policy it carries. `reason` is a verifier reason (`ad_mismatch` when what would be shown is not what was sealed).", "required": [ "matches" ], "properties": { "matches": { "type": "boolean" }, "creative": { "type": "string", "enum": [ "matched" ] }, "reason": { "$ref": "#/components/schemas/VerifierReason" }, "detail": { "type": "string" } } }, "statement": { "$ref": "#/components/schemas/Envelope" } } }, "SignedKeySet": { "type": "object", "required": [ "keys", "signed" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/Jwk" } }, "signed": { "description": "The key set as a `jwks.v1` DSSE envelope over `{v: 1, issued_at, keys, certificates}`\n(every key's `key-certificate.v1`, so the chain to the anchors travels with it), signed\nby the issuance key pair (P-256 and ML-DSA-65). The only part a verifier trusts.\n", "$ref": "#/components/schemas/Envelope" } } }, "ProjectionSpec": { "type": "object", "required": [ "version", "sha256", "record_type", "field_map" ], "properties": { "version": { "type": "string", "description": "`{type}/{version}`, e.g. `products/1`." }, "spec_version": { "type": "integer", "description": "The version of the whole specification document (`platform/projections/v{n}.json`)." }, "sha256": { "$ref": "#/components/schemas/Sha256", "description": "The `adl_proj` of every row this version projects — SHA-256 over the RFC 8785 bytes of `definition`." }, "record_type": { "type": "string" }, "field_map": { "type": "object", "additionalProperties": { "type": "string" } }, "rules": { "type": "object", "additionalProperties": { "type": "string" } }, "unsigned_fields": { "type": "array", "description": "The row fields the projection signature does not cover (set in the region).", "items": { "type": "string" } }, "serve_time_fields": { "type": "array", "description": "The members the retrieval service adds to a row when it serves it that this version's own unsigned list does not name (`freshness_expectation` and `ai_policy_bits`; `terms` under the earlier name), removed before the signature is checked. For v3, which lists `ai_policy_bits` itself, only `freshness_expectation`.", "items": { "type": "string" } }, "definition": { "type": "object", "additionalProperties": true, "description": "The machine-readable definition `sha256` is taken over." } } }, "SpecIndex": { "type": "object", "required": [ "payload_types", "specifications" ], "properties": { "payload_types": { "type": "array", "items": { "$ref": "#/components/schemas/PayloadType" } }, "specifications": { "type": "array", "items": { "type": "object", "required": [ "name", "version", "url", "sha256" ], "properties": { "name": { "type": "string" }, "version": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "sha256": { "$ref": "#/components/schemas/Sha256" }, "test_vectors_url": { "type": "string", "format": "uri" } } } } } }, "LogConsistencyProof": { "type": "object", "additionalProperties": false, "required": [ "from_size", "to_size", "proof" ], "properties": { "from_size": { "type": "integer", "minimum": 1 }, "to_size": { "type": "integer", "minimum": 1 }, "proof": { "type": "array", "items": { "$ref": "#/components/schemas/Sha256" } }, "checkpoint": { "type": "string", "description": "The signed note of `to_size`, when that is the latest checkpoint." } } }, "InclusionProof": { "type": "object", "required": [ "leaf", "leaf_type", "leaf_index", "tree_size", "proof", "checkpoint" ], "properties": { "leaf": { "$ref": "#/components/schemas/Sha256" }, "leaf_type": { "type": "string", "enum": [ "seal", "receipt_batch", "certificate", "key_event", "checkpoint", "sidecar", "receipt" ] }, "leaf_index": { "type": "integer", "minimum": 0 }, "tree_size": { "type": "integer", "minimum": 1 }, "proof": { "type": "array", "items": { "$ref": "#/components/schemas/Sha256" } }, "batch": { "type": "object", "description": "For a receipt only — its place in the region's one-minute batch, the first level of the proof.", "required": [ "region", "minute", "name", "index", "size", "root", "proof" ], "properties": { "region": { "type": "string" }, "minute": { "type": "string" }, "name": { "type": "string", "description": "The minute list's name under `receipts/{region}/` (the minute, or the minute and instance)." }, "index": { "type": "integer" }, "size": { "type": "integer", "minimum": 1, "description": "Leaves in the minute tree — the first level's inclusion check takes the tree size (RFC 9162)." }, "root": { "$ref": "#/components/schemas/Sha256" }, "proof": { "type": "array", "items": { "$ref": "#/components/schemas/Sha256" } } } }, "checkpoint": { "type": "string", "description": "The signed note the proof is against." } } }, "Vocabulary": { "type": "object", "description": "One version of a platform vocabulary, exactly as `platform/vocabularies/{name}/v{N}.json`\nholds it (the file's `vocabulary` member is `name` here). Each entry has a unique `id` and\nthe vocabulary's own fields (platform/vocabularies/README.md).\n", "required": [ "name", "version", "published_at", "entries" ], "properties": { "name": { "type": "string" }, "version": { "type": "integer" }, "published_at": { "type": "string", "format": "date" }, "entries": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } } } }, "Uuid": { "type": "string", "description": "A lower-case UUIDv4.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "ErrorCode": { "type": "string", "description": "The stable, machine-readable reason. A code, once published, is never renamed or reused; callers branch on it. `x-masterdb-status` gives the HTTP status each code is returned with when it is a refusal.", "enum": [ "sort_required", "filter_required", "country_required", "unknown_field", "operator_not_allowed", "sort_not_allowed", "value_invalid", "limit_exceeded", "collection_unknown", "request_invalid", "signature_missing", "signature_invalid", "signature_expired", "key_unknown", "nonce_reused", "digest_mismatch", "no_grant", "permission_denied", "grant_expired", "grant_deactivated", "party_not_verified", "party_suspended", "party_held", "party_not_funded", "admin_hold", "passkey_required", "device_bound_required", "invitation_invalid", "invitation_email_mismatch", "domain_claimed", "assembly_pending", "agreement_required", "challenge_invalid", "registration_invalid", "assertion_invalid", "passkey_test_failed", "credential_unknown", "credential_exists", "mint_assertion_missing", "session_invalid", "record_invalid", "json_invalid", "record_too_large", "duplicate_key", "depth_exceeded", "string_too_long", "too_many_keys", "control_character", "zero_width_character", "bidi_override", "not_nfc", "invalid_utf8", "bom_present", "number_invalid", "money_not_string", "money_invalid", "schema_missing", "schema_invalid", "not_canonical", "seal_invalid", "seal_key_unknown", "seal_payload_type", "seal_hash_mismatch", "seal_time_skew", "seq_not_increasing", "price_country_not_published", "unsafe_url", "field_required", "plain_text_required", "role_address_required", "personal_data", "country_invalid", "currency_invalid", "language_invalid", "vocabulary_invalid", "seal_required", "mandate_required", "mandate_scope", "draft_revision_conflict", "scope_violation", "url_flagged", "display_domain_mismatch", "image_type_refused", "image_invalid", "source_not_allowed", "domain_unproven", "verification_level_insufficient", "screening_not_passed", "verification_locked", "feature_not_enabled", "prf_unsupported", "budget_exhausted", "window_expired", "token_invalid", "token_reused", "allowance_exhausted", "idempotency_key_missing", "idempotency_key_invalid", "idempotency_key_reused", "idempotency_in_progress", "unauthenticated", "step_up_required", "forbidden", "not_found", "conflict", "rate_limited", "internal", "not_implemented", "unavailable" ], "x-enumDescriptions": { "sort_required": "A sort is required", "filter_required": "A filter naming exactly one country is required", "country_required": "A country is required", "unknown_field": "Field not allowed for this collection", "operator_not_allowed": "Operator not allowed for this field", "sort_not_allowed": "Sort key not allowed for this collection", "value_invalid": "Value is not valid for this field", "limit_exceeded": "Limit exceeds the maximum", "collection_unknown": "Unknown collection", "request_invalid": "Request is not valid", "signature_missing": "Request is not signed", "signature_invalid": "Request signature is not valid", "signature_expired": "Request signature is outside its validity window", "key_unknown": "Signing key is not registered or not live", "nonce_reused": "Nonce has already been used", "digest_mismatch": "Content-Digest does not match the body", "no_grant": "You hold no grant on this party", "permission_denied": "Your roles on this party do not include this action", "grant_expired": "Your access to this party has expired", "grant_deactivated": "Your access to this party is deactivated", "party_not_verified": "The party must be verified for this action", "party_suspended": "The party is suspended", "party_held": "The party is on hold: its records stay live, new publishing is paused", "party_not_funded": "The party has no funds for this action", "admin_hold": "A new admin cannot change grants, keys or mandates for 24 hours", "passkey_required": "This action requires a passkey", "device_bound_required": "This party requires a device-bound passkey for sealing", "invitation_invalid": "Invitation is not valid", "invitation_email_mismatch": "Sign in with the email address the invitation was sent to", "domain_claimed": "This email domain belongs to an existing party", "assembly_pending": "This AI company's setup is not complete", "agreement_required": "The AI-company Terms in force must be accepted first", "challenge_invalid": "Challenge is unknown, expired or already used", "registration_invalid": "Passkey registration is not valid", "assertion_invalid": "Passkey assertion is not valid", "passkey_test_failed": "The new passkey failed its test signature and was not saved", "credential_unknown": "Passkey is not registered or has been revoked", "credential_exists": "Passkey is already registered", "mint_assertion_missing": "Sign-in token has no recent mint assertion", "session_invalid": "The session is not bound to a live MasterDB sign-in; sign in again", "record_invalid": "Record is not valid", "json_invalid": "Body is not one strict JSON value", "record_too_large": "Record is too large", "duplicate_key": "Object has a duplicate key", "depth_exceeded": "Nesting is too deep", "string_too_long": "String is too long", "too_many_keys": "Object has too many keys", "control_character": "String contains a control character", "zero_width_character": "String contains a zero-width space or U+FEFF", "bidi_override": "String contains a bidirectional override", "not_nfc": "String is not in Unicode Normalization Form C", "invalid_utf8": "Body is not valid UTF-8", "bom_present": "Body starts with a byte-order mark", "number_invalid": "Number is outside the range every parser agrees on", "money_not_string": "Money must be a decimal string", "money_invalid": "Money string is not a valid decimal", "schema_missing": "Record has no top-level schema field", "schema_invalid": "Record schema field is not valid", "not_canonical": "Bytes are not in the canonical form", "seal_invalid": "Seal does not verify", "seal_key_unknown": "Seal names a key that is not registered", "seal_payload_type": "Envelope carries the wrong payload type", "seal_hash_mismatch": "Seal hash does not match the record bytes", "seal_time_skew": "sealed_at is too far from the time of receipt", "seq_not_increasing": "Batch sequence number is not greater than the last accepted", "price_country_not_published": "A price names a country the record is not published in", "unsafe_url": "URL points at a private or unsafe address", "field_required": "A required field is missing", "plain_text_required": "Text must be plain text", "role_address_required": "A published contact must be a role address, not a person", "personal_data": "Freeform text must not carry personal data", "country_invalid": "Not a country code in the platform vocabulary", "currency_invalid": "Not a currency code in the platform vocabulary", "language_invalid": "Not a language in the platform vocabulary", "vocabulary_invalid": "Value is not in the controlled vocabulary", "seal_required": "A seal is required", "mandate_required": "The signing key has no live publishing mandate", "mandate_scope": "The mandate does not cover this record type or country", "draft_revision_conflict": "The draft has changed since you read it", "scope_violation": "Text names another company or brand, or directs how other sources are treated", "url_flagged": "URL is flagged as unsafe", "display_domain_mismatch": "display_domain is not the destination host", "image_type_refused": "Only JPEG, PNG and WebP images are accepted", "image_invalid": "Image could not be decoded within the limits", "source_not_allowed": "The request comes from outside the mandate’s source allow-list", "domain_unproven": "An endpoint domain has no live proof of control", "verification_level_insufficient": "This action is not available to this party until its verification is complete: finish it, then try again", "screening_not_passed": "A check this action needs has not passed: try again later, and if it still has not passed, get in touch with us", "verification_locked": "Locked while verification is submitted or decided", "feature_not_enabled": "This feature is not enabled", "prf_unsupported": "The passkey does not support the PRF extension", "budget_exhausted": "Budget exhausted", "window_expired": "Confirmation window has expired", "token_invalid": "Token is not valid", "token_reused": "Token has already been confirmed", "allowance_exhausted": "Query allowance exhausted", "idempotency_key_missing": "Idempotency-Key header is required", "idempotency_key_invalid": "Idempotency-Key header is not valid", "idempotency_key_reused": "Idempotency-Key was used with a different request", "idempotency_in_progress": "A request with this Idempotency-Key is in progress", "unauthenticated": "Not signed in", "step_up_required": "A stronger sign-in is required for this action", "forbidden": "Not permitted", "not_found": "Not found", "conflict": "Conflict", "rate_limited": "Too many requests", "internal": "Internal error", "not_implemented": "Not implemented", "unavailable": "Temporarily unavailable" } }, "FieldError": { "type": "object", "description": "One reason among several: a request or record that fails several checks is answered with every reason at once.", "additionalProperties": false, "required": [ "code", "pointer", "detail" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "pointer": { "type": "string", "description": "JSON Pointer (RFC 6901) into the request or record; \"\" is the whole document." }, "detail": { "type": "string" } } }, "Problem": { "type": "object", "description": "RFC 9457 problem details, the one error shape on every MasterDB API. `type` is the documentation page of `code`. Extension members may appear; they never shadow the standard ones.", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "`https://docs.masterdb.ai/errors/{code}`" }, "title": { "type": "string", "description": "The code's human title; may be reworded, never branch on it." }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "detail": { "type": "string" }, "instance": { "type": "string", "description": "The request path, or the request id." }, "errors": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FieldError" } } } }, "Timestamp": { "type": "string", "description": "RFC 3339 UTC with milliseconds, e.g. 2026-09-23T14:02:11.482Z.", "format": "date-time" }, "Sha256": { "type": "string", "description": "A SHA-256 digest, `sha256:` + 64 lower-case hex.", "pattern": "^sha256:[0-9a-f]{64}$" }, "BusinessUuid": { "type": "string", "description": "A business's permanent public identifier, a lower-case UUIDv4.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "AiCompanyUuid": { "type": "string", "description": "An AI company's permanent public identifier, a lower-case UUIDv4.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "CertificatePayload": { "type": "object", "description": "The ADL certificate of a business (`business_uuid`) or an AI company\n(`ai_company_uuid`). No secret, no expiry; re-issued on a status change, never edited;\nevery issuance is a leaf in the transparency log. `revoked` is key compromise: seals\nfrom `status_effective_from` are invalid. `withdrawn` is MasterDB withdrawing its\nattestation — a reversed verification approval — and says nothing about the subject's\nkeys: seals before `status_effective_from` stand, a later one no longer does\n(`certificate_withdrawn`), and only a withdrawn issuance carries `status_reason`.\n\n**The certificate says who the subject is, its legal\nname, its jurisdiction (the country), that MasterDB verified it and since when, and its\nstatus — never how it was verified.** Any other member is refused\n(`payload_malformed`): the format is closed.\n", "required": [ "v", "legal_name", "jurisdiction", "issued_at", "status", "status_effective_from" ], "properties": { "v": { "const": 1 }, "business_uuid": { "$ref": "#/components/schemas/BusinessUuid" }, "ai_company_uuid": { "$ref": "#/components/schemas/AiCompanyUuid" }, "legal_name": { "type": "string" }, "jurisdiction": { "type": "string" }, "issued_at": { "$ref": "#/components/schemas/Timestamp" }, "status": { "type": "string", "enum": [ "active", "closed", "suspended", "revoked", "withdrawn" ] }, "status_effective_from": { "$ref": "#/components/schemas/Timestamp" }, "status_reason": { "type": "string", "enum": [ "approval_reversed" ], "description": "Why MasterDB withdrew the certificate; present only when `status` is `withdrawn`." }, "sandbox": { "type": "boolean" } }, "oneOf": [ { "required": [ "business_uuid" ] }, { "required": [ "ai_company_uuid" ] } ] }, "KeyId": { "type": "string", "description": "The RFC 7638 JWK thumbprint of a public key, base64url, 43 characters.", "pattern": "^[A-Za-z0-9_-]{43}$" }, "EnvelopeSignature": { "type": "object", "additionalProperties": false, "required": [ "keyid", "sig" ], "properties": { "keyid": { "$ref": "#/components/schemas/KeyId" }, "sig": { "type": "string", "contentEncoding": "base64", "description": "The signature, base64. ES256 is raw `r || s` (64 bytes); a WebAuthn assertion's signature stays DER." }, "authenticatorData": { "type": "string", "contentEncoding": "base64", "description": "A passkey signature only — the WebAuthn authenticator data." }, "clientDataJSON": { "type": "string", "contentEncoding": "base64", "description": "A passkey signature only — the WebAuthn client data, whose challenge is `\"mdb-seal\" || SHA-256(PAE(payloadType, payload))`." } } }, "Signatures": { "type": "array", "description": "One or two signatures over PAE(payloadType, payload) — the classical one and, for long-lived artefacts, the ML-DSA-65 one in the second slot.", "minItems": 1, "maxItems": 2, "items": { "$ref": "#/components/schemas/EnvelopeSignature" } }, "CertificateEnvelope": { "type": "object", "additionalProperties": false, "required": [ "payloadType", "payload", "signatures" ], "properties": { "payloadType": { "type": "string", "const": "application/vnd.masterdb.certificate.v1+json" }, "payload": { "type": "string", "contentEncoding": "base64", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/CertificatePayload" } }, "signatures": { "$ref": "#/components/schemas/Signatures" } } }, "Envelope": { "type": "object", "description": "A DSSE envelope. One or two signatures: the classical one and, for long-lived\nartefacts, the ML-DSA-65 one in the second slot. A verifier always states\nwhich `payloadType` it expects.\n", "additionalProperties": false, "required": [ "payloadType", "payload", "signatures" ], "properties": { "payloadType": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$" }, "payload": { "type": "string", "contentEncoding": "base64" }, "signatures": { "$ref": "#/components/schemas/Signatures" } } }, "KeyCustodyPayload": { "type": "object", "additionalProperties": false, "description": "Who holds a business key's private half: `hosted` — the key MasterDB issued to the\nverified business and holds for it (standard publishing; a seal by it proves MasterDB\nsigned on a confirmed request of a person with a grant, not that a person of the business\nsigned); `self` — a key the business holds (a person's passkey, an integration key). Signed\nlike the certificate by both halves of the issuance key. One per key, re-issued (never\nedited) when the key's custody changes; the statement in force at an instant is the latest\n`effective_from` at or before it. Every issuance is a `key_event` leaf in the transparency\nlog. Certificate v2 carries `key_custody` itself (verifier 1.1).\n", "required": [ "v", "business_uuid", "key_id", "custody", "issued_at", "effective_from" ], "properties": { "v": { "const": 1 }, "business_uuid": { "$ref": "#/components/schemas/BusinessUuid" }, "key_id": { "$ref": "#/components/schemas/KeyId" }, "custody": { "type": "string", "enum": [ "hosted", "self" ] }, "issued_at": { "$ref": "#/components/schemas/Timestamp" }, "effective_from": { "$ref": "#/components/schemas/Timestamp", "description": "From when the statement holds; never after `issued_at`. A first statement takes effect from the key's own start." }, "sandbox": { "const": true } } }, "KeyCustodyEnvelope": { "type": "object", "additionalProperties": false, "required": [ "payloadType", "payload", "signatures" ], "properties": { "payloadType": { "type": "string", "const": "application/vnd.masterdb.key-custody.v1+json" }, "payload": { "type": "string", "contentEncoding": "base64", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/KeyCustodyPayload" } }, "signatures": { "$ref": "#/components/schemas/Signatures" } } }, "SealPayload": { "type": "object", "description": "A record's seal, format 2 (`seal.v2`). `hash` is over the exact bytes stored;\n`sealed_at` is inside the signed payload; `ai_policy_version` is the business's AI policy\nversion in force at `sealed_at` (an AI policy record's own seal: the version it creates).\nFormat 1 (`seal.v1`: `v` 1 and `terms_version`) is still verified and,\nstill accepted from a pushing system.\n", "required": [ "v", "key_id", "cert_id", "hash", "sealed_at", "record_type", "ai_policy_version" ], "properties": { "v": { "const": 2 }, "key_id": { "$ref": "#/components/schemas/KeyId" }, "cert_id": { "type": "string" }, "hash": { "$ref": "#/components/schemas/Sha256" }, "sealed_at": { "$ref": "#/components/schemas/Timestamp" }, "record_type": { "type": "string" }, "ai_policy_version": { "type": "integer", "minimum": 0 } } }, "SealEnvelope": { "description": "A Path B seal (one record, sealed by a person's passkey). Format 2 (`seal.v2`); format 1 (`seal.v1`) is still verified.", "type": "object", "additionalProperties": false, "required": [ "payloadType", "payload", "signatures" ], "properties": { "payloadType": { "type": "string", "enum": [ "application/vnd.masterdb.seal.v2+json", "application/vnd.masterdb.seal.v1+json" ] }, "payload": { "type": "string", "contentEncoding": "base64", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SealPayload" } }, "signatures": { "$ref": "#/components/schemas/Signatures" } } }, "BatchSealPayload": { "type": "object", "description": "A Path A batch seal, format 2 (`batch-seal.v2`; format 1 names `terms_version` and is still accepted). `seq` is the per-key anti-rollback counter; `tree_size` comes from here, never from a proof.", "required": [ "v", "key_id", "cert_id", "root", "tree_size", "seq", "sealed_at", "record_type", "ai_policy_version" ], "properties": { "v": { "const": 2 }, "key_id": { "$ref": "#/components/schemas/KeyId" }, "cert_id": { "type": "string" }, "root": { "$ref": "#/components/schemas/Sha256" }, "tree_size": { "type": "integer", "minimum": 1 }, "seq": { "type": "integer", "minimum": 0 }, "sealed_at": { "$ref": "#/components/schemas/Timestamp" }, "record_type": { "type": "string" }, "ai_policy_version": { "type": "integer", "minimum": 0 } } }, "BatchSealEnvelope": { "type": "object", "additionalProperties": false, "required": [ "payloadType", "payload", "signatures" ], "properties": { "payloadType": { "type": "string", "enum": [ "application/vnd.masterdb.batch-seal.v2+json", "application/vnd.masterdb.batch-seal.v1+json" ] }, "payload": { "type": "string", "contentEncoding": "base64", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/BatchSealPayload" } }, "signatures": { "$ref": "#/components/schemas/Signatures" } } }, "BatchRecordSeal": { "type": "object", "description": "What a Path A record's seal holds: the batch envelope, the record's leaf index\nand its inclusion proof (RFC 6962 hashing, `0x00` leaf and `0x01` node prefixes; the\nleaf is the record's raw bytes), so the record verifies on its own.\n", "additionalProperties": false, "required": [ "envelope", "leaf_index", "proof" ], "properties": { "envelope": { "$ref": "#/components/schemas/BatchSealEnvelope" }, "leaf_index": { "type": "integer", "minimum": 0 }, "proof": { "type": "array", "items": { "$ref": "#/components/schemas/Sha256" } } } }, "RecordSeal": { "description": "A record's seal as stored and served — a Path B seal envelope or a Path A batch member.", "oneOf": [ { "$ref": "#/components/schemas/SealEnvelope" }, { "$ref": "#/components/schemas/BatchRecordSeal" } ] }, "AiPolicyBits": { "type": "object", "description": "The business's AI policy in force at `served_at`, stamped on the row by the retrieval service from the business's current sealed\n`ai_policy` record, so an AI company answering from the row alone knows what\nthe business permits and the contexts it does not want its data used in. Each mask is\nderived from the sealed named booleans — bit *i* set exactly when the *i*-th boolean of its\ngroup in `ai_policy_schema` is true — and the key to every bit is `GET /v1/ai-policy-key`.\nOutside the row signature (projection spec v3 lists it among the unsigned fields); what\nproves it is the sealed record a fetch returns (`ai_policy`). A business that has never\nsealed an AI policy is version 0 with every mask 0: nothing permitted beyond the AI-company\nTerms, nothing blocked.\n", "required": [ "ai_policy_version", "ai_policy_schema", "use", "action", "blocked" ], "properties": { "ai_policy_version": { "type": "integer", "minimum": 0, "description": "The AI policy version in force — its record's live generation; 0 when there is none." }, "ai_policy_schema": { "type": "integer", "minimum": 1, "description": "Which booleans exist and in what bit order (schema 2 adds the blocked contexts; schema 1 has none)." }, "use": { "type": "integer", "minimum": 0, "description": "Bitmask of the use toggles (cite as source, definitive source, prefer over inference, include in recommendations, quote policies verbatim, prices indicative, state publish date), bits 0–6." }, "action": { "type": "integer", "minimum": 0, "description": "Bitmask of the action terms — answer, quote, reserve, purchase, contact, hand to human — bits 0–5. The purchase bit is withheld while the business's authorised endpoints are suspended." }, "blocked": { "type": "integer", "minimum": 0, "description": "Bitmask of the blocked contexts: bit *n*−1 is `bc{n}` — bc1 adult_sexual, bc2\nalcohol, bc3 crime_illegal, bc4 death_tragedy_disaster, bc5 firearms_weapons_violence,\nbc6 gambling_betting, bc7 mental_health_self_harm, bc8 politics_elections, bc9\nregulated_advice, bc10 tobacco_vaping_drugs. A set bit: do not use this business's data\nto build a response in that context. The business's content policy, the same for every\ncaller. 0 under `ai_policy_schema` 1.\n" } }, "examples": [ { "ai_policy_version": 4, "ai_policy_schema": 2, "use": 79, "action": 51, "blocked": 130 } ] }, "Jwk": { "type": "object", "description": "A public JWK — Ed25519 `OKP`, P-256 `EC`, or ML-DSA-65 `AKP` (`{kty: \"AKP\", alg:\n\"ML-DSA-65\", pub}`, the second signature slot of, whose RFC 7638 thumbprint is over\n`alg`, `kty`, `pub`) — with what the key is for and its validity window.\n", "required": [ "kty", "kid" ], "properties": { "kty": { "type": "string", "enum": [ "OKP", "EC", "AKP" ] }, "crv": { "type": "string", "enum": [ "Ed25519", "P-256" ] }, "x": { "type": "string" }, "y": { "type": "string" }, "alg": { "type": "string", "enum": [ "ML-DSA-65" ] }, "pub": { "type": "string", "description": "An AKP key's public key, base64url (1,952 bytes for ML-DSA-65)." }, "kid": { "$ref": "#/components/schemas/KeyId" }, "use": { "type": "string" }, "purpose": { "type": "string", "enum": [ "root", "issuance", "projection", "receipt", "sidecar", "log_checkpoint", "statement", "entitlement" ] }, "region": { "type": "string" }, "valid_from": { "$ref": "#/components/schemas/Timestamp" }, "valid_until": { "$ref": "#/components/schemas/Timestamp" }, "compromised_from": { "$ref": "#/components/schemas/Timestamp" } } }, "AiPolicyKeyEntry": { "type": "object", "required": [ "name", "meaning", "bit", "since_schema" ], "properties": { "name": { "type": "string" }, "meaning": { "type": "string" }, "bit": { "type": "integer", "minimum": 0 }, "since_schema": { "type": "integer", "minimum": 1 } } }, "BlockedContextKeyEntry": { "type": "object", "description": "One blocked context. A code is never reused or renamed; a retired context keeps its number and gains `retired_in_schema`.", "required": [ "number", "code", "name", "meaning", "bit", "since_schema" ], "properties": { "number": { "type": "integer", "minimum": 1 }, "code": { "type": "string", "pattern": "^bc[1-9][0-9]*$" }, "name": { "type": "string" }, "meaning": { "type": "string" }, "bit": { "type": "integer", "minimum": 0, "description": "The bit of `ai_policy_bits.blocked` (`number` − 1)." }, "since_schema": { "type": "integer", "minimum": 1 }, "retired_in_schema": { "type": "integer", "minimum": 1 } } }, "AiPolicyKey": { "type": "object", "description": "The key to `ai_policy_bits` — every bit of every group, by name, with its meaning and the schema it arrived in.", "required": [ "key_version", "current_ai_policy_schema", "rule", "groups", "blocked" ], "properties": { "key_version": { "type": "integer", "minimum": 1 }, "current_ai_policy_schema": { "type": "integer", "minimum": 1 }, "rule": { "type": "string" }, "groups": { "type": "object", "required": [ "use", "action" ], "properties": { "use": { "type": "array", "items": { "$ref": "#/components/schemas/AiPolicyKeyEntry" } }, "action": { "type": "array", "items": { "$ref": "#/components/schemas/AiPolicyKeyEntry" } } } }, "blocked": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedContextKeyEntry" } } } }, "PayloadType": { "type": "string", "description": "The `payloadType` of every DSSE envelope MasterDB makes or accepts. A verifier is always told which one it expects.", "enum": [ "application/vnd.masterdb.seal.v1+json", "application/vnd.masterdb.batch-seal.v1+json", "application/vnd.masterdb.seal.v2+json", "application/vnd.masterdb.batch-seal.v2+json", "application/vnd.masterdb.receipt.v1+json", "application/vnd.masterdb.receipt.v2+json", "application/vnd.masterdb.receipt.v3+json", "application/vnd.masterdb.business-keys.v1+json", "application/vnd.masterdb.render.v1+json", "application/vnd.masterdb.click.v1+json", "application/vnd.masterdb.mandate.v1+json", "application/vnd.masterdb.certificate.v1+json", "application/vnd.masterdb.key-custody.v1+json", "application/vnd.masterdb.key-certificate.v1+json", "application/vnd.masterdb.jwks.v1+json", "application/vnd.masterdb.row.v1+json", "application/vnd.masterdb.sidecar.v1+json", "application/vnd.masterdb.sidecar.v2+json", "application/vnd.masterdb.verify-statement.v1+json", "application/vnd.masterdb.verify-page.v1+json", "application/vnd.masterdb.key-directory.v1+json", "application/vnd.masterdb.claim-statement.v1+json", "application/vnd.masterdb.system-action.v1+json", "application/vnd.masterdb.message.v1+json", "application/vnd.masterdb.message-deletion.v1+json", "application/vnd.masterdb.ceremony-transcript.v1+json", "application/vnd.masterdb.evidence-pack.v1+json", "application/vnd.masterdb.entitlement.v1+json" ] }, "RecordId": { "type": "string", "description": "A record identifier: `mdb_` + 26 base32 characters for a product, or `bf_`, `evt_`, `job_`, `upd_`, `ad_`, `aip_`, `frm_` + 22 random base32 characters. Never encodes its owner. `trm_` is no longer minted and still read (an AI policy sealed as `terms`, its earlier name).", "pattern": "^(?:mdb_[a-z2-7]{26}|(?:bf|evt|job|upd|ad|aip|frm|trm)_[a-z2-7]{22})$" } }, "headers": { "RequestId": { "description": "The request's id in MasterDB's logs (the `retrieval_id` on the retrieval API). Quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "Entity tag for conditional requests.", "schema": { "type": "string" } } }, "responses": { "Problem": { "description": "A refusal or failure, as RFC 9457 problem details with a stable `code`.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.masterdb.ai/errors/sort_required", "title": "A sort is required", "status": 400, "code": "sort_required", "detail": "sort_by is required; for relevance order write \"_text_match:desc\"", "errors": [ { "code": "sort_required", "pointer": "/sort_by", "detail": "sort_by is required; for relevance order write \"_text_match:desc\"" } ] } } } }, "NotFound": { "description": "Not found. On the retrieval API a blocked, withdrawn or absent record all answer this\nsame body, no sooner than 20 ms after arrival.\n", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://docs.masterdb.ai/errors/not_found", "title": "Not found", "status": 404, "code": "not_found" } } } } } } }