Developers

API Reference

Endpoint-level reference for the REST API and webhook payloads.

Format
OpenAPI 3.1
Operations
208 across 172 paths
Error codes
84, each with a stable type
Generated from
The typed contract, not by hand

Overview

One contract, one set of conventions

The v1 surface is 208 operations across 41 resource areas — authentication, customers, wallets, ledger, assets, rewards, events, webhooks, AI, workflows and the rest. This page does not restate all of them; the generated document does that. What it states is the conventions every one of them shares.

Ten properties hold across the surface: RESTful, versioned, predictable, idempotent, permission-aware, multi-tenant, environment-aware, fully documented, OpenAPI compliant, stable. Every write declares the permission it requires, every financial operation declares idempotency, and every collection paginates the same way.

Base URLs

Environments and versioning

Production
https://api.matinee.ai/v1
Sandbox
https://sandbox-api.matinee.ai/v1
Versioning
URL path — /v1
Breaking changes
Require a new version. /v1 is not modified in place.

Headers

The six request headers

Two identify the caller, two scope the request, two are conditional. Nothing else is read from headers.

Authorization

Bearer token — a session token for people, an API key for systems.

Authenticated

X-Organization-ID

Which tenant the request acts on. Client-supplied and therefore never trusted: validated against the authenticated principal, rejected as organization_mismatch on failure.

Authenticated

X-Environment

sandbox or production. A key is scoped to one environment; a mismatch is environment_mismatch, never a silent switch.

Authenticated

X-Request-ID

Client-supplied correlation id, generated if absent. Echoed in every response and every error, and written to the request log.

Optional

Idempotency-Key

Required on the write operations that declare idempotency. The same key with a different body is rejected as idempotency_key_reused.

Conditional

X-SDK-Version

Reported by official SDKs, for deprecation targeting.

Conditional

Envelope

Every response, success or failure

Success wraps the resource in data; failure carries a five-field error. Both carry meta.request_id, so a failed request is as traceable as a successful one.

envelope.jsonjson
// Success
{
  "data": { "id": "cus_9f2…", "external_id": "user-0001" },
  "meta": { "request_id": "req_b81…", "version": "v1" }
}

// Failure — the worked example from the specification
{
  "error": {
    "type": "validation_error",
    "code": "customer_email_invalid",
    "message": "Email is invalid.",
    "details": { "field": "email" }
  },
  "meta": { "request_id": "req_b81…", "version": "v1" }
}

A client switches on error.type for behaviour and on error.code for a message. The identifiers shown are illustrative shapes, not real records.

Conventions

Pagination, sorting and limits

  • Pagination is cursor-based everywhere — cursor and limit in, next_cursor and has_more out. Default page size 25, maximum 100. No endpoint offers an offset parameter: offsets drift when rows are inserted mid-scan, which for a ledger or event feed means silently skipped records.
  • Sorting is one convention across the surface: sort names the field, direction is asc or desc, and each endpoint declares which fields it sorts by.
  • Rate limit headers — RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset — are returned on every response, not only when a limit is hit.

Rate limits

Per-plan request budgets

Public
100 requests per minute
Business
1,000 requests per minute
Enterprise
Configurable
On 429
rate_limit_exceeded — back off and retry

Errors

Eight error types, one registry

Every one of the 84 registered codes belongs to a type, and the type fixes the HTTP status. An endpoint cannot declare a code that is not in the registry.

validation_error

The request is malformed or violates a domain rule — an unbalanced ledger posting, an amount with too many decimal places.

422

authentication_error

No credentials, expired session, revoked key, or a required second factor.

401

authorization_error

Authenticated, but not permitted: a missing permission, a cross-tenant organization id, a wallet policy breach.

403

not_found

The resource does not exist — or is not visible in this organization and environment.

404

conflict

The request is valid but the state refuses it: a frozen wallet, a paused asset, an insufficient balance, a duplicate event.

409

idempotency_error

An Idempotency-Key reused with a different body. A client bug, not a retry.

409

rate_limit_error

Too many requests. The one type where retrying unchanged is correct.

429

service_error

The request could not be completed. Retry with backoff.

500

Lifecycle

Deprecation is announced, not discovered

A deprecated endpoint says so in its Deprecation and Sunset response headers, and migration documentation is published before removal — never after.

The policy already has its first two cases. POST /ai/messages and POST /ai/search are marked deprecated in the v1 document with a sunset date of 2027-02-06, superseded by their conversation-scoped and knowledge-scoped replacements. Both remain in the document and keep working until that date — deprecated rather than deleted.

Artefacts

The reference in machine-readable form

OpenAPI 3.1
openapi.json — generated, build-validated
JSON Schema
Carried inside the document under components.schemas
Postman collection
Generated from the same source
TypeScript types
Generated by openapi-typescript
Where to get them
Public — github.com/matinee-ai/sdk, under api/

Reference

Seeing the conventions in use

Want the reference as a document?

The OpenAPI document, Postman collection and generated types all exist today. Request access and tell us what you are building.

Request AccessSee the APIs product