{ "openapi": "3.1.1", "info": { "title": "Trusted Master Data API", "version": "1.0.0", "summary": "Trusted, governed master data for autonomous AI agents.", "description": "Paid x402 API for trusted public master data, golden records, and reference data. Every operation is anonymous: there is no sign-up and no credential of any kind. Paid operations settle per call over the x402 payment protocol; discovery operations are free. Errors are RFC 9457 problem details served as application/problem+json. Each operationId is the name of the MCP tool the operation mirrors. A deployment may serve the paid operations without a payment challenge for a bounded promotional window that ends at a fixed instant its operator configures: while it is open the operation executes and answers 200 normally, no 402 challenge is issued, no payment is verified or settled, and a request carrying a payment header is served the same way and charged nothing. Price identifiers and amounts are unchanged by it - the window bypasses the challenge rather than revising a price - and the MCP tools/list availability metadata carries free_until, the instant it closes, while it is open. Each such answer is recorded in the service's audit record under the disposition served_free rather than served, with no payment request and no payer." }, "servers": [ { "url": "https://api.agentmasterdata.com", "description": "The resolved verified publisher domain (Operator decision D1): the API is served at api.agentmasterdata.com; versioned paths below carry their own /v1 prefix." } ], "security": [], "paths": { "/v1/master-data/schema": { "get": { "operationId": "get_master_data_schema", "summary": "Describe the master-data schema.", "description": "Free discovery operation. Returns the entity domains, field groups, and result shapes this service publishes. The v1 entity domains are exactly supplier, location, organization, and reference data.", "responses": { "200": { "description": "The published master-data schema.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/master-data/search": { "post": { "operationId": "search_master_data", "summary": "Search master-data records.", "description": "Paid operation. Searches golden records across the v1 entity domains.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Search request. The canonical input schema is the committed search_master_data MCP tool input schema." } } } }, "responses": { "200": { "description": "Search results in the common result envelope.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/PaymentNotAvailable" }, "503": { "$ref": "#/components/responses/PaidUnavailable" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/master-data/entities/resolve": { "post": { "operationId": "resolve_master_data_entity", "summary": "Resolve an entity to its golden record.", "description": "Paid operation. Resolves identifying attributes to the matching golden-record identity.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Resolution request. The canonical input schema is the committed resolve_master_data_entity MCP tool input schema." } } } }, "responses": { "200": { "description": "Resolution result in the common result envelope.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/PaymentNotAvailable" }, "503": { "$ref": "#/components/responses/PaidUnavailable" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/master-data/entities/{entity_type}/{record_id}": { "get": { "operationId": "get_master_data_golden_record", "summary": "Fetch one golden record.", "description": "Paid operation. Returns the golden record for one entity, with provenance and per-value redistribution terms.", "parameters": [ { "$ref": "#/components/parameters/EntityType" }, { "$ref": "#/components/parameters/RecordId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PaymentSignature" } ], "responses": { "200": { "description": "The golden record in the common result envelope.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/PaymentNotAvailable" }, "503": { "$ref": "#/components/responses/PaidUnavailable" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/master-data/entities/{entity_type}/{record_id}/relationships": { "get": { "operationId": "get_master_data_relationships", "summary": "Fetch the relationships of one golden record.", "description": "Paid operation. Returns the relationship graph around one entity, priced by traversal depth.", "parameters": [ { "$ref": "#/components/parameters/EntityType" }, { "$ref": "#/components/parameters/RecordId" }, { "name": "depth", "in": "query", "required": false, "description": "Traversal depth. Each depth is a separately priced tier.", "schema": { "type": "integer", "minimum": 1, "maximum": 3, "default": 1 } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PaymentSignature" } ], "responses": { "200": { "description": "The relationship graph in the common result envelope.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/PaymentNotAvailable" }, "503": { "$ref": "#/components/responses/PaidUnavailable" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/reference-data/{domain}": { "get": { "operationId": "get_reference_data", "summary": "Fetch a reference-data domain.", "description": "Paid operation. Returns the governed code list for one reference-data domain.", "parameters": [ { "$ref": "#/components/parameters/ReferenceDomain" }, { "name": "query", "in": "query", "required": false, "description": "Optional code or label search: a case-insensitive substring match against a value's code OR its label. Omit it to match every value. Percent-encode the value (a space is %20); a plus sign is a literal plus sign, not a space.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "codes", "in": "query", "required": false, "description": "Exact codes wanted. Set membership, never a substring match; omit it to narrow nothing. Serialized in the repeated form, one codes= per code (codes=A&codes=B): a comma is part of a code, never a separator.", "schema": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "style": "form", "explode": true }, { "name": "locale", "in": "query", "required": false, "description": "Language tag echoed on every served value and in the answer. Labels are served exactly as the snapshot stores them; there is no translation layer. Defaults to en.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$", "default": "en" } }, { "name": "valid_at", "in": "query", "required": false, "description": "The instant to evaluate each value's validity interval at, as an RFC 3339 UTC instant such as 2026-01-01T00:00:00Z (percent-encoded, the colons are %3A). Defaults to the request clock. A value whose source DECLARES its interval is active when valid_from <= valid_at < valid_to, an absent or null bound open on its side. A value whose source states no interval at all is neither: it is served active: null and carries the reference_value_validity_unknown warning.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_inactive", "in": "query", "required": false, "description": "Exactly the string true or false. Whether values not KNOWN to be active at valid_at are served. False excludes them; true serves them flagged - active: false for a value declared inactive, beside the reference_value_inactive warning, and active: null for one whose source states no validity interval, beside reference_value_validity_unknown - so an intentionally excluded value is distinguishable from an accidental match. Either warning is carried when such a value is WITHHELD too, so the omission is never silent.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, applied after query, codes, and validity have narrowed the list. A whole number in decimal digits from 1 through 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque continuation cursor from a prior identical request, percent-encoded as a query value (its base64 punctuation +, /, and = may be sent raw or as %2B, %2F, and %3D). A cursor is bound to the normalized request (domain, query, codes, locale, valid_at, include_inactive) and the data_version it paged, never to the transport or the limit: a cursor issued by the get_reference_data MCP tool continues the page here, and one issued here continues it there, when presented with the same narrowing.", "schema": { "type": "string", "maxLength": 2048 } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PaymentSignature" } ], "responses": { "200": { "description": "The reference-data domain in the common result envelope.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/PaymentNotAvailable" }, "503": { "$ref": "#/components/responses/PaidUnavailable" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/master-data/data-quality/assess": { "post": { "operationId": "assess_master_data_quality", "summary": "Assess the data quality of one stored record or one submitted attribute set.", "description": "Paid operation. Assesses the completeness, validity, consistency, uniqueness, and freshness of ONE existing golden record, named by record_id, or ONE submitted attribute set assessed without being written. Returns dimension scores, explainable issues citing registered quality rules, and safe remediation guidance. It never writes a correction, and a submitted attribute set is named in the answer by its digest alone.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PaymentSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Assessment request. The canonical input schema is the committed assess_master_data_quality MCP tool input schema." } } } }, "responses": { "200": { "description": "The quality assessment in the common result envelope.", "headers": { "PAYMENT-RESPONSE": { "$ref": "#/components/headers/PaymentResponse" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/PaymentNotAvailable" }, "503": { "$ref": "#/components/responses/PaidUnavailable" }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/v1/pricing": { "get": { "operationId": "get_x402_pricing", "summary": "Fetch the machine-readable x402 price catalogue.", "description": "Free discovery operation. Returns the immutable price identifiers and their amounts, populated only from deployment configuration.", "responses": { "200": { "description": "The x402 price catalogue.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Price catalogue unavailable: deployment configuration is absent or still carries unresolved placeholders, and the service fails closed rather than serving invented amounts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/readyz": { "get": { "operationId": "get_readiness", "summary": "Report the serving-readiness facts the payment-data guards decide from.", "description": "Free public endpoint. Returns the configured snapshot's data_version (null while none is loaded), the per-entity record counts, and payments_enabled - true only when this deployment could take a payment (payment configuration resolved, data loaded, and a challenge signing key configured); a boolean and never a facilitator, recipient, asset, or key value. It reports and never judges: an empty deployment is an honest 200 with data_version null.", "responses": { "200": { "description": "The readiness facts.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/eligibility/public-data-inventory": { "get": { "operationId": "get_public_data_eligibility_inventory", "summary": "Publish the versioned public-data eligibility inventory.", "description": "Free public endpoint, deliberately never behind a payment challenge and never reading the serving store: the inventory is a governance document about what the catalogue may publish, and it states the source requirements the paid public data terms and the attribution notice tell a buyer to consult. The response reproduces the committed inventory verbatim under inventory, hoists inventory_schema_version, policy_version, and the synthetic marker beside it, and carries version_notice - which states plainly that the inventory's policy_version and the policy_version a served public-use decision carries are meant to be compared but are not guaranteed to be equal. An inventory that does not validate against its committed schema is a fail-closed 503, never a partially trustworthy document.", "responses": { "200": { "description": "The published inventory, its versions, and the publication notices.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Public-data eligibility inventory unavailable: the committed inventory does not validate against its committed schema, or its publication manifest is unreadable, and the service fails closed rather than publishing a document a buyer would rely on.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details.", "properties": { "type": { "type": "string", "format": "uri-reference", "default": "about:blank" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 100, "maximum": 599 }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri-reference" } } } }, "headers": { "PaymentRequired": { "description": "x402 payment requirements for this operation.", "required": true, "schema": { "type": "string" } }, "PaymentResponse": { "description": "x402 settlement receipt for the payment that unlocked this response.", "required": true, "schema": { "type": "string" } }, "RetryAfter": { "description": "Whole seconds to wait before retrying. It is an exact wait, not a round number: a caller that waits it is admitted, and one that waits a second less is not.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-chosen value that makes a paid call safely retryable: a retry carrying the same value is not charged twice.", "schema": { "type": "string" } }, "PaymentSignature": { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "Signed x402 payment payload settling this paid call.", "schema": { "type": "string" } }, "EntityType": { "name": "entity_type", "in": "path", "required": true, "description": "One of the v1 entity domains. customer, asset, and person are closed Operator decisions, not gaps.", "schema": { "type": "string", "enum": [ "supplier", "location", "organization" ] } }, "RecordId": { "name": "record_id", "in": "path", "required": true, "description": "Golden-record identifier within the entity domain.", "schema": { "type": "string" } }, "ReferenceDomain": { "name": "domain", "in": "path", "required": true, "description": "Reference-data domain identifier.", "schema": { "type": "string" } } }, "responses": { "PaidUnavailable": { "description": "Refused without serving anything, for one of three reasons named by the stable code in the RFC 9457 problem document. service_paused: the operator has paused this deployment and it is serving no data; the Retry-After header names the soonest instant the answer could change. payment_requirements_unavailable: the deployment could be paid but cannot state what payment would be, which is what no configured challenge signing key looks like - a supported serving-only deployment, deliberately disabled rather than broken. payment_configuration_unavailable: a payment configuration is present but unusable, naming a network, asset, recipient, or facilitator credential that will not render into payment requirements; unlike the other two this reports a defect rather than a choice, and it is the one condition the tools/list availability metadata cannot anticipate, so a tool listed available may still answer it. Nothing is read, quoted, or charged by any of them, and free discovery documents keep answering.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PaymentNotAvailable": { "description": "This deployment cannot take a payment for this operation at all, so nothing is quoted, executed, or charged and no challenge is minted. The RFC 9457 problem document carries the stable code payment_not_available. A caller sees it when no payment configuration is resolved, when the operator has paused payments, or when the deployment carries no data to sell for this operation. Not retryable as sent: the answer changes only when the deployment does. Free discovery keeps serving throughout.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PaymentRequired": { "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document. Not issued while a promotional window is open: the operation is served 200 instead, and the MCP availability metadata's free_until names the instant that stops.", "headers": { "PAYMENT-REQUIRED": { "$ref": "#/components/headers/PaymentRequired" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem": { "description": "Error. RFC 9457 problem details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ServicePaused": { "description": "This deployment is paused by its operator and is serving no data. The RFC 9457 problem document carries the stable code service_paused and the Retry-After header names the soonest instant the answer could change. Nothing is read, quoted, or charged. Free discovery documents keep answering while a deployment is paused.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Refused without serving anything. The RFC 9457 problem document carries a stable code and the same wait as the Retry-After header: rate_limited, when a per-caller or per-question budget for this deployment is momentarily spent; or budget_exhausted, when this deployment's own budget for the UTC day is spent, in which case the wait names the next UTC midnight. Nothing is quoted, recorded, or charged, and presenting a payment does not raise either budget. The thresholds themselves are deployment configuration and are deliberately not published.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }