API reference

Beta reference — the surface is stabilizing; breaking changes are announced in the changelog.

Base URL: https://moamao.com/api/v1. The API is served from the app origin during the beta; a dedicated api.moamao.com host arrives at GA. All bodies are JSON.

Authentication

Every request carries your API key as a Bearer token. Generate keys in the dashboard; keep them server-side and rotate any key that leaks.

Authorization: Bearer $MOAMAO_KEY

POST /api/v1/runs

Create a run: fan the input out to the panel, run propose and critique, aggregate, and return one answer. The call blocks until the judge finishes.

POST https://moamao.com/api/v1/runs

{
  "input": "Review this migration plan for failure modes: ...",
  "compute": "moamao-cloud"
}

Request fields

Field	Type	Required	Description
`input`	`string`	required	The prompt. Fans out to the whole panel. Max 8,000 characters in the beta.
`compute`	`"moamao-cloud" \| "byok"`	optional	“moamao-cloud” (default) runs on our managed mixture endpoint, billed per token. “byok” is reserved for account provider keys and returns byok_not_available in the beta — run BYOK mixtures in the playground for now.
`stream`	`boolean`	optional	Must be false in the beta. Streaming arrives at GA; sending true returns stream_not_available.

Response

{
  "id": "rn_ahcA-Y86aCc1XWkd",
  "object": "run",
  "model": "Moamao Cloud",
  "compute": "moamao-cloud",
  "answer": "The plan has two likely failure modes: ...",
  "trace": [
    { "stage": "propose",   "provider": "Moamao Cloud", "ms": 2197 },
    { "stage": "critique",  "provider": "Moamao Cloud", "ms": 255 },
    { "stage": "aggregate", "provider": "Moamao Cloud", "ms": 223 }
  ],
  "usage": {
    "prompt_tokens": 536,
    "completion_tokens": 125,
    "total_tokens": 661
  }
}

Field	Type	Description
`id`	`string`	Run identifier (rn_...).
`object`	`string`	Always “run”.
`model`	`string`	The compute that answered — “Moamao Cloud” for managed runs.
`compute`	`string`	The compute mode used: “moamao-cloud”.
`answer`	`string`	The synthesized final answer. This is what you show your users.
`trace[]`	`array`	Ordered stages: { stage: propose \| critique \| aggregate, provider, ms }.
`usage.prompt_tokens`	`number`	Input tokens metered across the whole mixture.
`usage.completion_tokens`	`number`	Output tokens metered across the whole mixture.
`usage.total_tokens`	`number`	Sum of the two. Moamao Cloud bills per token on this total.

Errors

Errors return a non-2xx status and a single JSON object with a message and a stable code:

{
  "error": "compute: 'byok' isn't wired in this beta. Use compute: 'moamao-cloud'.",
  "code": "byok_not_available"
}

Status	Code	Meaning
400	`bad_request`	Malformed JSON or a missing input. The message names the problem.
400	`byok_not_available`	compute: “byok” over the API isn’t wired in the beta. Use moamao-cloud, or run BYOK in the playground.
400	`stream_not_available`	stream: true isn’t available in the beta. Send stream: false.
401	`unauthorized`	Missing, malformed, or revoked API key. Pass Authorization: Bearer mm_live_…
413	`too_large`	input exceeds the beta size limit.
503	`capacity_unavailable`	Moamao Cloud is busy. Retry shortly — availability is honest, not an SLA.
502	`run_failed`	The mixture couldn’t complete. Safe to retry with the same body.

Rate limits

During the beta, managed capacity is shared and requests are lightly rate-limited; over the limit you'll get a 429— queue and retry rather than hammering. Availability is honest, not an SLA: when Moamao Cloud is busy you'll get 503 capacity_unavailable. Endpoints for fetching past runs and listing panels arrive at GA; changes land in the changelog.