Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mayatech.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The Aurous Labs API uses date-pinned versioning. Send Aurous-Version: 2026-05-15 (or any prior date) on every request to opt into a specific contract; we echo the applied version on every response. Missing the header falls back to your team’s default_api_version (current at signup). Breaking changes ship under a new date; non-breaking additions are listed under the current date.

​
2026-05-15 (v1.0)

The first stable date-pin. Everything documented elsewhere on this site is what 2026-05-15 means.

​
Error envelope doc_url — temporary fallback while DNS migrates

The error envelope returned on every 4xx/5xx carries a doc_url field that points at the canonical errors documentation. The canonical host https://docs.aurous-labs.com/errors/<code> is not yet live in DNS (the Mintlify migration is in progress). Until DNS lands, preprod points doc_url at a live OpenAPI fragment URL of the form: 
https://api.preprod.aurous-labs.com/api-spec.json#errors-<code>
The fragment lands on the live OpenAPI JSON spec, which enumerates every error code under the errors schema. Treat both URLs (the OpenAPI-fragment URL on preprod, and https://docs.aurous-labs.com/errors/<code> on prod once DNS lands) as canonical until this migration completes. No customer action is required — the field name and shape do not change.

​
Documentation site moved to docs.aurous-labs.com

As of 2026-05-05, https://api.aurous-labs.com/docs (the legacy Scalar interactive docs surface) returns a 308 Permanent Redirect to https://docs.aurous-labs.com/ — the canonical Mintlify-powered docs site. The redirect carries:
  • Aurous-Deprecated: docs — same response-header pattern used for legacy route deprecations.
  • Sunset: Tue, 04 Aug 2026 00:00:00 GMT — RFC 8594. The redirect goes away on this date; afterward /docs returns 404.
Bookmarks, curl integrations, and any other automation pointing at api.aurous-labs.com/docs should be updated to docs.aurous-labs.com before the sunset. The OpenAPI JSON itself stays at the same URL — https://api.aurous-labs.com/api-spec.json — and is the source of truth for the docs site’s API Reference page.

​
Webhook event types — v1.0 lineup

We deliberately ship a smaller event taxonomy than originally drafted (8 instead of 12). Four event types are flagged below as v1.1 candidates because the underlying status transitions don’t yet exist in the production code path; advertising them today would be doc-fraud. Currently fired:
  • image.completed / image.failed / image.cancelled
  • video.completed / video.failed / video.cancelled
  • usage.balance_low (per-team threshold; 1-hour debounce)
  • webhook.endpoint_disabled (auto-disable notification)
Coming in a later date-pin (NOT fired today):
  • image.expired / video.expired — fires when a generation exceeds the 5-minute polling window without a terminal status. Requires a polling-timeout sweeper that flips status from processing to expired. Until then, stuck generations remain processing; the worker eventually fails them or the cancel endpoint resolves the hold.
  • image.moderation_rejected / video.moderation_rejected — moderation rejection currently throws 400 invalid_request from the create endpoint without inserting an inferences row, so there is nothing to fire a webhook against. Future change: insert the row in moderation_rejected state and fire the event.
If you subscribe with events: ["*"], the snapshot taken at registration time includes only the 8 events that exist today. A future date-pin that adds *.expired or *.moderation_rejected will require you to update your registration explicitly — ["*"] does NOT auto-subscribe across date-pins.

​
Resource paths

V1 endpoints use /v1/images and /v1/videos (Stripe-style nouns). Legacy /v1/generations and /v1/video-generations paths return 308 redirects with Aurous-Deprecated: route and Sunset headers; they are scheduled for removal on 2026-08-04 (90 days after PR-4 land).

​
Status enum

Generation status is one of: queued | processing | succeeded | failed | cancelled. The wire value is succeeded even though some internal logs use completed interchangeably — your integration only ever sees succeeded. expired and moderation_rejected are reserved enum values per the spec but never fire as wire values in 2026-05-15 (see “Webhook event types” above for the same reason).

​
Usage events — fields deferred to a later date-pin

GET /v1/usage/events returns line items with id, type, amount, currency, generation_id, hold_id, description, and created_at. Two fields commonly seen in similar ledger APIs (Stripe events, etc.) are intentionally NOT in 2026-05-15:
  • balance_before / balance_after — the team’s credit balance immediately before and after the event. Computing these accurately requires an authoritative balance-tracking column on usage_events (or a transactional bookkeeping query at write time). Until that ships, omitting the fields is more honest than guessing them. Targeted for a follow-up date-pin once the bookkeeping column is added.
If you need a per-event running balance today, sum amount across rows in chronological order with the type-derived sign (hold / charge / adjustment with negative description debit; release / refund / topup / positive adjustment credit).