Docs · API

REST endpoints, auth, and OpenAPI

The public REST API is versioned under /api/v1. All authenticated routes require a valid Supabase JWT in the Authorization: Bearer header unless documented otherwise in the OpenAPI spec.

OpenAPI specification

The machine-readable contract lives at /api/v1/openapi.json. Import it into Postman, Insomnia, or your CI contract tests. When the spec and this page disagree, trust the spec for field-level details.

Authentication

Create a workspace and sign in through the product or obtain a token via the documented auth endpoints.
Send Authorization: Bearer <access_token> on each request.
Include Content-Type: application/json for JSON bodies.
Respect tenant isolation - tokens are scoped to the workspace they were issued for.

GET /api/v1/receipts?page=1&limit=20
Authorization: Bearer <supabase-jwt>
Accept: application/json

Service accounts and long-lived API keys for Enterprise are provisioned through Enterprise pilot when available on your plan.

Response envelope

Successful list endpoints return pagination metadata. Errors include a stable code and request identifier.

Success:
{
  "data": [...],
  "meta": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}

Error:
{
  "error": { "code": "UNAUTHORIZED", "message": "Authentication required" },
  "requestId": "uuid"
}

Log requestId when contacting support - it helps us trace the request in application logs without sharing sensitive payload data.

Common error codes

UNAUTHORIZED - missing or expired token
FORBIDDEN - authenticated but lacking workspace permission
NOT_FOUND - resource id does not exist in your tenant
VALIDATION_ERROR - request body or query failed schema validation
RATE_LIMITED - too many requests; back off and retry with exponential delay

Rate limits

Auth, bank-link, and write-heavy routes are rate limited per IP and per user. Limits vary by plan. When limited, the API returns HTTP 429 with RATE_LIMITED. Automated clients should honor Retry-After when present.

Bring your own AI (BYO)

MizuAlign does not automatically share workspace data with third-party AI vendors. Power users can optionally connect their own tools (scripts, coding assistants, community MCP wrappers) using a user-issued bearer token against the same REST API. See BYO AI & API docs for scope, non-goals, and the OpenAPI import path.

Webhooks

Register HTTPS endpoints through /api/v1/webhooks. Delivery includes a signed payload so you can verify authenticity. Retry semantics and event types are enumerated in OpenAPI. Use a publicly reachable URL with valid TLS - localhost endpoints are for development only.

Core endpoints

/api/v1/auth/login - Exchange credentials for a session token (see OpenAPI for request schema)
/api/v1/receipts - List and create receipt records for your workspace
/api/v1/budgets - Read and manage budget definitions
/api/v1/organizations - Workspace metadata and membership (plan-dependent)
/api/v1/webhooks - Register outbound webhook endpoints for supported events

Health and status

/api/health - lightweight liveness check
/status - public component status page

Security and compliance

Do not send card numbers, government IDs, or raw bank credentials to MizuAlign API fields unless explicitly documented. Bank linking uses OAuth-style flows through our aggregation partners. See Security and Privacy.

← Product docs