API access for AI agents

Start here when an AI agent or integration needs to call MaYi's MaaS. The human-readable contract is at /api-specs, and the machine-readable OpenAPI JSON is at /api-specs/openapi.

Production: https://maas.flyingant.win

AI Agent Quickstart

  1. Get an admin-provided API key

    API key must come from a MaaS admin. Ask for a maas_test_ or maas_live_ key with the capability permissions required by the endpoint you will call.

  2. Choose the base URL

    External agents should use the Production base URL: https://maas.flyingant.win.

  3. Send the bearer header

    Every protected /api/v1 route requires Authorization: Bearer <api-key>. JSON routes also require Content-Type: application/json.

  4. Smoke-test authentication first

    Call GET /api/v1/health/auth-check before capability calls. A successful response confirms the key, consumer, capability, and permission wiring.

  5. Call the capability endpoint

    Use the endpoint cards or OpenAPI JSON for the exact request fields. Match your key permissions to the capability key listed for that endpoint.

  6. Poll async jobs when returned

    Image, video, and audio create routes return a jobId instead of final output. Send Idempotency-Key on the create request. Poll GET /api/v1/jobs/{jobId} with the same bearer key until the job reaches a terminal status.

First authenticated call

curl -i https://maas.flyingant.win/api/v1/health/auth-check \
  -H "Authorization: Bearer <api-key>"