Every endpoint.
A clear contract.

Describe the master-data schema.

GET /v1/master-data/schema

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.

Operation ID: get_master_data_schema

No request parameters.

Responses

200

The published master-data schema.

Response 200 contract

{
  "description": "The published master-data schema.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Search master-data records.

POST /v1/master-data/search

Paid operation. Searches golden records across the v1 entity domains.

Operation ID: search_master_data

Parameters

Idempotency-Key

header · optional

Client-chosen value that makes a paid call safely retryable: a retry carrying the same value is not charged twice.

Idempotency-Key schema

{
  "type": "string"
}

Copy

PAYMENT-SIGNATURE

header · optional

Signed x402 payment payload settling this paid call.

PAYMENT-SIGNATURE schema

{
  "type": "string"
}

Copy

Request body · required

{
  "type": "object",
  "description": "Search request. The canonical input schema is the committed search_master_data MCP tool input schema."
}

Responses

200

Search results in the common result envelope.

Response 200 contract

{
  "description": "Search results in the common result envelope.",
  "headers": {
    "PAYMENT-RESPONSE": {
      "$ref": "#/components/headers/PaymentResponse"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

402

Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.

Response 402 contract

{
  "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.",
  "headers": {
    "PAYMENT-REQUIRED": {
      "$ref": "#/components/headers/PaymentRequired"
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

429

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.

Response 429 contract

{
  "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"
      }
    }
  }
}

Copy

501

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.

Response 501 contract

{
  "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"
      }
    }
  }
}

Copy

503

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.

Response 503 contract

{
  "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"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Resolve an entity to its golden record.

POST /v1/master-data/entities/resolve

Paid operation. Resolves identifying attributes to the matching golden-record identity.

Operation ID: resolve_master_data_entity

Parameters

Idempotency-Key

header · optional

Client-chosen value that makes a paid call safely retryable: a retry carrying the same value is not charged twice.

Idempotency-Key schema

{
  "type": "string"
}

Copy

PAYMENT-SIGNATURE

header · optional

Signed x402 payment payload settling this paid call.

PAYMENT-SIGNATURE schema

{
  "type": "string"
}

Copy

Request body · required

{
  "type": "object",
  "description": "Resolution request. The canonical input schema is the committed resolve_master_data_entity MCP tool input schema."
}

Responses

200

Resolution result in the common result envelope.

Response 200 contract

{
  "description": "Resolution result in the common result envelope.",
  "headers": {
    "PAYMENT-RESPONSE": {
      "$ref": "#/components/headers/PaymentResponse"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

402

Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.

Response 402 contract

{
  "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.",
  "headers": {
    "PAYMENT-REQUIRED": {
      "$ref": "#/components/headers/PaymentRequired"
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

429

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.

Response 429 contract

{
  "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"
      }
    }
  }
}

Copy

501

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.

Response 501 contract

{
  "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"
      }
    }
  }
}

Copy

503

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.

Response 503 contract

{
  "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"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Fetch one golden record.

GET /v1/master-data/entities/{entity_type}/{record_id}

Paid operation. Returns the golden record for one entity, with provenance and per-value redistribution terms.

Operation ID: get_master_data_golden_record

Parameters

entity_type

path · required

One of the v1 entity domains. customer, asset, and person are closed Operator decisions, not gaps.

entity_type schema

{
  "type": "string",
  "enum": [
    "supplier",
    "location",
    "organization"
  ]
}

Copy

record_id

path · required

Golden-record identifier within the entity domain.

record_id schema

{
  "type": "string"
}

Copy

Idempotency-Key

header · optional

Client-chosen value that makes a paid call safely retryable: a retry carrying the same value is not charged twice.

Idempotency-Key schema

{
  "type": "string"
}

Copy

PAYMENT-SIGNATURE

header · optional

Signed x402 payment payload settling this paid call.

PAYMENT-SIGNATURE schema

{
  "type": "string"
}

Copy

Responses

200

The golden record in the common result envelope.

Response 200 contract

{
  "description": "The golden record in the common result envelope.",
  "headers": {
    "PAYMENT-RESPONSE": {
      "$ref": "#/components/headers/PaymentResponse"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

402

Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.

Response 402 contract

{
  "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.",
  "headers": {
    "PAYMENT-REQUIRED": {
      "$ref": "#/components/headers/PaymentRequired"
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

429

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.

Response 429 contract

{
  "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"
      }
    }
  }
}

Copy

501

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.

Response 501 contract

{
  "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"
      }
    }
  }
}

Copy

503

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.

Response 503 contract

{
  "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"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Fetch the relationships of one golden record.

GET /v1/master-data/entities/{entity_type}/{record_id}/relationships

Paid operation. Returns the relationship graph around one entity, priced by traversal depth.

Operation ID: get_master_data_relationships

Parameters

entity_type

path · required

One of the v1 entity domains. customer, asset, and person are closed Operator decisions, not gaps.

entity_type schema

{
  "type": "string",
  "enum": [
    "supplier",
    "location",
    "organization"
  ]
}

Copy

record_id

path · required

Golden-record identifier within the entity domain.

record_id schema

{
  "type": "string"
}

Copy

depth

query · optional

Traversal depth. Each depth is a separately priced tier.

depth schema

{
  "type": "integer",
  "minimum": 1,
  "maximum": 3,
  "default": 1
}

Copy

Idempotency-Key

header · optional

Client-chosen value that makes a paid call safely retryable: a retry carrying the same value is not charged twice.

Idempotency-Key schema

{
  "type": "string"
}

Copy

PAYMENT-SIGNATURE

header · optional

Signed x402 payment payload settling this paid call.

PAYMENT-SIGNATURE schema

{
  "type": "string"
}

Copy

Responses

200

The relationship graph in the common result envelope.

Response 200 contract

{
  "description": "The relationship graph in the common result envelope.",
  "headers": {
    "PAYMENT-RESPONSE": {
      "$ref": "#/components/headers/PaymentResponse"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

402

Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.

Response 402 contract

{
  "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.",
  "headers": {
    "PAYMENT-REQUIRED": {
      "$ref": "#/components/headers/PaymentRequired"
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

429

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.

Response 429 contract

{
  "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"
      }
    }
  }
}

Copy

501

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.

Response 501 contract

{
  "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"
      }
    }
  }
}

Copy

503

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.

Response 503 contract

{
  "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"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Fetch a reference-data domain.

GET /v1/reference-data/{domain}

Paid operation. Returns the governed code list for one reference-data domain.

Operation ID: get_reference_data

Parameters

domain

path · required

Reference-data domain identifier.

domain schema

{
  "type": "string"
}

Copy

query

query · optional

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.

query schema

{
  "type": "string",
  "minLength": 1,
  "maxLength": 200
}

Copy

codes

query · optional

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.

codes schema

{
  "type": "array",
  "maxItems": 100,
  "items": {
    "type": "string",
    "minLength": 1,
    "maxLength": 100
  }
}

Copy

locale

query · optional

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.

locale schema

{
  "type": "string",
  "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$",
  "default": "en"
}

Copy

valid_at

query · optional

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.

valid_at schema

{
  "type": "string",
  "format": "date-time"
}

Copy

include_inactive

query · optional

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.

include_inactive schema

{
  "type": "boolean",
  "default": false
}

Copy

limit

query · optional

Page size, applied after query, codes, and validity have narrowed the list. A whole number in decimal digits from 1 through 500.

limit schema

{
  "type": "integer",
  "minimum": 1,
  "maximum": 500,
  "default": 100
}

Copy

cursor

query · optional

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.

cursor schema

{
  "type": "string",
  "maxLength": 2048
}

Copy

Idempotency-Key

header · optional

Client-chosen value that makes a paid call safely retryable: a retry carrying the same value is not charged twice.

Idempotency-Key schema

{
  "type": "string"
}

Copy

PAYMENT-SIGNATURE

header · optional

Signed x402 payment payload settling this paid call.

PAYMENT-SIGNATURE schema

{
  "type": "string"
}

Copy

Responses

200

The reference-data domain in the common result envelope.

Response 200 contract

{
  "description": "The reference-data domain in the common result envelope.",
  "headers": {
    "PAYMENT-RESPONSE": {
      "$ref": "#/components/headers/PaymentResponse"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

402

Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.

Response 402 contract

{
  "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.",
  "headers": {
    "PAYMENT-REQUIRED": {
      "$ref": "#/components/headers/PaymentRequired"
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

429

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.

Response 429 contract

{
  "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"
      }
    }
  }
}

Copy

501

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.

Response 501 contract

{
  "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"
      }
    }
  }
}

Copy

503

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.

Response 503 contract

{
  "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"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Assess the data quality of one stored record or one submitted attribute set.

POST /v1/master-data/data-quality/assess

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.

Operation ID: assess_master_data_quality

Parameters

Idempotency-Key

header · optional

Client-chosen value that makes a paid call safely retryable: a retry carrying the same value is not charged twice.

Idempotency-Key schema

{
  "type": "string"
}

Copy

PAYMENT-SIGNATURE

header · optional

Signed x402 payment payload settling this paid call.

PAYMENT-SIGNATURE schema

{
  "type": "string"
}

Copy

Request body · required

{
  "type": "object",
  "description": "Assessment request. The canonical input schema is the committed assess_master_data_quality MCP tool input schema."
}

Responses

200

The quality assessment in the common result envelope.

Response 200 contract

{
  "description": "The quality assessment in the common result envelope.",
  "headers": {
    "PAYMENT-RESPONSE": {
      "$ref": "#/components/headers/PaymentResponse"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

402

Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.

Response 402 contract

{
  "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 payment requirements; the body is an RFC 9457 problem document.",
  "headers": {
    "PAYMENT-REQUIRED": {
      "$ref": "#/components/headers/PaymentRequired"
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

429

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.

Response 429 contract

{
  "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"
      }
    }
  }
}

Copy

501

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.

Response 501 contract

{
  "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"
      }
    }
  }
}

Copy

503

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.

Response 503 contract

{
  "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"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Fetch the machine-readable x402 price catalogue.

GET /v1/pricing

Free discovery operation. Returns the immutable price identifiers and their amounts, populated only from deployment configuration.

Operation ID: get_x402_pricing

No request parameters.

Responses

200

The x402 price catalogue.

Response 200 contract

{
  "description": "The x402 price catalogue.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

503

Price catalogue unavailable: deployment configuration is absent or still carries unresolved placeholders, and the service fails closed rather than serving invented amounts.

Response 503 contract

{
  "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"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Report the serving-readiness facts the payment-data guards decide from.

GET /readyz

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.

Operation ID: get_readiness

No request parameters.

Responses

200

The readiness facts.

Response 200 contract

{
  "description": "The readiness facts.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Publish the versioned public-data eligibility inventory.

GET /eligibility/public-data-inventory

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.

Operation ID: get_public_data_eligibility_inventory

No request parameters.

Responses

200

The published inventory, its versions, and the publication notices.

Response 200 contract

{
  "description": "The published inventory, its versions, and the publication notices.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}

Copy

503

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.

Response 503 contract

{
  "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"
      }
    }
  }
}

Copy

default

Error. RFC 9457 problem details.

Response default contract

{
  "description": "Error. RFC 9457 problem details.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Copy

Shared schemas

Expand a definition referenced by an endpoint above. These definitions come directly from the pinned specification.

{
  "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"
    }
  }
}