MasterDB Business Machine API (1.0.0)

Publishes a batch of records of one type, each exactly the bytes the business sealed, under one batch seal: a Merkle root over the records' raw bytes signed with the business's own key, carrying the per-key sequence number seq that must be greater than the last accepted one (so a stolen key cannot roll a price back by replaying an old seal) and a sealed_at within five minutes of receipt. Each record is validated with every reason at once and answered accepted, updated or rejected; a push replaces the record it names. A push that would move more than a fifth of the catalogue's prices is held for the owner (the price-shock hold). Only products is published through this route.

Every record is also held to the scope rule (text naming another company or brand, or directing how other sources are treated, is scope_violation; a brand the business sells belongs in its Business & Brand Identity file's brands_sold) and to a malware and phishing check (url_flagged), and a display_domain must be its destination_url's own host (display_domain_mismatch) — each a per-record rejection, never the batch's.

Back-pressure: the per-key caps stamped on the mandate — records per hour and bytes per day — are judged before the body is parsed, and a request over either is answered 429 rate_limited with Retry-After. A mandate with a source allow-list (CIDR ranges and AS numbers) is honoured only from inside it (403 source_not_allowed).

Accepted, then processed. Everything that must refuse a batch is checked before the answer: the request signature, the key, the mandate and its caps, the verified business, the batch seal, its Merkle root over the records, the certificate, the AI policy version, seq, and the business's fair use. Then:

• up to 50 records are processed inside the request and answered 200 with every outcome (PublishOutcome), as before;
• 51 to 10,000 records are stored for processing and answered 202 at once with the push's status (PushStatus) and a Location header: poll GET /v1/pushes/{push_id} until state is complete (or held, or failed). The records are checked and published in chunks of 200 in the background; a notice tells the business's owners and admins when it finishes.

If background processing cannot be reached, a push of up to 500 records is processed inside its request (200). A larger one is answered 503 with Retry-After: 60 and retry_after_seconds: send the same batch again later; a batch that was already accepted is kept and resumes. For more than 10,000 records, upload a bulk file (POST /v1/bulk-uploads, then POST /v1/bulk-imports).

A push that does not answer, or stops (a timeout, a dropped connection, a 5xx, a failed status): every record of the batch has a row in GET /v1/push-attempts and on its status — rejected with its reasons, or pending — and each pending row becomes accepted, updated or held in the same commit that publishes (or holds) its record. Sending the exact batch again (the same batch_seal and records, a new request signature — accepted after the five-minute sealed_at window too, since it was accepted before) resumes it: the records it already settled keep their outcome, the rest are completed, and nothing is published twice. A push still being processed is only reported. Any other batch under the same seq is refused (seq_not_increasing).

Takes a record out of serving with a tiny sealed document {record_id, action: withdraw, at} signed by the business — never an HTTP verb on a bare id. The record of truth is never removed and history stays; the published pointer moves and the fan-out removes the rows and mirror documents from every region within seconds.

Deletes a record with a sealed document {record_id, action: delete, at}. Deletion means deletion: the record leaves serving in seconds and its bytes are purged from the master copy and backups within 30 days; only its fingerprints — the hashes and log leaves — stay, which is what lets the public disavowal check still say when a record with that hash was live.

The manifest of what your business has published — ids, your own business_product_id, last_updated and source (manual, import or api) — in cursor pages, rate-limited above 1,000 records. It is how a connector reconciles its own state with MasterDB's; it is not an export, and the only full-record path is the account export in the Business Portal.

One of your own records as stored, by MasterDB's record id or by your own business_product_id — the bytes you sealed, the seal, the sidecar and where it is live. Only your own business's records are ever returned here.

Every row a push tried to publish in a window, with its outcome and reason — a seal failure is its own category, distinct from a validation failure — so a rejected push is visible within seconds.

A push or bulk import accepted then processed: its totals, its progress and a page of its records' outcomes in leaf order (100 a page; next_cursor for the next). With outcome, only the records with that outcome — e.g. rejected, to fix and send again. Poll every poll_after_seconds while it is present. A push that has completed no step for ten minutes carries stalled: true and a resume instruction (send the exact batch again — a bulk import, the same import request again; what it already published is not published twice). Signed with mdb-business-read: any live integration key of the business may read it.

The bulk-file route for very large loads, step 1: a signed upload (valid one hour) for one file of up to 100,000 records and 256 MiB. The file is newline-delimited: one record a line, each line the base64 of the record's exact bytes (application/x-ndjson); line i is leaf i of the batch seal's Merkle tree. POST the file to url as multipart/form-data with every member of fields, then the file as file. The key needs a live mandate for the record type. Uploaded files are deleted after 7 days, or as soon as their import completes.

Answered 503 with Retry-After (60 seconds) and reason: staging_unavailable where the upload area cannot be written, and 503 with a longer Retry-After where bulk import is not available.

The bulk-file route, step 2: the uploaded file's upload_id and the batch seal over its records — the same seal as a push's (tree_size the number of lines, root the Merkle root over the records' raw bytes, a seq above the key's last). The seal, the key, the mandate and its caps (over the file's bytes and records), the certificate, the AI policy version and fair use are checked here; the file is then read once in the background, and if its records are not exactly the ones the seal names the import is failed with seal_invalid before any record is checked. Otherwise it is processed as a queued push: poll GET /v1/pushes/{push_id}. The same request again answers the import's status, and resumes one that stopped. Answered 503 with Retry-After where bulk import is not available (the upload area cannot be written, reason: staging_unavailable), and where background processing cannot be reached (the import is kept: send the same request again).

What the next seal must name: cert_id, the business's certificate in force (a seal naming any other is refused), and ai_policy_version, the business's own AI policy version in force — the live generation of its AI policy record, 0 before one is sealed. A seal binds the version in force at sealed_at (seal format 2's ai_policy_version; format 1 named terms_version); an AI policy record's own seal names the version it creates, next_ai_policy_version. Before this read a pushing system learned the version only from a refusal (seal_invalid with an ai_policy_version extension). Any live integration key of the business may read it.

Your business's own figures per day, per country and per AI group (one name per group) — searches that returned your records, fetches, ad renders, clicks and spend — as at the end of the last complete hour. Never an impression figure MasterDB cannot know, never share of showings.

The AI groups that retrieved your business's records over the last 30 days, by name, with counts, country as the axis. It is what the business-side block decision is made from.