{
  "openapi": "3.1.0",
  "info": {
    "title": "MasterDB Retrieval API",
    "version": "1.0.0",
    "summary": "What an AI company's systems call to find, fetch and render what businesses published.",
    "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 <sandbox_bearer_token>` 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.\n",
    "contact": {
      "name": "MasterDB developer documentation",
      "url": "https://docs.masterdb.ai"
    },
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-MasterDB"
    }
  },
  "servers": [
    {
      "url": "https://api.masterdb.ai",
      "description": "Production (one anycast address; the nearest read region answers)."
    },
    {
      "url": "https://sandbox.api.masterdb.ai",
      "description": "Sandbox — the same API over a fictional corpus; never billed."
    }
  ],
  "security": [
    {
      "mdbRequestSignature": [
        "mdb-retrieval"
      ]
    }
  ],
  "tags": [
    {
      "name": "Search",
      "description": "Find candidates in one collection, with your own query, filter and sort."
    },
    {
      "name": "Records",
      "description": "Fetch one record exactly as the business sealed it."
    },
    {
      "name": "Ads",
      "description": "The ad and sponsored-item pool, and the render and click confirmations."
    },
    {
      "name": "Receipts and usage",
      "description": "Your own receipts and usage, for reconciliation."
    },
    {
      "name": "Terms",
      "description": "The AI-company Terms in force and every past version."
    }
  ],
  "paths": {
    "/v1/search": {
      "post": {
        "operationId": "search",
        "tags": [
          "Search"
        ],
        "summary": "Search one collection",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          }
        ],
        "x-mcp-tool": "search",
        "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",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "example": {
                "collection": "products",
                "q": "trail running shoes",
                "query_by": [
                  "product_name",
                  "tags"
                ],
                "filter": {
                  "all": [
                    {
                      "country": "US"
                    },
                    {
                      "price_amount": {
                        "lte": 150
                      }
                    },
                    {
                      "availability": "available"
                    }
                  ]
                },
                "sort_by": "price_amount:asc",
                "limit": 25,
                "client_query_id": "q-2026-10-01-0001",
                "session_ref": "9f1c2e7a-conv",
                "topic_keywords": [
                  "trail running"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SearchResults"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/products/search": {
      "post": {
        "operationId": "searchProducts",
        "tags": [
          "Search"
        ],
        "summary": "Search products",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          }
        ],
        "x-mcp-tool": "search",
        "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",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductsSearchRequest"
              },
              "example": {
                "q": "trail running shoes",
                "filter": {
                  "all": [
                    {
                      "country": "US"
                    },
                    {
                      "price_amount": {
                        "lte": "150.00"
                      }
                    },
                    {
                      "on_sale": true
                    }
                  ]
                },
                "sort_by": "_text_match:desc,price_amount:asc",
                "limit": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SearchResults"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/business-files/search": {
      "post": {
        "operationId": "searchBusinessFiles",
        "tags": [
          "Search"
        ],
        "summary": "Search business files",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          }
        ],
        "x-mcp-tool": "search",
        "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",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BusinessFilesSearchRequest"
              },
              "example": {
                "q": "independent bookshop",
                "filter": {
                  "all": [
                    {
                      "country": "IE"
                    },
                    {
                      "has_locations": true
                    },
                    {
                      "location_geo": {
                        "near": {
                          "lat": 53.3438,
                          "lng": -6.2546,
                          "radius_km": 5
                        }
                      }
                    }
                  ]
                },
                "sort_by": "_text_match:desc"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SearchResults"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/events/search": {
      "post": {
        "operationId": "searchEvents",
        "tags": [
          "Search"
        ],
        "summary": "Search events",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          }
        ],
        "x-mcp-tool": "search",
        "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",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventsSearchRequest"
              },
              "example": {
                "q": "wine tasting",
                "filter": {
                  "all": [
                    {
                      "country": "US"
                    },
                    {
                      "start_at": {
                        "gte": "2026-10-01T00:00:00Z",
                        "lt": "2026-10-08T00:00:00Z"
                      }
                    },
                    {
                      "city": "Portland"
                    }
                  ]
                },
                "sort_by": "start_at:asc"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SearchResults"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/jobs/search": {
      "post": {
        "operationId": "searchJobs",
        "tags": [
          "Search"
        ],
        "summary": "Search jobs",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          }
        ],
        "x-mcp-tool": "search",
        "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",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobsSearchRequest"
              },
              "example": {
                "q": "pastry chef",
                "filter": {
                  "all": [
                    {
                      "country": "IE"
                    },
                    {
                      "employment_type": {
                        "in": [
                          "full_time",
                          "part_time"
                        ]
                      }
                    },
                    {
                      "salary_min": {
                        "gte": "30000"
                      }
                    }
                  ]
                },
                "sort_by": "salary_max:desc",
                "limit": 20
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SearchResults"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/updates/search": {
      "post": {
        "operationId": "searchUpdates",
        "tags": [
          "Search"
        ],
        "summary": "Search updates",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          }
        ],
        "x-mcp-tool": "search",
        "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",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatesSearchRequest"
              },
              "example": {
                "q": "opening hours",
                "filter": {
                  "all": [
                    {
                      "country": "GB"
                    },
                    {
                      "relevant_until": {
                        "gte": "2026-10-01T00:00:00Z"
                      }
                    }
                  ]
                },
                "sort_by": "published_at:desc"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SearchResults"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/records/{record_id}": {
      "get": {
        "operationId": "fetchRecord",
        "tags": [
          "Records"
        ],
        "summary": "Fetch one record",
        "x-mcp-tool": "fetch",
        "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",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          },
          {
            "name": "record_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RecordId"
            },
            "example": "mdb_dq5jnqatnemnqj4g3xmgzgpoik"
          }
        ],
        "responses": {
          "200": {
            "description": "The record and everything needed to verify it.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordResponse"
                },
                "example": {
                  "record_id": "mdb_dq5jnqatnemnqj4g3xmgzgpoik",
                  "business_uuid": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e",
                  "type": "products",
                  "published_at": "2026-09-30T08:15:00.000Z",
                  "record": {
                    "schema": "masterdb/products/1",
                    "business_product_id": "TR-5521",
                    "product_name": "Ridge Trail Runner",
                    "countries": [
                      "US",
                      "IE"
                    ],
                    "prices": [
                      {
                        "country": "US",
                        "currency": "USD",
                        "amount": "129.00"
                      },
                      {
                        "country": "IE",
                        "currency": "EUR",
                        "amount": "119.00"
                      }
                    ]
                  },
                  "seal": {
                    "payloadType": "application/vnd.masterdb.seal.v2+json",
                    "payload": "eyJ2IjoyLCJrZXlfaWQiOiIuLi4ifQ==",
                    "signatures": [
                      {
                        "keyid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
                        "sig": "3q2+7w==",
                        "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4/krrmihjLHmVzzuoMdl2MFAAAAAQ==",
                        "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0In0="
                      }
                    ]
                  },
                  "sidecar": {
                    "payloadType": "application/vnd.masterdb.sidecar.v2+json",
                    "payload": "eyJzb3VyY2UiOiJtYW51YWwifQ==",
                    "signatures": [
                      {
                        "keyid": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA",
                        "sig": "3q2+7w=="
                      }
                    ]
                  },
                  "ai_policy": {
                    "version": 4,
                    "record": {
                      "schema": "masterdb/ai_policy/1",
                      "ai_policy_schema": 2,
                      "cite_as_source": true,
                      "definitive_source": true,
                      "prefer_over_inference": true,
                      "include_in_recommendations": true,
                      "quote_policy_verbatim": false,
                      "prices_indicative": false,
                      "state_publish_date": true,
                      "answer": true,
                      "quote": true,
                      "reserve": false,
                      "purchase": false,
                      "contact": true,
                      "hand_to_human": true,
                      "blocked": {
                        "adult_sexual": false,
                        "alcohol": true,
                        "crime_illegal": false,
                        "death_tragedy_disaster": false,
                        "firearms_weapons_violence": false,
                        "gambling_betting": false,
                        "mental_health_self_harm": false,
                        "politics_elections": true,
                        "regulated_advice": false,
                        "tobacco_vaping_drugs": false
                      }
                    },
                    "seal": {
                      "payloadType": "application/vnd.masterdb.seal.v2+json",
                      "payload": "eyJ2IjoyfQ==",
                      "signatures": [
                        {
                          "keyid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
                          "sig": "3q2+7w=="
                        }
                      ]
                    }
                  },
                  "provenance": {
                    "certificate_url": "https://verify.masterdb.ai/v1/certificates/0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e",
                    "projection_version": "products/3",
                    "log_leaf": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
                    "source_line": "mdb-source/1 record=mdb_dq5jnqatnemnqj4g3xmgzgpoik origin=sha256:9f2c4e1a7b3d5f6e8a0c2b4d6f8e1a3c5b7d9f0e2a4c6b8d0f1e3a5c7b9d2f4e cert=sha256:3b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c served=2026-10-01T09:00:00.000Z verify=https://verify.masterdb.ai/v1/verify/mdb_dq5jnqatnemnqj4g3xmgzgpoik?origin=sha256%3A9f2c4e1a7b3d5f6e8a0c2b4d6f8e1a3c5b7d9f0e2a4c6b8d0f1e3a5c7b9d2f4e&cert=sha256%3A3b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c&served_at=2026-10-01T09%3A00%3A00.000Z"
                  },
                  "receipt": {
                    "payloadType": "application/vnd.masterdb.receipt.v3+json",
                    "payload": "eyJyZXRyaWV2YWxfaWQiOiJyXzAxSjhYIn0=",
                    "signatures": [
                      {
                        "keyid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                        "sig": "3q2+7w=="
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/ads/pool": {
      "post": {
        "operationId": "adsPool",
        "tags": [
          "Ads"
        ],
        "summary": "Get the ad pool for a context",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          }
        ],
        "x-mcp-tool": "ads_pool",
        "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",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdsPoolRequest"
              },
              "example": {
                "country": "US",
                "keywords": [
                  "running shoes",
                  "trail running"
                ],
                "formats": [
                  "card",
                  "compact"
                ],
                "sort_by": "net_price:desc",
                "max_per_campaign": 2,
                "size": 5,
                "session_ref": "9f1c2e7a-conv"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The pool — possibly empty when there are genuinely no payable ads.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdsPoolResponse"
                },
                "example": {
                  "retrieval_id": "r_01J8XK2Q7S",
                  "ads": [
                    {
                      "ad_id": "ad_lisanb2yutfpdoaecdreat",
                      "campaign_id": "cmp_7f6a5b4c",
                      "business_uuid": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e",
                      "label": "Ad",
                      "formats": [
                        "card",
                        "compact"
                      ],
                      "creative": {
                        "headline": "Ridge Trail Runner — 20% off",
                        "description": "Grippy, light, built for wet trails.",
                        "cta": "Shop Now",
                        "destination_url": "https://ridge.example/trail-runner",
                        "display_domain": "ridge.example",
                        "image_square_url": "https://img.masterdb.ai/creatives/ab12.webp?t=2d9f8e5a-4b6c-4e3d-9f0a-9b8c7d6e5f4a.rt_1&Expires=1790857200&KeyName=creatives-production&Signature=x",
                        "image_landscape_url": "https://img.masterdb.ai/creatives/cd34.webp?t=2d9f8e5a-4b6c-4e3d-9f0a-9b8c7d6e5f4a.rt_1&Expires=1790857200&KeyName=creatives-production&Signature=y"
                      },
                      "net_price": {
                        "amount": "4.20",
                        "currency": "USD",
                        "basis": "cpm"
                      },
                      "adl_origin_seal": {
                        "payloadType": "application/vnd.masterdb.seal.v2+json",
                        "payload": "eyJ2IjoyfQ==",
                        "signatures": [
                          {
                            "keyid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
                            "sig": "3q2+7w=="
                          }
                        ]
                      },
                      "record_base64": "eyJzY2hlbWEiOiJtYXN0ZXJkYi9hZHMvMSJ9",
                      "row": {
                        "id": "ad_lisanb2yutfpdoaecdreat",
                        "record_id": "ad_lisanb2yutfpdoaecdreat",
                        "business_uuid": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e",
                        "type": "ads",
                        "countries": [
                          "US"
                        ],
                        "published_at": 1790845231,
                        "campaign_id": "cmp_7f6a5b4c",
                        "headline": "Ridge Trail Runner — 20% off",
                        "cta_text": "Shop Now",
                        "destination_url": "https://ridge.example/trail-runner",
                        "display_domain": "ridge.example",
                        "adl_dest": "https://ridge.example/trail-runner",
                        "adl_creative": [
                          "sha256:9f2c5b1e0d4a3c7b6e8f1a2d3c4b5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d"
                        ],
                        "adl_origin_seal": "{\"payloadType\":\"application/vnd.masterdb.seal.v2+json\",\"payload\":\"eyJ2IjoyfQ==\",\"signatures\":[{\"keyid\":\"kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k\",\"sig\":\"3q2+7w==\"}]}",
                        "adl_origin": "sha256:4b1e8f3a2c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f",
                        "adl_proj": "sha256:7d1c9e2b4a6f8d0c3e5b7a9f1d3c5e7b9a1c3e5f7d9b1a3c5e7f9d1b3a5c7e9f",
                        "ai_policy_version": 2,
                        "adl_key_id": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                        "adl_row_sig": "3q2-7w",
                        "ai_policy_bits": {
                          "ai_policy_version": 2,
                          "ai_policy_schema": 2,
                          "use": 79,
                          "action": 35,
                          "blocked": 0
                        }
                      },
                      "ai_policy": {
                        "version": 2,
                        "record_base64": "eyJzY2hlbWEiOiJtYXN0ZXJkYi9haV9wb2xpY3kvMSJ9",
                        "seal": {
                          "payloadType": "application/vnd.masterdb.seal.v2+json",
                          "payload": "eyJ2IjoyfQ==",
                          "signatures": [
                            {
                              "keyid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
                              "sig": "3q2+7w=="
                            }
                          ]
                        }
                      },
                      "render_token": {
                        "payloadType": "application/vnd.masterdb.render.v1+json",
                        "payload": "eyJ0b2tlbl9pZCI6InJ0XzEifQ==",
                        "signatures": [
                          {
                            "keyid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                            "sig": "3q2+7w=="
                          }
                        ]
                      }
                    }
                  ],
                  "receipt": {
                    "payloadType": "application/vnd.masterdb.receipt.v3+json",
                    "payload": "eyJyZXRyaWV2YWxfaWQiOiJyXzAxSjhYSzJRN1MifQ==",
                    "signatures": [
                      {
                        "keyid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                        "sig": "3q2+7w=="
                      }
                    ]
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/ads/render": {
      "post": {
        "operationId": "adsRender",
        "tags": [
          "Ads"
        ],
        "summary": "Confirm a render",
        "x-mcp-tool": "ads_render",
        "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",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdsRenderRequest"
              },
              "example": {
                "render_token": {
                  "payloadType": "application/vnd.masterdb.render.v1+json",
                  "payload": "eyJ0b2tlbl9pZCI6InJ0XzEifQ==",
                  "signatures": [
                    {
                      "keyid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                      "sig": "3q2+7w=="
                    }
                  ]
                },
                "format": "card",
                "session_ref": "9f1c2e7a-conv"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Confirmation"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/ads/click": {
      "post": {
        "operationId": "adsClick",
        "tags": [
          "Ads"
        ],
        "summary": "Confirm a click",
        "x-mcp-tool": "ads_click",
        "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",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdsClickRequest"
              },
              "example": {
                "click_token": {
                  "payloadType": "application/vnd.masterdb.click.v1+json",
                  "payload": "eyJ0b2tlbl9pZCI6ImN0XzEifQ==",
                  "signatures": [
                    {
                      "keyid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                      "sig": "3q2+7w=="
                    }
                  ]
                },
                "session_ref": "9f1c2e7a-conv"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Confirmation"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/receipts": {
      "get": {
        "operationId": "listReceipts",
        "tags": [
          "Receipts and usage"
        ],
        "summary": "List your own receipts",
        "x-mcp-tool": "receipts",
        "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",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          },
          {
            "$ref": "#/components/parameters/From"
          },
          {
            "$ref": "#/components/parameters/To"
          },
          {
            "name": "key_id",
            "in": "query",
            "required": false,
            "description": "Only receipts for requests signed by this key.",
            "schema": {
              "$ref": "#/components/schemas/KeyId"
            }
          },
          {
            "name": "ai_company_uuid",
            "in": "query",
            "required": false,
            "description": "Only receipts for this legal entity of your group.",
            "schema": {
              "$ref": "#/components/schemas/AiCompanyUuid"
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of receipts, oldest first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptList"
                },
                "example": {
                  "receipts": [
                    {
                      "retrieval_id": "r_01J8XK2Q7R",
                      "served_at": "2026-10-01T14:02:11.482Z",
                      "region": "us-east4",
                      "key_id": "L1BSyf0VsZoYxYTQE2NWgZhhPww06EQJ73k4cJoVnsI",
                      "ai_company_uuid": "1c8e7d4f-3a5b-4d2c-8e9f-8a7b6c5d4e3f",
                      "receipt": {
                        "payloadType": "application/vnd.masterdb.receipt.v3+json",
                        "payload": "eyJyZXRyaWV2YWxfaWQiOiJyXzAxSjhYIn0=",
                        "signatures": [
                          {
                            "keyid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                            "sig": "3q2+7w=="
                          }
                        ]
                      }
                    }
                  ],
                  "next_cursor": "eyJhZnRlciI6InJfMDFKOFhLMlE3UiJ9"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "operationId": "getUsage",
        "tags": [
          "Receipts and usage"
        ],
        "summary": "Read your usage",
        "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",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          },
          {
            "$ref": "#/components/parameters/From"
          },
          {
            "$ref": "#/components/parameters/To"
          }
        ],
        "responses": {
          "200": {
            "description": "The usage figures.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                },
                "example": {
                  "as_at": "2026-10-01T14:00:00.000Z",
                  "days": [
                    {
                      "date": "2026-09-30",
                      "key_id": "L1BSyf0VsZoYxYTQE2NWgZhhPww06EQJ73k4cJoVnsI",
                      "ai_company_uuid": "1c8e7d4f-3a5b-4d2c-8e9f-8a7b6c5d4e3f",
                      "collection": "products",
                      "searches": 18231,
                      "fetches": 4410,
                      "billable": 21007
                    }
                  ],
                  "tiers": [
                    {
                      "tier": 1,
                      "from_queries": 0,
                      "to_queries": 100000,
                      "consumed": 21007
                    }
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/terms": {
      "get": {
        "operationId": "getTerms",
        "tags": [
          "Terms"
        ],
        "summary": "Read the Terms in force",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          }
        ],
        "x-mcp-tool": "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",
        "responses": {
          "200": {
            "$ref": "#/components/responses/Terms"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/v1/terms/{version}": {
      "get": {
        "operationId": "getTermsVersion",
        "tags": [
          "Terms"
        ],
        "summary": "Read a past version of the Terms",
        "x-mcp-tool": "terms",
        "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",
        "parameters": [
          {
            "$ref": "#/components/parameters/SandboxKey"
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 3
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Terms"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "mdbRequestSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "Signature",
        "description": "Every request is signed with RFC 9421 HTTP Message Signatures by a key the caller\nregistered; there is no bearer token. Covered components: `@method`,\n`@authority`, `@path`, `@query` when there is a query string, and `content-digest`\n(RFC 9530, sha-256) when there is a body. Signature parameters: `created`, `expires`\n(at most 300 s after `created`), `nonce` (single use per key within the window),\n`keyid` (the RFC 7638 thumbprint of the public key) and `tag`. The value in a\nsecurity requirement is the `tag` the operation accepts: `mdb-retrieval` for an AI\ncompany's retrieval key, `mdb-push` for a business's integration key under a\npublishing mandate, `mdb-business-read` for a business's reads of its own\ndata — catalogue read-back, push attempts, analytics — authorised by ownership of a\nregistered integration key alone, no mandate (a mandate authorises\npublishing, not reading). Identity comes only from the key; any identifier in a\nbody, query string or header is ignored. The SDKs sign for you.\n"
      }
    },
    "responses": {
      "SearchResults": {
        "description": "At most 50 rows and a signed receipt.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SearchResponse"
            },
            "example": {
              "retrieval_id": "r_01J8XK2Q7R",
              "collection": "products",
              "country": "US",
              "rows": [
                {
                  "record_id": "mdb_dq5jnqatnemnqj4g3xmgzgpoik",
                  "business_uuid": "0b7d6c3e-2f4a-4c1b-9d8e-7f6a5b4c3d2e",
                  "type": "products",
                  "published_at": 1790669700,
                  "product_name": "Ridge Trail Runner",
                  "price_US": 129,
                  "price_currency_US": "USD",
                  "price_IE": 119,
                  "price_currency_IE": "EUR",
                  "product_url": "https://ridge.example/trail-runner",
                  "adl_origin": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
                  "adl_origin_cert": "cert_0b7d6c3e_3",
                  "adl_proj": "products/3",
                  "adl_row_sig": "3q2+7w==",
                  "adl_key_id": "arnx6499M4j0-dWG9m6Z_VQIDfLERvDlhmiwnAihbdA",
                  "ai_policy_version": 4,
                  "ai_policy_bits": {
                    "ai_policy_version": 4,
                    "ai_policy_schema": 2,
                    "use": 79,
                    "action": 51,
                    "blocked": 130
                  }
                }
              ],
              "receipt": {
                "payloadType": "application/vnd.masterdb.receipt.v3+json",
                "payload": "eyJyZXRyaWV2YWxfaWQiOiJyXzAxSjhYIn0=",
                "signatures": [
                  {
                    "keyid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                    "sig": "3q2+7w=="
                  }
                ]
              }
            }
          }
        }
      },
      "Confirmation": {
        "description": "The verdict. A refusal that is a normal outcome (a late render, an empty budget) is a 200 with `accepted false` and a reason, recorded and never billed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Confirmation"
            },
            "example": {
              "accepted": true,
              "click_token": {
                "payloadType": "application/vnd.masterdb.click.v1+json",
                "payload": "eyJ0b2tlbl9pZCI6ImN0XzEifQ==",
                "signatures": [
                  {
                    "keyid": "AV9-a8Wur0g3JAieklLME7UJUaa2lBJSJ2XP9NeAMG4",
                    "sig": "3q2+7w=="
                  }
                ]
              }
            }
          }
        }
      },
      "Terms": {
        "description": "One version of the AI-company Terms.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/ETag"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/TermsDocument"
            },
            "example": {
              "version": 3,
              "effective_from": "2026-10-01T00:00:00.000Z",
              "sha256": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
              "text": "MasterDB AI-company Terms, version 3. …"
            }
          }
        }
      },
      "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"
            }
          }
        }
      }
    },
    "schemas": {
      "AdsPoolRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "country",
          "keywords",
          "formats",
          "sort_by",
          "session_ref"
        ],
        "properties": {
          "country": {
            "$ref": "#/components/schemas/Country"
          },
          "subdivision": {
            "type": "string",
            "description": "ISO 3166-2 subdivision, when you know it.",
            "pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$"
          },
          "keywords": {
            "type": "array",
            "description": "Subject terms, matched exactly against the ads' keywords. Never the question, never a user or conversation id.",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            }
          },
          "formats": {
            "type": "array",
            "description": "The render formats you can show.",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/RenderFormat"
            }
          },
          "sort_by": {
            "type": "string",
            "description": "Your order for the candidates — MasterDB never supplies one. Up to three\ncomma-separated keys from the allow-list, each `:asc` or `:desc`:\n`net_price` (what you would earn, per thousand renders or per click),\n`published_at`, `keyword_matches` (how many of your keywords the ad names) and\n`random` (seeded by this pool's `retrieval_id`).\n",
            "pattern": "^(?:net_price|published_at|keyword_matches|random):(?:asc|desc)(?:,(?:net_price|published_at|keyword_matches|random):(?:asc|desc)){0,2}$",
            "examples": [
              "net_price:desc",
              "keyword_matches:desc,net_price:desc"
            ],
            "minLength": 1,
            "maxLength": 200
          },
          "max_per_campaign": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "At most this many ads from one campaign in the pool."
          },
          "size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "How many ads you want; at most 20."
          },
          "session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Your opaque reference for the conversation, used only for repeat limits and fraud patterns; HMACed on arrival, kept 24 hours, never shown to a business."
          }
        }
      },
      "NetPrice": {
        "type": "object",
        "description": "What you earn for a render or click of this ad — net only (A1). Gross never leaves MasterDB.",
        "required": [
          "amount",
          "currency",
          "basis"
        ],
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/Money"
          },
          "currency": {
            "const": "USD"
          },
          "basis": {
            "type": "string",
            "enum": [
              "cpm",
              "cpc"
            ]
          }
        }
      },
      "AdCreative": {
        "type": "object",
        "required": [
          "headline",
          "cta",
          "destination_url",
          "display_domain"
        ],
        "properties": {
          "headline": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "cta": {
            "type": "string"
          },
          "destination_url": {
            "type": "string",
            "format": "uri"
          },
          "deep_link_url": {
            "type": "string",
            "format": "uri",
            "description": "The advertiser's optional mobile application link (an https universal or app link), beside `destination_url`; present only when the ad carries one. Open it in place of the destination on a device that can; `display_domain` always describes the destination (ads contract Rule 32)."
          },
          "display_domain": {
            "type": "string"
          },
          "image_square_url": {
            "type": "string",
            "format": "uri",
            "description": "Signed link to the 1:1 image (the `compact` render)."
          },
          "image_landscape_url": {
            "type": "string",
            "format": "uri",
            "description": "Signed link to the 1.91:1 image (the `card` render)."
          }
        }
      },
      "PoolAd": {
        "type": "object",
        "description": "One ad, verifiable on its own: `record_base64`, `row` and `ai_policy` tie the\nadvertiser's seal to what `creative` shows. `creative` is for rendering: the sealed text\nwith `cta_text` as `cta`, and signed image links in place of the sealed image paths.\n",
        "required": [
          "ad_id",
          "campaign_id",
          "business_uuid",
          "creative",
          "net_price",
          "adl_origin_seal",
          "record_base64",
          "row",
          "ai_policy",
          "render_token"
        ],
        "properties": {
          "record_base64": {
            "type": "string",
            "format": "byte",
            "description": "The exact bytes the advertiser sealed (`masterdb/ads/1`), base64. `row.adl_origin` is their SHA-256; the seal is over them."
          },
          "row": {
            "$ref": "#/components/schemas/PoolAdRow"
          },
          "ai_policy": {
            "$ref": "#/components/schemas/PoolAiPolicy"
          },
          "ad_id": {
            "$ref": "#/components/schemas/RecordId"
          },
          "campaign_id": {
            "type": "string"
          },
          "business_uuid": {
            "$ref": "#/components/schemas/BusinessUuid"
          },
          "creative": {
            "$ref": "#/components/schemas/AdCreative"
          },
          "net_price": {
            "$ref": "#/components/schemas/NetPrice"
          },
          "label": {
            "type": "string",
            "description": "The label to show beside the item, one per type of paid item; `Ad` for an ad.",
            "enum": [
              "Ad",
              "Sponsored",
              "Promoted event",
              "Promoted vacancy",
              "Promoted update"
            ]
          },
          "formats": {
            "type": "array",
            "description": "The render formats this item offers among those you asked for (`compact` has the 1:1 image, `card` the 1.91:1).",
            "items": {
              "$ref": "#/components/schemas/RenderFormat"
            }
          },
          "adl_origin_seal": {
            "$ref": "#/components/schemas/SealEnvelope"
          },
          "render_token": {
            "$ref": "#/components/schemas/RenderTokenEnvelope"
          }
        }
      },
      "PoolAdRow": {
        "type": "object",
        "description": "The ad's index row exactly as projected and signed (projection `ads`, `GET\n/v1/projections/ads/{version}`), with the advertiser's `ai_policy_bits` stamped as on a\nsearch row (outside the signature; v3 lists it among its unsigned fields). Verify\n`adl_row_sig` as for any row (`verifyServedRow`); `adl_origin_seal` is the advertiser's\nseal as RFC 8785 text, `adl_dest` the sealed destination, `adl_creative` a hash per image.\n",
        "required": [
          "record_id",
          "business_uuid",
          "type",
          "adl_origin",
          "adl_proj",
          "adl_row_sig",
          "adl_key_id",
          "adl_origin_seal",
          "adl_dest",
          "ai_policy_bits"
        ],
        "properties": {
          "record_id": {
            "$ref": "#/components/schemas/RecordId"
          },
          "business_uuid": {
            "$ref": "#/components/schemas/BusinessUuid"
          },
          "type": {
            "type": "string",
            "const": "ads"
          },
          "adl_origin": {
            "$ref": "#/components/schemas/Sha256"
          },
          "adl_proj": {
            "type": "string"
          },
          "adl_row_sig": {
            "type": "string"
          },
          "adl_key_id": {
            "$ref": "#/components/schemas/KeyId"
          },
          "adl_origin_seal": {
            "type": "string",
            "description": "The advertiser's seal (an envelope) as RFC 8785 text, inside the row signature."
          },
          "adl_dest": {
            "type": "string"
          },
          "adl_creative": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Sha256"
            }
          },
          "ai_policy_bits": {
            "$ref": "#/components/schemas/AiPolicyBits"
          }
        },
        "additionalProperties": true
      },
      "PoolAiPolicy": {
        "type": "object",
        "description": "The advertiser's sealed AI policy in force, as a fetch carries it (`SealedAiPolicy`),\nwith the record's bytes base64 (`record_base64`) because the item is re-serialised. Version\n0 with nulls: the advertiser has sealed none. It proves the `ai_policy_bits` on `row`.\n",
        "required": [
          "version",
          "record_base64",
          "seal"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "record_base64": {
            "type": [
              "string",
              "null"
            ],
            "format": "byte",
            "description": "The AI policy record's exact bytes, base64; null at version 0."
          },
          "seal": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RecordSeal"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "AdsPoolResponse": {
        "type": "object",
        "required": [
          "retrieval_id",
          "ads",
          "receipt"
        ],
        "properties": {
          "retrieval_id": {
            "type": "string",
            "pattern": "^r_[A-Za-z0-9_-]{1,62}$",
            "description": "This pool's id; the seed of the `random` sort, and the receipt's `retrieval_id`."
          },
          "receipt": {
            "$ref": "#/components/schemas/ReceiptEnvelope",
            "description": "MasterDB's signed statement of the ads served."
          },
          "ads": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/PoolAd"
            }
          }
        }
      },
      "AdsRenderRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "Either `render_token` (an ad from the pool) or `retrieval_id`, `record_id` and `receipt` (a sponsored or promoted row from a search, with the search's receipt).",
        "required": [
          "format",
          "session_ref"
        ],
        "properties": {
          "receipt": {
            "$ref": "#/components/schemas/ReceiptEnvelope",
            "description": "The receipt of the search the row was served in, exactly as received; its row must say `sponsored`."
          },
          "render_token": {
            "$ref": "#/components/schemas/RenderTokenEnvelope"
          },
          "retrieval_id": {
            "type": "string"
          },
          "record_id": {
            "$ref": "#/components/schemas/RecordId"
          },
          "format": {
            "$ref": "#/components/schemas/RenderFormat"
          },
          "session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        },
        "oneOf": [
          {
            "required": [
              "render_token"
            ]
          },
          {
            "required": [
              "retrieval_id",
              "record_id",
              "receipt"
            ]
          }
        ]
      },
      "AdsClickRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "click_token",
          "session_ref"
        ],
        "properties": {
          "click_token": {
            "$ref": "#/components/schemas/ClickTokenEnvelope"
          },
          "session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "Confirmation": {
        "type": "object",
        "required": [
          "accepted"
        ],
        "properties": {
          "accepted": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "enum": [
              "window_expired",
              "budget_exhausted",
              "token_reused"
            ]
          },
          "label": {
            "type": "string",
            "description": "For a sponsored or promoted row, the label to show beside it.",
            "enum": [
              "Sponsored",
              "Promoted event",
              "Promoted vacancy",
              "Promoted update"
            ]
          },
          "click_token": {
            "$ref": "#/components/schemas/ClickTokenEnvelope"
          }
        }
      },
      "ReceiptList": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Page"
          },
          {
            "type": "object",
            "required": [
              "receipts"
            ],
            "properties": {
              "receipts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "retrieval_id",
                    "served_at",
                    "region",
                    "key_id",
                    "ai_company_uuid",
                    "receipt"
                  ],
                  "properties": {
                    "retrieval_id": {
                      "type": "string"
                    },
                    "served_at": {
                      "$ref": "#/components/schemas/Timestamp"
                    },
                    "region": {
                      "type": "string"
                    },
                    "key_id": {
                      "$ref": "#/components/schemas/KeyId"
                    },
                    "ai_company_uuid": {
                      "$ref": "#/components/schemas/AiCompanyUuid"
                    },
                    "receipt": {
                      "$ref": "#/components/schemas/ReceiptEnvelope"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "BandedCount": {
        "description": "A count; below 50 it is shown only as the band `<50`.",
        "oneOf": [
          {
            "type": "integer",
            "minimum": 50
          },
          {
            "const": "<50"
          }
        ]
      },
      "Usage": {
        "type": "object",
        "required": [
          "as_at",
          "days"
        ],
        "properties": {
          "as_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "days": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "date",
                "searches",
                "fetches",
                "billable"
              ],
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "key_id": {
                  "$ref": "#/components/schemas/KeyId"
                },
                "ai_company_uuid": {
                  "$ref": "#/components/schemas/AiCompanyUuid"
                },
                "collection": {
                  "$ref": "#/components/schemas/RecordType"
                },
                "searches": {
                  "$ref": "#/components/schemas/BandedCount"
                },
                "fetches": {
                  "$ref": "#/components/schemas/BandedCount"
                },
                "billable": {
                  "$ref": "#/components/schemas/BandedCount"
                }
              }
            }
          },
          "tiers": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "tier",
                "consumed"
              ],
              "properties": {
                "tier": {
                  "type": "integer"
                },
                "from_queries": {
                  "type": "integer"
                },
                "to_queries": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "consumed": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "TermsDocument": {
        "type": "object",
        "required": [
          "version",
          "effective_from",
          "sha256",
          "text"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "effective_from": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "sha256": {
            "$ref": "#/components/schemas/Sha256"
          },
          "text": {
            "type": "string",
            "description": "The Terms, as Markdown."
          }
        }
      },
      "CountryClause": {
        "description": "The one country the search is for: exactly one per filter (`filter_required` otherwise). It selects the rows published for that country and the per-country fields (`price_amount` becomes that country's price).",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "country"
        ],
        "properties": {
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2."
          }
        }
      },
      "StringValue": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256,
        "description": "Plain text: no leading or trailing space, no control characters, no backtick."
      },
      "ProductsLanguageOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "ProductsLanguageClause": {
        "description": "`language` — string; operators: eq, in. `{\"language\": v}` is shorthand for `{\"language\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "language"
        ],
        "properties": {
          "language": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/ProductsLanguageOperators"
              }
            ]
          }
        }
      },
      "ProductsTagsOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "ProductsTagsClause": {
        "description": "`tags` — string; operators: eq, in. `{\"tags\": v}` is shorthand for `{\"tags\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tags"
        ],
        "properties": {
          "tags": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/ProductsTagsOperators"
              }
            ]
          }
        }
      },
      "ProductsBrandOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "ProductsBrandClause": {
        "description": "`brand` — string; operators: eq, ne, in, nin. `{\"brand\": v}` is shorthand for `{\"brand\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "brand"
        ],
        "properties": {
          "brand": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/ProductsBrandOperators"
              }
            ]
          }
        }
      },
      "ProductsVerticalOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "ProductsVerticalClause": {
        "description": "`vertical` — string; operators: eq, ne, in, nin. `{\"vertical\": v}` is shorthand for `{\"vertical\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "vertical"
        ],
        "properties": {
          "vertical": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/ProductsVerticalOperators"
              }
            ]
          }
        }
      },
      "ProductsCategoryOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "ProductsCategoryClause": {
        "description": "`category` — string; operators: eq, ne, in, nin. `{\"category\": v}` is shorthand for `{\"category\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "category"
        ],
        "properties": {
          "category": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/ProductsCategoryOperators"
              }
            ]
          }
        }
      },
      "ProductsChannelOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "ProductsChannelClause": {
        "description": "`channel` — string; operators: eq, ne, in, nin. `{\"channel\": v}` is shorthand for `{\"channel\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/ProductsChannelOperators"
              }
            ]
          }
        }
      },
      "ProductsAvailabilityOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "ProductsAvailabilityClause": {
        "description": "`availability` — string; operators: eq, ne, in, nin. `{\"availability\": v}` is shorthand for `{\"availability\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "availability"
        ],
        "properties": {
          "availability": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/ProductsAvailabilityOperators"
              }
            ]
          }
        }
      },
      "BoolValue": {
        "type": "boolean"
      },
      "ProductsOnSaleOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/BoolValue"
          }
        }
      },
      "ProductsOnSaleClause": {
        "description": "`on_sale` — bool; operators: eq. `{\"on_sale\": v}` is shorthand for `{\"on_sale\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "on_sale"
        ],
        "properties": {
          "on_sale": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BoolValue"
              },
              {
                "$ref": "#/components/schemas/ProductsOnSaleOperators"
              }
            ]
          }
        }
      },
      "MoneyValue": {
        "description": "A decimal quantity: a decimal string (\"150.00\"), or a JSON number written without an exponent.",
        "type": [
          "string",
          "number"
        ],
        "pattern": "^(?:0|[1-9][0-9]{0,14})(?:\\.[0-9]{1,6})?$",
        "minimum": 0,
        "maximum": 999999999999999
      },
      "ProductsPriceAmountOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "lt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "lte": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gte": {
            "$ref": "#/components/schemas/MoneyValue"
          }
        }
      },
      "ProductsPriceAmountClause": {
        "description": "`price_amount` — money; operators: eq, lt, lte, gt, gte; also a sort key; applies to the searched country's value (indexed as `price_{CC}`). `{\"price_amount\": v}` is shorthand for `{\"price_amount\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "price_amount"
        ],
        "properties": {
          "price_amount": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MoneyValue"
              },
              {
                "$ref": "#/components/schemas/ProductsPriceAmountOperators"
              }
            ]
          }
        }
      },
      "CurrencyValue": {
        "type": "string",
        "pattern": "^[A-Z]{3}$",
        "description": "ISO 4217 code."
      },
      "ProductsPriceCurrencyOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/CurrencyValue"
          },
          "ne": {
            "$ref": "#/components/schemas/CurrencyValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/CurrencyValue"
            }
          }
        }
      },
      "ProductsPriceCurrencyClause": {
        "description": "`price_currency` — currency; operators: eq, ne, in; applies to the searched country's value (indexed as `price_currency_{CC}`). `{\"price_currency\": v}` is shorthand for `{\"price_currency\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "price_currency"
        ],
        "properties": {
          "price_currency": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CurrencyValue"
              },
              {
                "$ref": "#/components/schemas/ProductsPriceCurrencyOperators"
              }
            ]
          }
        }
      },
      "ProductsGtinOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "ProductsGtinClause": {
        "description": "`gtin` — string; operators: eq, in. `{\"gtin\": v}` is shorthand for `{\"gtin\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "gtin"
        ],
        "properties": {
          "gtin": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/ProductsGtinOperators"
              }
            ]
          }
        }
      },
      "ProductsSponsoredOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/BoolValue"
          }
        }
      },
      "ProductsSponsoredClause": {
        "description": "`sponsored` — bool; operators: eq. `{\"sponsored\": v}` is shorthand for `{\"sponsored\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sponsored"
        ],
        "properties": {
          "sponsored": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BoolValue"
              },
              {
                "$ref": "#/components/schemas/ProductsSponsoredOperators"
              }
            ]
          }
        }
      },
      "TimestampValue": {
        "description": "RFC 3339 UTC (\"2026-10-01T00:00:00Z\") or Unix seconds.",
        "type": [
          "string",
          "integer"
        ],
        "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$",
        "minimum": 0
      },
      "ProductsPublishedAtOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "ProductsPublishedAtClause": {
        "description": "`published_at` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "published_at"
        ],
        "properties": {
          "published_at": {
            "$ref": "#/components/schemas/ProductsPublishedAtOperators"
          }
        }
      },
      "ProductsFilterClause": {
        "description": "One condition on a `products` field: an object with exactly one member, the field name.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/CountryClause"
          },
          {
            "$ref": "#/components/schemas/ProductsLanguageClause"
          },
          {
            "$ref": "#/components/schemas/ProductsTagsClause"
          },
          {
            "$ref": "#/components/schemas/ProductsBrandClause"
          },
          {
            "$ref": "#/components/schemas/ProductsVerticalClause"
          },
          {
            "$ref": "#/components/schemas/ProductsCategoryClause"
          },
          {
            "$ref": "#/components/schemas/ProductsChannelClause"
          },
          {
            "$ref": "#/components/schemas/ProductsAvailabilityClause"
          },
          {
            "$ref": "#/components/schemas/ProductsOnSaleClause"
          },
          {
            "$ref": "#/components/schemas/ProductsPriceAmountClause"
          },
          {
            "$ref": "#/components/schemas/ProductsPriceCurrencyClause"
          },
          {
            "$ref": "#/components/schemas/ProductsGtinClause"
          },
          {
            "$ref": "#/components/schemas/ProductsSponsoredClause"
          },
          {
            "$ref": "#/components/schemas/ProductsPublishedAtClause"
          }
        ]
      },
      "ProductsFilter": {
        "description": "The structured filter for `products`: every clause must hold. Exactly one clause names the country. Only the fields below exist; anything else is `unknown_field`, and an operator a field does not list is `operator_not_allowed`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "all"
        ],
        "properties": {
          "all": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/ProductsFilterClause"
            },
            "contains": {
              "$ref": "#/components/schemas/CountryClause"
            },
            "minContains": 1,
            "maxContains": 1
          }
        }
      },
      "ProductsSortBy": {
        "type": "string",
        "description": "Mandatory: MasterDB never supplies an order. `field:asc|desc`, up to 3, comma-separated, from: `_text_match`, `price_amount`, `published_at`. For relevance order write `_text_match:desc`.",
        "pattern": "^(?:_text_match|price_amount|published_at):(?:asc|desc)(?:,(?:_text_match|price_amount|published_at):(?:asc|desc)){0,2}$"
      },
      "ProductsCollectionSearchRequest": {
        "description": "A search of `products` through `POST /v1/search`: the ProductsSearchRequest with `collection` required.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collection",
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "products",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `products` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "enum": [
                "product_name",
                "short_description",
                "tags",
                "brand"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/ProductsFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/ProductsSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "BusinessFilesLanguageOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "BusinessFilesLanguageClause": {
        "description": "`language` — string; operators: eq, in. `{\"language\": v}` is shorthand for `{\"language\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "language"
        ],
        "properties": {
          "language": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/BusinessFilesLanguageOperators"
              }
            ]
          }
        }
      },
      "BusinessFilesHasLocationsOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/BoolValue"
          }
        }
      },
      "BusinessFilesHasLocationsClause": {
        "description": "`has_locations` — bool; operators: eq. `{\"has_locations\": v}` is shorthand for `{\"has_locations\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "has_locations"
        ],
        "properties": {
          "has_locations": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BoolValue"
              },
              {
                "$ref": "#/components/schemas/BusinessFilesHasLocationsOperators"
              }
            ]
          }
        }
      },
      "GeoNearOperator": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "near"
        ],
        "properties": {
          "near": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "lat",
              "lng",
              "radius_km"
            ],
            "properties": {
              "lat": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "lng": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              },
              "radius_km": {
                "type": "number",
                "minimum": 0.001,
                "maximum": 1000
              }
            }
          }
        }
      },
      "BusinessFilesLocationGeoClause": {
        "description": "`location_geo` — geopoint; operators: near.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "location_geo"
        ],
        "properties": {
          "location_geo": {
            "$ref": "#/components/schemas/GeoNearOperator"
          }
        }
      },
      "BusinessFilesCitiesOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "BusinessFilesCitiesClause": {
        "description": "`cities` — string; operators: eq, in. `{\"cities\": v}` is shorthand for `{\"cities\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "cities"
        ],
        "properties": {
          "cities": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/BusinessFilesCitiesOperators"
              }
            ]
          }
        }
      },
      "BusinessFilesDeliveryOptionsOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "BusinessFilesDeliveryOptionsClause": {
        "description": "`delivery.options` — string; operators: eq, in. `{\"delivery.options\": v}` is shorthand for `{\"delivery.options\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "delivery.options"
        ],
        "properties": {
          "delivery.options": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/BusinessFilesDeliveryOptionsOperators"
              }
            ]
          }
        }
      },
      "BusinessFilesShipsInternationallyOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/BoolValue"
          }
        }
      },
      "BusinessFilesShipsInternationallyClause": {
        "description": "`ships_internationally` — bool; operators: eq. `{\"ships_internationally\": v}` is shorthand for `{\"ships_internationally\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ships_internationally"
        ],
        "properties": {
          "ships_internationally": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BoolValue"
              },
              {
                "$ref": "#/components/schemas/BusinessFilesShipsInternationallyOperators"
              }
            ]
          }
        }
      },
      "BusinessFilesPaymentMethodsOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "BusinessFilesPaymentMethodsClause": {
        "description": "`payment.methods` — string; operators: eq, in. `{\"payment.methods\": v}` is shorthand for `{\"payment.methods\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payment.methods"
        ],
        "properties": {
          "payment.methods": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/BusinessFilesPaymentMethodsOperators"
              }
            ]
          }
        }
      },
      "BusinessFilesHasBookingOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/BoolValue"
          }
        }
      },
      "BusinessFilesHasBookingClause": {
        "description": "`has_booking` — bool; operators: eq; always false on every row, so has_booking: true matches nothing. `{\"has_booking\": v}` is shorthand for `{\"has_booking\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "has_booking"
        ],
        "properties": {
          "has_booking": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BoolValue"
              },
              {
                "$ref": "#/components/schemas/BusinessFilesHasBookingOperators"
              }
            ]
          }
        }
      },
      "IntValue": {
        "type": "integer"
      },
      "BusinessFilesYearEstablishedOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/IntValue"
          },
          "lt": {
            "$ref": "#/components/schemas/IntValue"
          },
          "lte": {
            "$ref": "#/components/schemas/IntValue"
          },
          "gt": {
            "$ref": "#/components/schemas/IntValue"
          },
          "gte": {
            "$ref": "#/components/schemas/IntValue"
          }
        }
      },
      "BusinessFilesYearEstablishedClause": {
        "description": "`year_established` — int; operators: eq, lt, lte, gt, gte; also a sort key. `{\"year_established\": v}` is shorthand for `{\"year_established\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "year_established"
        ],
        "properties": {
          "year_established": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/IntValue"
              },
              {
                "$ref": "#/components/schemas/BusinessFilesYearEstablishedOperators"
              }
            ]
          }
        }
      },
      "BusinessFilesPublishedAtOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "BusinessFilesPublishedAtClause": {
        "description": "`published_at` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "published_at"
        ],
        "properties": {
          "published_at": {
            "$ref": "#/components/schemas/BusinessFilesPublishedAtOperators"
          }
        }
      },
      "BusinessFilesFilterClause": {
        "description": "One condition on a `business_files` field: an object with exactly one member, the field name.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/CountryClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesLanguageClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesHasLocationsClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesLocationGeoClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesCitiesClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesDeliveryOptionsClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesShipsInternationallyClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesPaymentMethodsClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesHasBookingClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesYearEstablishedClause"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesPublishedAtClause"
          }
        ]
      },
      "BusinessFilesFilter": {
        "description": "The structured filter for `business_files`: every clause must hold. Exactly one clause names the country. Only the fields below exist; anything else is `unknown_field`, and an operator a field does not list is `operator_not_allowed`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "all"
        ],
        "properties": {
          "all": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/BusinessFilesFilterClause"
            },
            "contains": {
              "$ref": "#/components/schemas/CountryClause"
            },
            "minContains": 1,
            "maxContains": 1
          }
        }
      },
      "BusinessFilesSortBy": {
        "type": "string",
        "description": "Mandatory: MasterDB never supplies an order. `field:asc|desc`, up to 3, comma-separated, from: `_text_match`, `year_established`, `published_at`. For relevance order write `_text_match:desc`.",
        "pattern": "^(?:_text_match|year_established|published_at):(?:asc|desc)(?:,(?:_text_match|year_established|published_at):(?:asc|desc)){0,2}$"
      },
      "BusinessFilesCollectionSearchRequest": {
        "description": "A search of `business_files` through `POST /v1/search`: the BusinessFilesSearchRequest with `collection` required.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collection",
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "business_files",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `business_files` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "enum": [
                "description",
                "brands_owned.name",
                "brands_sold.name",
                "markets_served"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/BusinessFilesFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/BusinessFilesSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "EventsLanguageOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "EventsLanguageClause": {
        "description": "`language` — string; operators: eq, in. `{\"language\": v}` is shorthand for `{\"language\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "language"
        ],
        "properties": {
          "language": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/EventsLanguageOperators"
              }
            ]
          }
        }
      },
      "EventsRegionOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "EventsRegionClause": {
        "description": "`region` — string; operators: eq, in. `{\"region\": v}` is shorthand for `{\"region\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "region"
        ],
        "properties": {
          "region": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/EventsRegionOperators"
              }
            ]
          }
        }
      },
      "EventsEventTypeOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "EventsEventTypeClause": {
        "description": "`event_type` — string; operators: eq, ne, in, nin. `{\"event_type\": v}` is shorthand for `{\"event_type\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "event_type"
        ],
        "properties": {
          "event_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/EventsEventTypeOperators"
              }
            ]
          }
        }
      },
      "EventsAttendanceModeOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "EventsAttendanceModeClause": {
        "description": "`attendance_mode` — string; operators: eq, ne, in. `{\"attendance_mode\": v}` is shorthand for `{\"attendance_mode\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "attendance_mode"
        ],
        "properties": {
          "attendance_mode": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/EventsAttendanceModeOperators"
              }
            ]
          }
        }
      },
      "EventsStartAtOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "EventsStartAtClause": {
        "description": "`start_at` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "start_at"
        ],
        "properties": {
          "start_at": {
            "$ref": "#/components/schemas/EventsStartAtOperators"
          }
        }
      },
      "EventsEndAtOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "EventsEndAtClause": {
        "description": "`end_at` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "end_at"
        ],
        "properties": {
          "end_at": {
            "$ref": "#/components/schemas/EventsEndAtOperators"
          }
        }
      },
      "EventsTimezoneOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "EventsTimezoneClause": {
        "description": "`timezone` — string; operators: eq, in. `{\"timezone\": v}` is shorthand for `{\"timezone\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "timezone"
        ],
        "properties": {
          "timezone": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/EventsTimezoneOperators"
              }
            ]
          }
        }
      },
      "EventsGeoClause": {
        "description": "`geo` — geopoint; operators: near.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "geo"
        ],
        "properties": {
          "geo": {
            "$ref": "#/components/schemas/GeoNearOperator"
          }
        }
      },
      "EventsCityOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "EventsCityClause": {
        "description": "`city` — string; operators: eq, in. `{\"city\": v}` is shorthand for `{\"city\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "city"
        ],
        "properties": {
          "city": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/EventsCityOperators"
              }
            ]
          }
        }
      },
      "EventsTicketedOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/BoolValue"
          }
        }
      },
      "EventsTicketedClause": {
        "description": "`ticketed` — bool; operators: eq. `{\"ticketed\": v}` is shorthand for `{\"ticketed\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ticketed"
        ],
        "properties": {
          "ticketed": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BoolValue"
              },
              {
                "$ref": "#/components/schemas/EventsTicketedOperators"
              }
            ]
          }
        }
      },
      "EventsPriceMinOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "lte": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gte": {
            "$ref": "#/components/schemas/MoneyValue"
          }
        }
      },
      "EventsPriceMinClause": {
        "description": "`price_min` — money; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "price_min"
        ],
        "properties": {
          "price_min": {
            "$ref": "#/components/schemas/EventsPriceMinOperators"
          }
        }
      },
      "EventsPriceMaxOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "lte": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gte": {
            "$ref": "#/components/schemas/MoneyValue"
          }
        }
      },
      "EventsPriceMaxClause": {
        "description": "`price_max` — money; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "price_max"
        ],
        "properties": {
          "price_max": {
            "$ref": "#/components/schemas/EventsPriceMaxOperators"
          }
        }
      },
      "EventsPriceCurrencyOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/CurrencyValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/CurrencyValue"
            }
          }
        }
      },
      "EventsPriceCurrencyClause": {
        "description": "`price_currency` — currency; operators: eq, in. `{\"price_currency\": v}` is shorthand for `{\"price_currency\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "price_currency"
        ],
        "properties": {
          "price_currency": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CurrencyValue"
              },
              {
                "$ref": "#/components/schemas/EventsPriceCurrencyOperators"
              }
            ]
          }
        }
      },
      "EventsAgeRestrictionOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "EventsAgeRestrictionClause": {
        "description": "`age_restriction` — string; operators: eq, ne, in. `{\"age_restriction\": v}` is shorthand for `{\"age_restriction\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "age_restriction"
        ],
        "properties": {
          "age_restriction": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/EventsAgeRestrictionOperators"
              }
            ]
          }
        }
      },
      "EventsPublishedAtOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "EventsPublishedAtClause": {
        "description": "`published_at` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "published_at"
        ],
        "properties": {
          "published_at": {
            "$ref": "#/components/schemas/EventsPublishedAtOperators"
          }
        }
      },
      "EventsFilterClause": {
        "description": "One condition on a `events` field: an object with exactly one member, the field name.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/CountryClause"
          },
          {
            "$ref": "#/components/schemas/EventsLanguageClause"
          },
          {
            "$ref": "#/components/schemas/EventsRegionClause"
          },
          {
            "$ref": "#/components/schemas/EventsEventTypeClause"
          },
          {
            "$ref": "#/components/schemas/EventsAttendanceModeClause"
          },
          {
            "$ref": "#/components/schemas/EventsStartAtClause"
          },
          {
            "$ref": "#/components/schemas/EventsEndAtClause"
          },
          {
            "$ref": "#/components/schemas/EventsTimezoneClause"
          },
          {
            "$ref": "#/components/schemas/EventsGeoClause"
          },
          {
            "$ref": "#/components/schemas/EventsCityClause"
          },
          {
            "$ref": "#/components/schemas/EventsTicketedClause"
          },
          {
            "$ref": "#/components/schemas/EventsPriceMinClause"
          },
          {
            "$ref": "#/components/schemas/EventsPriceMaxClause"
          },
          {
            "$ref": "#/components/schemas/EventsPriceCurrencyClause"
          },
          {
            "$ref": "#/components/schemas/EventsAgeRestrictionClause"
          },
          {
            "$ref": "#/components/schemas/EventsPublishedAtClause"
          }
        ]
      },
      "EventsFilter": {
        "description": "The structured filter for `events`: every clause must hold. Exactly one clause names the country. Only the fields below exist; anything else is `unknown_field`, and an operator a field does not list is `operator_not_allowed`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "all"
        ],
        "properties": {
          "all": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/EventsFilterClause"
            },
            "contains": {
              "$ref": "#/components/schemas/CountryClause"
            },
            "minContains": 1,
            "maxContains": 1
          }
        }
      },
      "EventsSortBy": {
        "type": "string",
        "description": "Mandatory: MasterDB never supplies an order. `field:asc|desc`, up to 3, comma-separated, from: `_text_match`, `start_at`, `end_at`, `price_min`, `price_max`, `published_at`. For relevance order write `_text_match:desc`.",
        "pattern": "^(?:_text_match|start_at|end_at|price_min|price_max|published_at):(?:asc|desc)(?:,(?:_text_match|start_at|end_at|price_min|price_max|published_at):(?:asc|desc)){0,2}$"
      },
      "EventsCollectionSearchRequest": {
        "description": "A search of `events` through `POST /v1/search`: the EventsSearchRequest with `collection` required.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collection",
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "events",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `events` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "enum": [
                "title",
                "description"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/EventsFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/EventsSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "JobsLanguageOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "JobsLanguageClause": {
        "description": "`language` — string; operators: eq, in. `{\"language\": v}` is shorthand for `{\"language\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "language"
        ],
        "properties": {
          "language": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/JobsLanguageOperators"
              }
            ]
          }
        }
      },
      "JobsSalaryDisclosedOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/BoolValue"
          }
        }
      },
      "JobsSalaryDisclosedClause": {
        "description": "`salary_disclosed` — bool; operators: eq. `{\"salary_disclosed\": v}` is shorthand for `{\"salary_disclosed\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "salary_disclosed"
        ],
        "properties": {
          "salary_disclosed": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BoolValue"
              },
              {
                "$ref": "#/components/schemas/JobsSalaryDisclosedOperators"
              }
            ]
          }
        }
      },
      "JobsEmploymentTypeOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "JobsEmploymentTypeClause": {
        "description": "`employment_type` — string; operators: eq, ne, in, nin. `{\"employment_type\": v}` is shorthand for `{\"employment_type\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "employment_type"
        ],
        "properties": {
          "employment_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/JobsEmploymentTypeOperators"
              }
            ]
          }
        }
      },
      "JobsCategoryOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "JobsCategoryClause": {
        "description": "`category` — string; operators: eq, ne, in, nin. `{\"category\": v}` is shorthand for `{\"category\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "category"
        ],
        "properties": {
          "category": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/JobsCategoryOperators"
              }
            ]
          }
        }
      },
      "JobsWorkArrangementOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "JobsWorkArrangementClause": {
        "description": "`work_arrangement` — string; operators: eq, ne, in. `{\"work_arrangement\": v}` is shorthand for `{\"work_arrangement\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "work_arrangement"
        ],
        "properties": {
          "work_arrangement": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/JobsWorkArrangementOperators"
              }
            ]
          }
        }
      },
      "JobsGeoClause": {
        "description": "`geo` — geopoint; operators: near.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "geo"
        ],
        "properties": {
          "geo": {
            "$ref": "#/components/schemas/GeoNearOperator"
          }
        }
      },
      "JobsCityOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "JobsCityClause": {
        "description": "`city` — string; operators: eq, in. `{\"city\": v}` is shorthand for `{\"city\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "city"
        ],
        "properties": {
          "city": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/JobsCityOperators"
              }
            ]
          }
        }
      },
      "JobsRegionOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "JobsRegionClause": {
        "description": "`region` — string; operators: eq, in. `{\"region\": v}` is shorthand for `{\"region\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "region"
        ],
        "properties": {
          "region": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/JobsRegionOperators"
              }
            ]
          }
        }
      },
      "JobsSalaryMinOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "lte": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gte": {
            "$ref": "#/components/schemas/MoneyValue"
          }
        }
      },
      "JobsSalaryMinClause": {
        "description": "`salary_min` — money; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "salary_min"
        ],
        "properties": {
          "salary_min": {
            "$ref": "#/components/schemas/JobsSalaryMinOperators"
          }
        }
      },
      "JobsSalaryMaxOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "lte": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gt": {
            "$ref": "#/components/schemas/MoneyValue"
          },
          "gte": {
            "$ref": "#/components/schemas/MoneyValue"
          }
        }
      },
      "JobsSalaryMaxClause": {
        "description": "`salary_max` — money; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "salary_max"
        ],
        "properties": {
          "salary_max": {
            "$ref": "#/components/schemas/JobsSalaryMaxOperators"
          }
        }
      },
      "JobsSalaryCurrencyOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/CurrencyValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/CurrencyValue"
            }
          }
        }
      },
      "JobsSalaryCurrencyClause": {
        "description": "`salary_currency` — currency; operators: eq, in. `{\"salary_currency\": v}` is shorthand for `{\"salary_currency\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "salary_currency"
        ],
        "properties": {
          "salary_currency": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CurrencyValue"
              },
              {
                "$ref": "#/components/schemas/JobsSalaryCurrencyOperators"
              }
            ]
          }
        }
      },
      "JobsSalaryPeriodOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "JobsSalaryPeriodClause": {
        "description": "`salary_period` — string; operators: eq, in. `{\"salary_period\": v}` is shorthand for `{\"salary_period\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "salary_period"
        ],
        "properties": {
          "salary_period": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/JobsSalaryPeriodOperators"
              }
            ]
          }
        }
      },
      "JobsClosingDateOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "JobsClosingDateClause": {
        "description": "`closing_date` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "closing_date"
        ],
        "properties": {
          "closing_date": {
            "$ref": "#/components/schemas/JobsClosingDateOperators"
          }
        }
      },
      "JobsPublishedAtOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "JobsPublishedAtClause": {
        "description": "`published_at` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "published_at"
        ],
        "properties": {
          "published_at": {
            "$ref": "#/components/schemas/JobsPublishedAtOperators"
          }
        }
      },
      "JobsFilterClause": {
        "description": "One condition on a `jobs` field: an object with exactly one member, the field name.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/CountryClause"
          },
          {
            "$ref": "#/components/schemas/JobsLanguageClause"
          },
          {
            "$ref": "#/components/schemas/JobsSalaryDisclosedClause"
          },
          {
            "$ref": "#/components/schemas/JobsEmploymentTypeClause"
          },
          {
            "$ref": "#/components/schemas/JobsCategoryClause"
          },
          {
            "$ref": "#/components/schemas/JobsWorkArrangementClause"
          },
          {
            "$ref": "#/components/schemas/JobsGeoClause"
          },
          {
            "$ref": "#/components/schemas/JobsCityClause"
          },
          {
            "$ref": "#/components/schemas/JobsRegionClause"
          },
          {
            "$ref": "#/components/schemas/JobsSalaryMinClause"
          },
          {
            "$ref": "#/components/schemas/JobsSalaryMaxClause"
          },
          {
            "$ref": "#/components/schemas/JobsSalaryCurrencyClause"
          },
          {
            "$ref": "#/components/schemas/JobsSalaryPeriodClause"
          },
          {
            "$ref": "#/components/schemas/JobsClosingDateClause"
          },
          {
            "$ref": "#/components/schemas/JobsPublishedAtClause"
          }
        ]
      },
      "JobsFilter": {
        "description": "The structured filter for `jobs`: every clause must hold. Exactly one clause names the country. Only the fields below exist; anything else is `unknown_field`, and an operator a field does not list is `operator_not_allowed`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "all"
        ],
        "properties": {
          "all": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/JobsFilterClause"
            },
            "contains": {
              "$ref": "#/components/schemas/CountryClause"
            },
            "minContains": 1,
            "maxContains": 1
          }
        }
      },
      "JobsSortBy": {
        "type": "string",
        "description": "Mandatory: MasterDB never supplies an order. `field:asc|desc`, up to 3, comma-separated, from: `_text_match`, `salary_min`, `salary_max`, `closing_date`, `published_at`. For relevance order write `_text_match:desc`.",
        "pattern": "^(?:_text_match|salary_min|salary_max|closing_date|published_at):(?:asc|desc)(?:,(?:_text_match|salary_min|salary_max|closing_date|published_at):(?:asc|desc)){0,2}$"
      },
      "JobsCollectionSearchRequest": {
        "description": "A search of `jobs` through `POST /v1/search`: the JobsSearchRequest with `collection` required.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collection",
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "jobs",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `jobs` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "enum": [
                "title",
                "description"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/JobsFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/JobsSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "UpdatesLanguageOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "UpdatesLanguageClause": {
        "description": "`language` — string; operators: eq, in. `{\"language\": v}` is shorthand for `{\"language\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "language"
        ],
        "properties": {
          "language": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/UpdatesLanguageOperators"
              }
            ]
          }
        }
      },
      "UpdatesUpdateTypeOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "eq": {
            "$ref": "#/components/schemas/StringValue"
          },
          "ne": {
            "$ref": "#/components/schemas/StringValue"
          },
          "in": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          },
          "nin": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/StringValue"
            }
          }
        }
      },
      "UpdatesUpdateTypeClause": {
        "description": "`update_type` — string; operators: eq, ne, in, nin. `{\"update_type\": v}` is shorthand for `{\"update_type\": {\"eq\": v}}`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "update_type"
        ],
        "properties": {
          "update_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StringValue"
              },
              {
                "$ref": "#/components/schemas/UpdatesUpdateTypeOperators"
              }
            ]
          }
        }
      },
      "UpdatesPublishedAtOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "UpdatesPublishedAtClause": {
        "description": "`published_at` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "published_at"
        ],
        "properties": {
          "published_at": {
            "$ref": "#/components/schemas/UpdatesPublishedAtOperators"
          }
        }
      },
      "UpdatesRelevantUntilOperators": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "lt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "lte": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gt": {
            "$ref": "#/components/schemas/TimestampValue"
          },
          "gte": {
            "$ref": "#/components/schemas/TimestampValue"
          }
        }
      },
      "UpdatesRelevantUntilClause": {
        "description": "`relevant_until` — timestamp; operators: lt, lte, gt, gte; also a sort key.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "relevant_until"
        ],
        "properties": {
          "relevant_until": {
            "$ref": "#/components/schemas/UpdatesRelevantUntilOperators"
          }
        }
      },
      "UpdatesFilterClause": {
        "description": "One condition on a `updates` field: an object with exactly one member, the field name.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/CountryClause"
          },
          {
            "$ref": "#/components/schemas/UpdatesLanguageClause"
          },
          {
            "$ref": "#/components/schemas/UpdatesUpdateTypeClause"
          },
          {
            "$ref": "#/components/schemas/UpdatesPublishedAtClause"
          },
          {
            "$ref": "#/components/schemas/UpdatesRelevantUntilClause"
          }
        ]
      },
      "UpdatesFilter": {
        "description": "The structured filter for `updates`: every clause must hold. Exactly one clause names the country. Only the fields below exist; anything else is `unknown_field`, and an operator a field does not list is `operator_not_allowed`.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "all"
        ],
        "properties": {
          "all": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/UpdatesFilterClause"
            },
            "contains": {
              "$ref": "#/components/schemas/CountryClause"
            },
            "minContains": 1,
            "maxContains": 1
          }
        }
      },
      "UpdatesSortBy": {
        "type": "string",
        "description": "Mandatory: MasterDB never supplies an order. `field:asc|desc`, up to 3, comma-separated, from: `_text_match`, `published_at`, `relevant_until`. For relevance order write `_text_match:desc`.",
        "pattern": "^(?:_text_match|published_at|relevant_until):(?:asc|desc)(?:,(?:_text_match|published_at|relevant_until):(?:asc|desc)){0,2}$"
      },
      "UpdatesCollectionSearchRequest": {
        "description": "A search of `updates` through `POST /v1/search`: the UpdatesSearchRequest with `collection` required.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collection",
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "updates",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `updates` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "enum": [
                "headline",
                "body"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/UpdatesFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/UpdatesSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "SearchRequest": {
        "description": "A search of one collection, selected by `collection`.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ProductsCollectionSearchRequest"
          },
          {
            "$ref": "#/components/schemas/BusinessFilesCollectionSearchRequest"
          },
          {
            "$ref": "#/components/schemas/EventsCollectionSearchRequest"
          },
          {
            "$ref": "#/components/schemas/JobsCollectionSearchRequest"
          },
          {
            "$ref": "#/components/schemas/UpdatesCollectionSearchRequest"
          }
        ]
      },
      "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"
            }
          }
        }
      },
      "SearchCollection": {
        "type": "string",
        "description": "The collections `POST /v1/search` serves. `ads` is not among them: the pool has its own call.",
        "enum": [
          "products",
          "business_files",
          "events",
          "jobs",
          "updates"
        ]
      },
      "Country": {
        "type": "string",
        "description": "ISO 3166-1 alpha-2, from the platform vocabulary.",
        "pattern": "^[A-Z]{2}$"
      },
      "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})$"
      },
      "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}$"
      },
      "RecordType": {
        "type": "string",
        "description": "The five published types, as collection names.",
        "enum": [
          "products",
          "business_files",
          "events",
          "jobs",
          "updates"
        ]
      },
      "Sha256": {
        "type": "string",
        "description": "A SHA-256 digest, `sha256:` + 64 lower-case hex.",
        "pattern": "^sha256:[0-9a-f]{64}$"
      },
      "KeyId": {
        "type": "string",
        "description": "The RFC 7638 JWK thumbprint of a public key, base64url, 43 characters.",
        "pattern": "^[A-Za-z0-9_-]{43}$"
      },
      "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
          }
        ]
      },
      "FreshnessExpectation": {
        "type": "object",
        "description": "How fresh the business says records of this type are expected to be, from its sealed Business & Brand file's `freshness_expectation` — the strictest\nof its files when it has several (one per country). Served on a row only when declared;\noutside the row signature (the business file a fetch returns proves it). **A record is\nstale when it is older than its expectation**: now − `published_at` > the window — an hour,\na day, a week, 31 days, 92 days, 366 days, or `interval_hours`. The verifier libraries'\n`isStale` / `is_stale` apply it.\n",
        "required": [
          "cadence"
        ],
        "properties": {
          "cadence": {
            "type": "string",
            "enum": [
              "hourly",
              "daily",
              "weekly",
              "monthly",
              "quarterly",
              "yearly",
              "interval"
            ]
          },
          "interval_hours": {
            "type": "integer",
            "minimum": 1,
            "maximum": 87600,
            "description": "Only with `cadence` interval."
          }
        },
        "additionalProperties": false
      },
      "SearchRow": {
        "type": "object",
        "description": "One short row (spine plus the collection's returned fields), exactly as the\nprojection wrote and signed it — so each row is verifiable on its own with `adl_row_sig`\n— plus members the retrieval service sets as it serves the row: `ai_policy_bits`,\nthe business's AI policy in force; `freshness_expectation`, the\nbusiness's declared expectation for the row's type, when it declares one; and\n`sponsored`, only when true. None is covered by the row signature; `freshness_expectation`\ncame after v3 was pinned, so it is among `serve_time_fields` of every version. Projection spec v3 lists both among its unsigned\nfields, so a v3 row (its `adl_proj` names the spec) verifies by the published procedure\nexactly as served; the pinned v1 and v2 lists predate `ai_policy_bits`, so for a row of\nthose specs remove it first (`GET /v1/projections/{type}/{version}` names it among\n`serve_time_fields`) — the SDKs' `verifyServedRow` does either, by the row's spec. A product row carries its price for each country it is\npublished in as `price_{CC}` and `price_currency_{CC}`, as signed; the searched\ncountry's is the one the filter and sort used. Never carries a party id, a sponsorship id or anything about blocks. Fields beyond the spine\ndepend on the collection.\n",
        "required": [
          "record_id",
          "business_uuid",
          "type",
          "adl_origin",
          "adl_proj",
          "adl_row_sig",
          "adl_key_id",
          "ai_policy_bits"
        ],
        "properties": {
          "record_id": {
            "$ref": "#/components/schemas/RecordId"
          },
          "business_uuid": {
            "$ref": "#/components/schemas/BusinessUuid"
          },
          "type": {
            "$ref": "#/components/schemas/RecordType"
          },
          "published_at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "sponsored": {
            "type": "boolean",
            "description": "Present and true only when the row's sponsorship is deliverable in this region now. Confirm a render of it with `POST /v1/ads/render`."
          },
          "adl_origin": {
            "$ref": "#/components/schemas/Sha256"
          },
          "adl_origin_cert": {
            "type": "string"
          },
          "adl_proj": {
            "type": "string",
            "description": "The projection specification version the row was built by (`GET /v1/projections/{type}/{version}`)."
          },
          "adl_row_sig": {
            "type": "string"
          },
          "adl_key_id": {
            "$ref": "#/components/schemas/KeyId"
          },
          "ai_policy_version": {
            "type": "integer",
            "minimum": 0,
            "description": "Signed (projection spec v3): the business's AI policy version its record's seal bound. The version in force now is `ai_policy_bits.ai_policy_version`."
          },
          "ai_policy_bits": {
            "$ref": "#/components/schemas/AiPolicyBits"
          },
          "freshness_expectation": {
            "$ref": "#/components/schemas/FreshnessExpectation"
          }
        },
        "additionalProperties": true
      },
      "Timestamp": {
        "type": "string",
        "description": "RFC 3339 UTC with milliseconds, e.g. 2026-09-23T14:02:11.482Z.",
        "format": "date-time"
      },
      "ReceiptRow": {
        "type": "object",
        "description": "One thing served. For a search row, its origin hash and projection signature as served;\nfor a fetch, the record's `adl_origin` (the `sha256:` of its sealed bytes) and no\n`row_sig`, since a fetch serves the sealed record, not a row. `ai_policy_version` is the\nbusiness's AI policy version applied to it — the version that governs (named\n`terms_version` in receipt formats 1 and 2).\n",
        "required": [
          "id",
          "adl_origin",
          "ai_policy_version"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/RecordId"
          },
          "adl_origin": {
            "$ref": "#/components/schemas/Sha256"
          },
          "row_sig": {
            "type": "string",
            "description": "The row's projection signature as served (`adl_row_sig`); absent on a fetch receipt."
          },
          "ai_policy_version": {
            "type": "integer",
            "minimum": 0
          },
          "sponsored": {
            "const": true,
            "description": "Present only on a search row served with its `sponsored` marker. A sponsored\nrow's render is confirmed against this receipt (`POST /v1/ads/render`); a row served\nunmarked is never charged.\n"
          }
        }
      },
      "ReceiptPayload": {
        "type": "object",
        "description": "MasterDB's signed statement of what it served, to whom and when. Each row entry\ncarries the row's origin hash and signature, so a receipt alone settles \"you served me\nthe old price\". `request_hash` binds the caller's own signed request, and `caller_key_id`\n(formats 2 and 3) names the caller's retrieval key, so a receipt that leaks cannot be\nconfirmed by anyone else. Issued as format 3 (each row's `ai_policy_version`); format\n2 (rows' `terms_version`) and format 1 (no `caller_key_id`) are no longer issued and still\nverify.\n",
        "required": [
          "retrieval_id",
          "served_at",
          "region",
          "request_hash",
          "rows",
          "key_id"
        ],
        "properties": {
          "retrieval_id": {
            "type": "string",
            "pattern": "^r_[A-Za-z0-9_-]{1,62}$"
          },
          "served_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "region": {
            "type": "string",
            "examples": [
              "us-east4"
            ]
          },
          "request_hash": {
            "$ref": "#/components/schemas/Sha256",
            "description": "`sha256:` of the RFC 9421 signature base of the caller's request (its covered\ncomponents and `@signature-params` line, UTF-8) — the bytes the caller's own\nsignature is over, so the caller can recompute it.\n"
          },
          "country": {
            "$ref": "#/components/schemas/Country",
            "description": "The one country the search named; absent on a fetch receipt."
          },
          "rows": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/ReceiptRow"
            }
          },
          "key_id": {
            "$ref": "#/components/schemas/KeyId",
            "description": "The receipt key that signed it."
          },
          "caller_key_id": {
            "$ref": "#/components/schemas/KeyId",
            "description": "Formats 2 and 3 — the AI company's retrieval key that signed the request; always present on them."
          },
          "sandbox": {
            "type": "boolean",
            "description": "Present and true on every sandbox receipt."
          }
        }
      },
      "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"
        }
      },
      "ReceiptEnvelope": {
        "description": "A receipt, Ed25519-signed by the answering region's receipt key. Issued as format 3 (`receipt.v3`); formats 2 and 1 are still accepted by every verifier.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payloadType",
          "payload",
          "signatures"
        ],
        "properties": {
          "payloadType": {
            "type": "string",
            "enum": [
              "application/vnd.masterdb.receipt.v3+json",
              "application/vnd.masterdb.receipt.v2+json",
              "application/vnd.masterdb.receipt.v1+json"
            ]
          },
          "payload": {
            "type": "string",
            "contentEncoding": "base64",
            "contentMediaType": "application/json",
            "contentSchema": {
              "$ref": "#/components/schemas/ReceiptPayload"
            }
          },
          "signatures": {
            "$ref": "#/components/schemas/Signatures"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "description": "At most 50 rows, no pagination, and a signed receipt.",
        "required": [
          "retrieval_id",
          "collection",
          "country",
          "rows",
          "receipt"
        ],
        "properties": {
          "retrieval_id": {
            "type": "string"
          },
          "collection": {
            "$ref": "#/components/schemas/SearchCollection"
          },
          "country": {
            "$ref": "#/components/schemas/Country"
          },
          "partial": {
            "type": "boolean",
            "description": "True when the index stopped at the 40 ms search cutoff and returned what it had."
          },
          "rows": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/SearchRow"
            }
          },
          "receipt": {
            "$ref": "#/components/schemas/ReceiptEnvelope"
          }
        }
      },
      "ProductsSearchRequest": {
        "description": "A search of `products` (allow-list v1). This is also the input schema of the MCP `search` tool for this collection.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "products",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `products` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "enum": [
                "product_name",
                "short_description",
                "tags",
                "brand"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/ProductsFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/ProductsSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "BusinessFilesSearchRequest": {
        "description": "A search of `business_files` (allow-list v1). This is also the input schema of the MCP `search` tool for this collection.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "business_files",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `business_files` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "enum": [
                "description",
                "brands_owned.name",
                "brands_sold.name",
                "markets_served"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/BusinessFilesFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/BusinessFilesSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "EventsSearchRequest": {
        "description": "A search of `events` (allow-list v1). This is also the input schema of the MCP `search` tool for this collection.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "events",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `events` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "enum": [
                "title",
                "description"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/EventsFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/EventsSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "JobsSearchRequest": {
        "description": "A search of `jobs` (allow-list v1). This is also the input schema of the MCP `search` tool for this collection.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "jobs",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `jobs` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "enum": [
                "title",
                "description"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/JobsFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/JobsSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "UpdatesSearchRequest": {
        "description": "A search of `updates` (allow-list v1). This is also the input schema of the MCP `search` tool for this collection.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "filter",
          "sort_by"
        ],
        "properties": {
          "collection": {
            "const": "updates",
            "description": "Required on `POST /v1/search`; optional on the typed address, where it must be `updates` if given."
          },
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The text query; `*` (the default) matches everything the filter admits."
          },
          "query_by": {
            "type": "array",
            "description": "The text fields `q` is matched against; default: all of them.",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "enum": [
                "headline",
                "body"
              ]
            }
          },
          "filter": {
            "$ref": "#/components/schemas/UpdatesFilter"
          },
          "sort_by": {
            "$ref": "#/components/schemas/UpdatesSortBy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "At most 50 rows; default 50. There is no second page."
          },
          "client_query_id": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "The caller's own reference, echoed in the event stream."
          },
          "session_ref": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,128}$",
            "description": "Optional: your opaque label for the conversation, new for every conversation and never identifying a person. HMACed with a daily salt on arrival, used only for repeat limits and fraud patterns, never shown to a business."
          },
          "topic_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "description": "Optional: subject terms of the search (\"vegan restaurant\", \"late opening\"), stored — screened for anything that looks personal — as demand insight for businesses. The free text `q` runs the search and is never stored."
          }
        }
      },
      "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"
          }
        ]
      },
      "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"
          }
        }
      },
      "SealedAiPolicy": {
        "type": "object",
        "description": "The business's sealed `ai_policy` record in force at `served_at` (the\n`terms` member under its earlier name): named booleans (`AiPolicyRecord`), sealed by a person\nlike any record, with its seal. This is the policy that governs the delivery, and what\nproves a row's `ai_policy_bits`. A business that has never sealed an AI policy has version\n0 and `record` and `seal` null: nothing is permitted beyond the AI-company Terms.\n",
        "required": [
          "version",
          "record",
          "seal"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "record": {
            "type": [
              "object",
              "null"
            ],
            "description": "The AI policy record's bytes, verbatim, as a JSON value (`AiPolicyRecord`; a record sealed under the earlier name reads `{schema: masterdb/terms/1, terms_schema: 1, …}`); null at version 0. Hash the raw member, not a re-serialisation.",
            "additionalProperties": true
          },
          "seal": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RecordSeal"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Represent": {
        "type": "object",
        "description": "The five \"represent us\" texts of a business file — never indexed, never on a search row, only here.",
        "properties": {
          "represent_description": {
            "type": [
              "string",
              "null"
            ]
          },
          "terms_to_use": {
            "type": [
              "string",
              "null"
            ]
          },
          "terms_to_avoid": {
            "type": [
              "string",
              "null"
            ]
          },
          "claims_not_made": {
            "type": [
              "string",
              "null"
            ]
          },
          "route_questions_to": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "EndpointsStatus": {
        "type": "object",
        "description": "A Business & Brand Identity file's authorised-endpoints section as MasterDB stands behind\nit now, from the signed sidecar. `suspended`: continuous domain\nassurance could no longer confirm control of a domain it relies on — do not send a person\nto, or enter payment details at, any checkout, order, booking or API address in this\nrecord's `authorised_endpoints`. The rest of the record is unaffected.\n",
        "required": [
          "status",
          "since"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "live",
              "suspended"
            ]
          },
          "since": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "Provenance": {
        "type": "object",
        "required": [
          "certificate_url",
          "projection_version",
          "log_leaf"
        ],
        "properties": {
          "certificate_url": {
            "type": "string",
            "format": "uri"
          },
          "projection_version": {
            "type": "string"
          },
          "log_leaf": {
            "$ref": "#/components/schemas/Sha256"
          },
          "source_line": {
            "type": "string",
            "description": "The one line of provenance to cite beside an answer built from this record: `mdb-source/1 record=… origin=… cert=… served=… verify=…`, the\nverify URL landing on the public verify page (`GET /v1/verify/{record_id}`).\n"
          }
        }
      },
      "RecordResponse": {
        "type": "object",
        "description": "One record exactly as sealed. `record` is the business's bytes embedded without\nre-serialisation, so a verifier can hash what it received and match the seal. The use\nconditions (once, one chat, no training, no caching) are the Terms' and travel by\nreference, not as prose on every response.\n",
        "required": [
          "record_id",
          "business_uuid",
          "type",
          "published_at",
          "record",
          "seal",
          "sidecar",
          "ai_policy",
          "provenance",
          "receipt"
        ],
        "properties": {
          "record_id": {
            "$ref": "#/components/schemas/RecordId"
          },
          "business_uuid": {
            "$ref": "#/components/schemas/BusinessUuid"
          },
          "type": {
            "$ref": "#/components/schemas/RecordType"
          },
          "published_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "record": {
            "type": "object",
            "additionalProperties": true,
            "description": "The sealed bytes, verbatim. Every record carries a top-level `schema`, e.g. `masterdb/products/1`."
          },
          "seal": {
            "$ref": "#/components/schemas/RecordSeal"
          },
          "sidecar": {
            "$ref": "#/components/schemas/Envelope"
          },
          "ai_policy": {
            "$ref": "#/components/schemas/SealedAiPolicy"
          },
          "represent": {
            "$ref": "#/components/schemas/Represent"
          },
          "endpoints": {
            "$ref": "#/components/schemas/EndpointsStatus"
          },
          "provenance": {
            "$ref": "#/components/schemas/Provenance"
          },
          "receipt": {
            "$ref": "#/components/schemas/ReceiptEnvelope"
          }
        }
      },
      "RenderFormat": {
        "type": "string",
        "description": "The two ways an ad can be rendered (ads contract, \"Ad formats\"); the AI company chooses.",
        "enum": [
          "compact",
          "card"
        ]
      },
      "Money": {
        "type": "string",
        "description": "A decimal string, never a float: at most 15 integer digits and 6 decimal places.",
        "pattern": "^(?:0|[1-9][0-9]{0,14})(?:\\.[0-9]{1,6})?$"
      },
      "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}$"
      },
      "RenderTokenPayload": {
        "type": "object",
        "description": "A render token. No money in it, ever. Valid 10 minutes from `served_at` on MasterDB's clock, single use, owned by the minting region.",
        "required": [
          "token_id",
          "ad_id",
          "campaign_id",
          "ai_company_uuid",
          "country",
          "format",
          "served_at",
          "region"
        ],
        "properties": {
          "token_id": {
            "type": "string"
          },
          "ad_id": {
            "$ref": "#/components/schemas/RecordId"
          },
          "campaign_id": {
            "type": "string"
          },
          "ai_company_uuid": {
            "$ref": "#/components/schemas/AiCompanyUuid"
          },
          "country": {
            "$ref": "#/components/schemas/Country"
          },
          "format": {
            "$ref": "#/components/schemas/RenderFormat"
          },
          "served_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "region": {
            "type": "string"
          }
        }
      },
      "RenderTokenEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payloadType",
          "payload",
          "signatures"
        ],
        "properties": {
          "payloadType": {
            "type": "string",
            "const": "application/vnd.masterdb.render.v1+json"
          },
          "payload": {
            "type": "string",
            "contentEncoding": "base64",
            "contentMediaType": "application/json",
            "contentSchema": {
              "$ref": "#/components/schemas/RenderTokenPayload"
            }
          },
          "signatures": {
            "$ref": "#/components/schemas/Signatures"
          }
        }
      },
      "ClickTokenPayload": {
        "type": "object",
        "description": "A click token, minted by MasterDB on a render confirmation and carrying the render token's id; valid 24 hours from that confirmation.",
        "required": [
          "token_id",
          "render_token_id",
          "ad_id",
          "campaign_id",
          "ai_company_uuid",
          "confirmed_at",
          "region"
        ],
        "properties": {
          "token_id": {
            "type": "string"
          },
          "render_token_id": {
            "type": "string"
          },
          "ad_id": {
            "$ref": "#/components/schemas/RecordId"
          },
          "campaign_id": {
            "type": "string"
          },
          "ai_company_uuid": {
            "$ref": "#/components/schemas/AiCompanyUuid"
          },
          "confirmed_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "region": {
            "type": "string"
          }
        }
      },
      "ClickTokenEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payloadType",
          "payload",
          "signatures"
        ],
        "properties": {
          "payloadType": {
            "type": "string",
            "const": "application/vnd.masterdb.click.v1+json"
          },
          "payload": {
            "type": "string",
            "contentEncoding": "base64",
            "contentMediaType": "application/json",
            "contentSchema": {
              "$ref": "#/components/schemas/ClickTokenPayload"
            }
          },
          "signatures": {
            "$ref": "#/components/schemas/Signatures"
          }
        }
      },
      "Page": {
        "type": "object",
        "description": "A cursor page. `next_cursor` is absent on the last page.",
        "properties": {
          "next_cursor": {
            "type": "string"
          }
        }
      }
    },
    "parameters": {
      "SandboxKey": {
        "name": "MDB-Sandbox-Key",
        "in": "header",
        "required": false,
        "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",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 8192
        },
        "example": "mdb_sbxk1.eyJ2IjoxLCJraW5kIjoicmV0cmlldmFsIn0.c2lnbmF0dXJl"
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "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",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 257
        },
        "example": "5f2b8c1e-7d3a-4e8f-9b6c-2a1d0e9f8c7b"
      },
      "From": {
        "name": "from",
        "in": "query",
        "required": false,
        "description": "Start of the window, inclusive (RFC 3339 UTC or a date).",
        "schema": {
          "type": "string"
        },
        "example": "2026-10-01T00:00:00Z"
      },
      "To": {
        "name": "to",
        "in": "query",
        "required": false,
        "description": "End of the window, exclusive (RFC 3339 UTC or a date).",
        "schema": {
          "type": "string"
        },
        "example": "2026-10-02T00:00:00Z"
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "description": "The opaque `next_cursor` of the previous page.",
        "schema": {
          "type": "string",
          "maxLength": 512
        }
      }
    },
    "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"
        }
      }
    }
  }
}