Last updated Jun 14, 2026

The SDKs are thin wrappers around the JSON REST API. They handle the boring parts — header construction, idempotency-key generation, exponential backoff, cursor pagination, SSE framing, HMAC signature verification — and stay out of your way for everything else. Every typed ID prefix in the API (ent_, tok_, flg_, …) becomes a branded type in the SDK so a DocumentId cannot be passed where an EntityId is expected. The OpenAPI Generator produces the wire stubs; a hand-finishing pass adds the helpers and idiomatic types each language community expects (e.g. async iterators in Node, httpx.AsyncClient in Python, context.Context in Go).

Install

# No install — Matter is a JSON REST API. The SDKs exist to spare you the
# idempotency-key / version-pin / backoff plumbing, not to gate access.
curl https://api.mattermode.com/v1/entities \
  -H "Authorization: Bearer sk_test_..." \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"jurisdiction":"US-DE","legal_name":"Waypoint Systems, Inc."}'

npm i @mattermode/node
# or: pnpm add @mattermode/node
# or: bun add @mattermode/node

pip install matter-sdk
# or: uv add matter-sdk
# or: poetry add matter-sdk

go get github.com/matterhq/matter-go

Comparison

All three SDKs:

• Pin Matter-Version at client construction. No implicit "latest."
• Auto-generate UUID v4 Idempotency-Key headers unless you supply one.
• Surface 202 Accepted as a typed pending resource — async by default is the contract, not an SDK opinion.
• Retry 429 and 5xx with full exponential backoff and jitter, honoring retry_after.
• Map every RFC 7807 type URI to a typed exception class.
• Ship branded ID types so resource-level type confusion is a compile-time error (TypeScript, Go) or a runtime check at the boundary (Python).

Languages

Patterns

The five cross-language patterns most teams hit on day one. Each page shows the same behavior in all three SDKs, side by side, with the JSON REST equivalent for reference.

What the SDKs do not do

• They do not hide the contract. 202 Accepted stays 202 Accepted. The pending resource is what you receive — terminal outcomes still arrive via webhooks. No SDK has a "wait until done" helper that polls for you. (See async by default.)
• They do not auto-pin a version. You pass Matter-Version at construction. The SDK refuses to start without it — implicit version drift in long-lived applications would silently change behavior across deployments.
• They do not retry on 4xx. Only 429 and 5xx are retried. A 400 is a bug in your code; a 409 is a state conflict — neither retries safely.
• They do not deserialize PDFs. Document.pdf_url is a presigned URL; download it yourself. The structured JSON twin (Document.data) is what the SDK exposes as a typed object.
• They do not bundle credentials. No SDK reads from process.env.MATTER_API_KEY or similar by default. Pass the key explicitly. Implicit env reads have caused too many prod-mode-on-localhost incidents.

Generation pipeline

Each SDK lives in its own repo and regenerates on every OpenAPI release. The pipeline:

1. Matter publishes a new spec version to apps/docs/api-reference/openapi.yaml.
2. CI runs bun run sdks:bump which invokes the per-language generator.
3. Generated diff lands in a PR. Hand-written code (idempotency, transport, error shaping) lives outside the generated boundary and is preserved.
4. Each SDK ships a minor version per spec release. Major versions ship only on breaking client-shape changes (rare).

The generator is apps/api/scripts/generate-mcp-tools.ts for the MCP server and a similar pipeline for each SDK repo. Hand-authored API-backed clients are not accepted.

Status

FAQ