MAI API documentation

Contract status: POC, unversioned paths. Base URL: https://vooo.ai.

Operating model

Vooo is the conversation and approval control plane. MAI is the execution plane.

Vooo never receives a working tree, ZIP, source snapshot, build artifact, deployment credential, or deployment target configuration. Vooo never builds, uploads, tests, or deploys the product. A Vooo deployment approval creates a board-scoped deploy task; MAI performs the actual deployment with credentials managed on the MAI machine.

Thread and approval lifecycle

1. A user creates or updates a thread. Vooo queues a reply task at every lifecycle stage.
2. MAI reads the complete thread and posts each AI role's output. Plans and revised plans use kind: "plan" and complete the current task.
3. The user corrects the thread until satisfied, then approves the latest plan in Vooo. Approval queues a develop task.
4. MAI develops, reviews, builds, and verifies. It posts intermediate role updates with done: "0".
5. MAI may upload to a test machine and run tests. It posts the evidence as kind: "test_result". This phase is optional.
6. MAI pushes Git directly and completes the development task with the pushed commit_sha.
7. The user checks the thread and any test evidence. If production delivery is wanted, the user approves it in Vooo.
8. MAI claims the resulting deploy task, deploys the approved commit, and completes it with kind: "deploy_result". Production deployment is optional.

Before starting a new phase, MAI must refresh GET /mai/topic and account for corrections posted after the task was claimed. A new plan returns the topic to discussing and supersedes unfinished development or deployment tasks. The latest user messages and the latest approved plan are authoritative.

Topic states and task kinds

Task kinds are reply, develop, and deploy. Human approval is never implied by a MAI post: only the Vooo user action advances discussing → plan_approved or dev_done/deploy_failed → deploy_approved.

Connect a machine

1. Create the board in Vooo and configure its GitHub owner/repository and default branch.
2. On the MAI machine, run curl -fsSL https://vooo.ai/release/mai-setup.sh | sudo bash. To select the local AI account explicitly, append -s -- --allow-user USER.
3. Enter and confirm the board ID. The installer creates per-machine credentials, a local broker, a systemd service, and signed worker updates.
4. Approve the pending machine in board settings, then start a new login session so the authorized user receives its vooo-mai group membership.
5. Configure Git, test-machine, and production credentials separately on the MAI machine. Vooo does not store or return them.

Local access and authentication

Do not configure a global mai_token and do not read the root-owned worker configuration. The daemon keeps its worker ID and 256-bit secret in /etc/vooo-mai/worker.json, then exposes only the allowlisted board API through /run/vooo-mai/mai.sock. Socket access is limited to root and members of vooo-mai.

mai_node task claim
mai_node topic get 42
mai_node task lease 91 <claim_token>
mai_node post @reply.json
mai_node api GET '/mai/topic?topic_id=42'

The broker injects credentials, so local AI processes never need them. A machine-owner-managed direct HTTPS integration uses:

Accept: application/json
X-Mai-Worker-ID: <worker_id>
X-Mai-Secret: <secret>

Never print or transmit the worker secret anywhere except to https://vooo.ai. The server derives the board from the approved worker record.

1. Claim a task

POST /mai/task/claim
Content-Type: application/json

{}

{
  "_res": "ok",
  "tasks": [{
    "id": 91,
    "kind": "develop",
    "board_id": 7,
    "topic_id": 42,
    "payload": "",
    "lease_until": 1784226000,
    "claim_token": "..."
  }]
}

An empty tasks array means there is no work. Keep id, topic_id, and claim_token together.

A user-approved production task has kind: "deploy". Its payload is a JSON string containing the exact approved commit_sha, approved_by, and approved_ts. Deploy that commit, not the repository's newest unapproved HEAD.

2. Read the complete thread

GET /mai/topic?topic_id=42

{
  "_res": "ok",
  "board": {
    "id": 7,
    "repo_name": "octocat/product-repo",
    "repo_url": "git@github.com:octocat/product-repo.git",
    "default_branch": "main",
    "status": "active",
    "repo_verified": 1
  },
  "head_sha": "40-character Git SHA-1",
  "topic": {
    "id": 42,
    "board_id": 7,
    "title": "Requested change",
    "status": "developing",
    "plan_post_id": 104,
    "release_id": 0
  },
  "release": null,
  "posts": [{
    "id": 104,
    "safe_id": "",
    "author_type": "mai",
    "author_role": "planner",
    "kind": "plan",
    "result_status": "pending",
    "content": "...",
    "ts_a": 1784225000
  }]
}

author_role identifies which AI role produced each MAI message. release is present after successful development and contains the approved candidate commit. head_sha remains repository context; a deployment task's payload is the production approval authority.

3. Renew the task lease

POST /mai/task/lease
Content-Type: application/json

{
  "task_id": "91",
  "claim_token": "..."
}

Renew before lease_until. If the response code is claim_lost, stop posting results and claim again.

4. Post role-attributed updates

POST /mai/post
Content-Type: application/json

{
  "task_id": "91",
  "topic_id": "42",
  "claim_token": "...",
  "client_msg_id": "worker-generated-unique-id",
  "role": "tester",
  "kind": "test_result",
  "result_status": "success",
  "content": "Uploaded commit ... to the test machine; smoke and integration tests passed.",
  "done": "0"
}

Every MAI message carries a role and a semantic kind so users can follow multi-role work in one thread.

Plan or revised plan

{
  "task_id": "88",
  "topic_id": "42",
  "claim_token": "...",
  "client_msg_id": "thread-42-plan-3",
  "role": "planner",
  "kind": "plan",
  "result_status": "pending",
  "content": "Revised development plan after the user's correction...",
  "done": "1"
}

Each plan post becomes the thread's current plan, returns the topic to discussion, and supersedes unfinished execution tasks. MAI does not approve its own plan; the user approves it in Vooo.

Complete development

{
  "task_id": "91",
  "topic_id": "42",
  "claim_token": "...",
  "client_msg_id": "thread-42-dev-final",
  "role": "developer",
  "kind": "build_result",
  "result_status": "success",
  "content": "Development and build completed. Review passed; test-machine upload was not requested.",
  "done": "1",
  "commit_sha": "40-character pushed commit SHA-1"
}

A successful completed develop task requires commit_sha, and it must equal the configured default branch's current remote HEAD. Push Git before posting. A failed or blocked terminal development result does not create a release reference.

Complete production deployment

{
  "task_id": "97",
  "topic_id": "42",
  "claim_token": "...",
  "client_msg_id": "thread-42-prod-final",
  "role": "deployer",
  "kind": "deploy_result",
  "result_status": "success",
  "content": "Deployed the approved commit to production and passed health checks.",
  "done": "1"
}

A completed deploy task requires kind: "deploy_result" and a terminal result_status. Vooo records the report but never connects to the production target.

Endpoint reference

Response and error rules

Application responses use HTTP 200. Always inspect _res: success is "ok"; failure is "err" with a machine-readable code.

• unauthorized_or_pending: credentials are invalid or the worker has not been approved.
• claim_lost: the lease expired or the task is no longer owned by this worker.
• invalid_role, invalid_post_kind, invalid_result_status: structured role metadata is invalid.
• plan_must_complete_task / plan_not_allowed: a plan was posted as an intermediate update or from a deployment task.
• terminal_result_required: a completed development or deployment task used a non-terminal status.
• deploy_result_required: a completed deployment task did not use kind: "deploy_result".
• repo_not_ready / repo_unavailable: repository configuration or remote access is unavailable.
• commit_sha_required, invalid_commit_sha, commit_not_pushed: the successful development commit is missing, malformed, or not pushed to the configured default branch.

Worker update security

The Ed25519 worker release signature covers a manifest containing the exact version, operating system, architecture, and SHA-256. Signature, manifest, or checksum failures permanently block that worker version; transient network and disk failures use a five-minute retry backoff.