Skip to main content

​
Bearer authentication

Send the API key in every request:
API keys are server-side secrets. Never expose them in browser JavaScript, mobile bundles, public repositories, logs, analytics, or prompts. Rotate a key if it may have leaked. GET /v1/me identifies the API key and the Mint account that owns it. Assets created with the key belong to that account and can be read through supported API, MCP, and Mint surfaces.

​
Rate limits

Mint uses continuously refilling account-level limits. All API keys owned by the same Mint account share these limits. The general request limit and a paid-work limit apply together when both are relevant. Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the active bucket. X-RateLimit-Reset is the Unix timestamp when the continuously refilling bucket should be full again. A 429 Too Many Requests response includes the same rate-limit headers plus Retry-After; wait at least that long before retrying. Use bounded polling rather than a tight loop. These limits protect the service without restricting ordinary integrations. Contact Mint before intentionally scheduling sustained traffic near a limit.

​
Retry policy

Retry connection failures, 429, and retryable 5xx responses with exponential backoff and jitter. Respect Retry-After when present. Do not blindly retry validation, authentication, payment, or conflict responses. A 400 validation problem can report up to five invalid fields in errors. Each entry includes a field path, validation code, and readable message. Correct every listed field before sending the request again.
Every API response includes X-Request-Id. Save it with failed-request logs and include it when contacting Mint support. Problem type URLs are stable public error categories; branch on the complete URL rather than matching prose in detail. For ordinary mutations, Mint creates an internal request key automatically. You do not need to send another header.

​
Optional retry protection

If your application will retry a mutation when it cannot tell whether Mint accepted the original request, send an optional Idempotency-Key. Generate one stable key before the first attempt and reuse it only for retries of that same request.
The same key and request return the existing operation. The same key with different input returns a conflict. Retrying without a caller-supplied key can start another operation when the first response was lost. Some actions also protect the asset’s current state. Approving Asset Pack items that already started returns their current work without another charge. Repeating the same optimization level does not create another optimized copy. Smart topology and animation create additional outputs, so retry an uncertain request only with the stable key supplied on its first attempt.