API Overview

All API requests are made to https://api.mimasa.ai/v1 and must be sent over HTTPS. Requests over plain HTTP are rejected rather than redirected, so that credentials are never transmitted in the clear. The version segment is part of the path, which lets you pin an integration to a known contract and migrate deliberately rather than being upgraded underneath you.

The API accepts JSON-encoded request bodies and returns JSON-encoded responses. Set Content-Type: application/json on every request that carries a body. Field names use snake_case, timestamps are ISO 8601 in UTC, and identifiers are opaque strings — do not parse meaning out of them. Unknown fields in a request body are rejected rather than silently ignored, so typos surface immediately during development.

Every request must carry a credential. Server-to-server integrations use an API key sent in the Authorization header; user-delegated integrations use OAuth 2.0 so that the calling application acts on behalf of a specific person and inherits that person's role-based permissions. Keys and tokens are scoped to a workspace, so a credential issued for one workspace can never read another workspace's data.

API access respects the same governed workspace rules as the user interface. Role-based access control, dataset-level permissions and audit logging all apply to API traffic, and every call is recorded with the acting identity, the resource touched and the outcome. That means an integration cannot be used as a side door around the controls your data team configured in the product.

List endpoints return a page of results together with a cursor. Pass the cursor back on the next request to continue where you left off; when the cursor is absent you have reached the end of the collection. Cursor pagination stays correct while records are being created or deleted, which offset pagination cannot guarantee for actively changing datasets.

Requests are rate limited per workspace. When a limit is reached the API responds with HTTP 429 and a header describing when to retry. Treat 429 and 5xx responses as retryable with exponential backoff and jitter; treat 4xx responses other than 429 as programming errors that retrying will not fix. Write endpoints accept an idempotency key so a retried request cannot create duplicate work.

Errors use standard HTTP status codes and return a JSON body containing a stable machine-readable code, a human-readable message and, where relevant, the specific field at fault. Branch your logic on the code rather than on the message text, because messages are written for people and may be reworded over time while codes remain stable.

The API is versioned through the URL path and the current version is v1. Additive changes — new endpoints, new optional request fields, new response fields — ship inside the existing version, so clients must tolerate unfamiliar response fields. Anything that would break an existing integration ships as a new version with an announced migration window.