API
Conventions
The Matter API contract in one screen — base URL, headers, envelope, and a one-line rule per convention.
Last updated
TL;DR. JSON over HTTPS at https://api.mattermode.com/v1. Bearer auth, dated Matter-Version,
Idempotency-Key on every mutation. Mutations return 202 Accepted; terminal outcomes via webhook.
Errors are RFC 7807 application/problem+json. Each row in the table below links to the deep dive.
Base URL and headers
https://api.mattermode.com/v1| Header | Required | Value |
|---|---|---|
Authorization | yes | Bearer sk_live_… · sk_test_… · pk_live_… · pk_test_… · tok_… |
Matter-Version | yes | Dated, e.g. 2026-05-01. Pinned at key/token creation. |
Idempotency-Key | yes on POST/PATCH/PUT/DELETE | Up to 255 chars. UUIDv4 recommended. |
Content-Type | default | application/json |
Every response carries Matter-Request-Id: req_…, mirrored as request_id in error envelopes.
Resource envelope
Every resource — Entity, Filing, Token, all 26 — carries the same envelope.
interface MatterResource {
id: string; // typed prefix, e.g. "ent_Nq3KcAbc"
object: string; // discriminator, e.g. "entity"
created: number; // unix seconds
updated: number; // unix seconds
mode: "live" | "sandbox" | "test";
metadata: Record<string, string>;
}The conventions, one line each
| Convention | Rule | Read more |
|---|---|---|
| Idempotency | Every mutation requires Idempotency-Key. Same key + same body replays. Same key + different body returns 409 idempotency_key_replay. 24-hour retention, token-scoped. | idempotency |
| Pagination | Cursor-based, both directions. limit (default 10, max 100), starting_after, ending_before. List envelope: {object, data, has_more, url, next_cursor}. | pagination |
| Versioning | Matter-Version: YYYY-MM-DD on every request. Pinned at credential creation. v1 is additive-only; breaking changes ship under a new dated version with 18-month support. | versioning |
| Errors | Non-2xx is application/problem+json (RFC 7807). Match on code, log request_id. | errors |
| Async | Mutations return 202 Accepted with the resource pending. Terminal outcomes arrive via webhook minutes to days later. Never block on a state filing. | lifecycle |
| Webhooks | HMAC-SHA256 signed (Matter-Signature: t=,v1=). Per-entity strict ordering via sequence. 3-day backoff in live, 3 attempts in test. Thin payloads by default; opt into fat payloads via WebhookEndpoint.include. | webhooks |
| Expand | ?expand[]=<dot.path>. Inflates referenced resources in-place. Max depth 4. Only fields marked x-matter-expandable in the spec are inflatable. | expand |
| Dry-run | ?dry_run=true on any mutation. Returns the would-be response with dry_run: true. No state mutated, no webhook, no key consumed. | dry-run |
| Mode triad | sk_test_ (deterministic simulators), sk_sandbox_ (production-grade rules, synthetic providers), sk_live_ (real filings). X-Matter-Test-Speed: real | fast | instant is honoured on test. Each mode has its own signing-key hierarchy; receipts cannot cross-mode. | test/sandbox/live mode |
| Rate limits | Budget against X-RateLimit-* headers. 429 includes retry_after seconds — honor it. | rate-limits |
| Caching | ETag + If-None-Match on every GET for conditional requests. Cache-Control on stable resources. | caching |
| Metadata | Every resource accepts a metadata: Record<string, string> for caller-owned tags. Preserved across versions. | metadata |
| Observability | Trace IDs, structured logs, request timing headers. | observability |
| Agent tiers | Scoped tok_ tokens carry tier 1 (observe) → 4 (autonomous). Tier 3+ pauses on Authorization for high-stakes actions. | agents |
Typed IDs
Every resource carries a typed prefix. SDKs generate strongly-typed aliases — EntityId,
FilingId, TokenId — so a doc_ can never be passed where an ent_ is expected.
| Prefix | Resource | Phase |
|---|---|---|
ent_ | Entity | create |
int_ | Intent | create |
rcp_ | IncorporatorReceipt | create |
stk_ | Stakeholder | create |
pf_ | Portfolio | create |
cls_ | ShareClass | manage |
plan_ | EquityPlan | manage |
led_ | ShareLedgerEntry | manage |
grt_ | Grant | manage |
val_ | Valuation | manage |
res_ | Resolution | manage |
flg_ | Filing | manage |
qal_ | Qualification | manage |
doc_ | Document | manage |
ra_ | RegisteredAgent | manage |
tax_ | TaxProfile | manage |
ctx_ | CorporateTransaction | exit |
tok_ | Token | platform |
auth_ | Authorization | platform |
aud_ | AuditEntry | platform |
evt_ | Event | platform |
whe_ | WebhookEndpoint | platform |
req_ | Request | platform |
Plus two computed views with no prefix: CapTable and Compliance.
OpenAPI extensions
The spec uses x-matter-* vendor extensions. Tools that don't understand them safely ignore them.
| Extension | Purpose |
|---|---|
x-matter-id-prefix | Typed ID prefix for the resource. |
x-matter-references | Names the target resource for a foreign-key field. |
x-matter-expandable | Field can be inflated via ?expand[]=<field>. |
x-matter-availability | ga or preview. Preview endpoints stable in shape, not SLA'd. |
x-matter-enum-extensible | New enum values may land in additive releases. |
x-matter-mcp | Controls generation of MCP tools from the spec. |
x-matter-lifecycle | Phase of the operation: create, manage, exit, or platform. |
x-matter-lifecycle-primary | Primary phase of a tag — drives section clustering. |