Разработчикам

API Reference

This document describes Milly Lab's HTTP and WebSocket API. It is for developers integrating with Milly Lab programmatically.

#Base URL

https://aria-web-production-a38d.up.railway.app

All endpoints are prefixed /api.

Interactive documentation

Swagger UI (/docs) and ReDoc (/redoc) are disabled in production. They are available only when the application runs outside a production environment.

To obtain the OpenAPI schema, run the application locally with APP_ENV=development and fetch /openapi.json.

#Authentication

Milly Lab uses JWT bearer tokens.

Obtaining tokens

POST /api/auth/login
Content-Type: application/json

{"email": "user@example.com", "password": "your-password"}

The response contains an access token, a refresh token, and the user record. Send the access token on every subsequent request:

Authorization: Bearer <access_token>

Refreshing

POST /api/auth/refresh
Content-Type: application/json

{"refresh_token": "<refresh_token>"}

Returns a new token pair.

Revocation

Tokens carry the account's revocation version. POST /api/auth/logout, a password change, and a password reset all invalidate every token issued earlier. A revoked token returns 401; obtain a new pair by signing in again.

#Error handling

Errors use standard HTTP status codes with a JSON body.

Most errors return {"detail": "..."}. 402 responses return a structured object so clients can branch on the cause.

The payment-required family

{
  "detail": {
    "code": "insufficient_balance",
    "model_key": "claude-sonnet-5",
    "plan": "pro",
    "balance_usd": 0.42,
    "needed_usd": 1.20,
    "message": "Monthly allowance for this model is exhausted and your top-up balance is too low. Add funds to continue."
  }
}

Always branch on code, never on message — messages are user-facing and may change.

#Rate limits

Applied per client IP by category.

Rate limiting is backed by Redis. When Redis is unavailable, authentication endpoints fall back to a per-process in-memory limiter so they are never entirely unlimited; other traffic passes through.

Exceeding a limit returns 429.

#Endpoints

Authentication — /api/auth

Users — /api/users

GET /me/entitlements is the endpoint to call before offering a model in a UI — it reports what the caller may actually use.

Conversations — /api/conversations

POST /{id}/messages is the main chat endpoint. It streams the response. The 402 gate is applied before any provider call, so a payment-required error arrives instead of a stream, not partway through one.

A full event-by-event description of the streaming format is not yet published; the response streams as it is generated and completes with the final usage totals.

Billing — /api/billing

/topup and /upgrade exist but no payment gateway is connected. They do not take payment.

Swarm Mind — Project Mode — /api/project

Concurrency: a cap applies to simultaneous runs per user. Exceeding it returns an error rather than queueing.

Connected workspaces — /api/project/workspaces

GET /sessions/{id}/changes:

{
  "files": [{"path": "src/app.ts", "op": "edit", "content": "..."}],
  "proposal": {"target": "branch", "branch": "aria/refactor", "message": "..."},
  "applied": null
}

POST /sessions/{id}/changes/apply:

{
  "target": "branch",
  "branch": "aria/refactor",
  "message": "Refactor the request handler"
}

• target is "default" or "branch". Empty falls back to the run's own proposal.
• 409 if a run is still executing, or if an apply is already in progress. The in-progress claim self-expires after 120 seconds.
• 400 if there are no staged changes.
• 404 if the workspace connection no longer exists.
• Per-file failures are reported individually; the apply is not all-or-nothing.

Swarm Mind — Council Mode — /api/council

Studios

Images — /api/images

Video — /api/videos

3D — /api/assets-3d

Generation is asynchronous: the POST returns a job, and you poll status or watch the job list. A budget hold is placed when the job is queued and settled on completion.

Job status — GET /api/jobs/{job_id} for any generation job.

Teams — /api/teams

Inviting sends an email. No account or membership is created until the invitation is accepted, so an invitation cannot be used to probe whether an address is registered.

Other

Administrative endpoints under /api/admin require a platform-operator account and are out of scope here.

#WebSocket protocol

WS /api/project/ws/{session_id}
WS /api/council/ws/{session_id}

Authenticate at connection time by passing your access token as a ?token=<access_token> query parameter, or as an Authorization: Bearer header on the upgrade request.

Close codes:

The server sends {"type":"ping"} roughly every 20 seconds. Clients should tolerate it and may respond with any text frame to keep the connection alive.

Events are self-describing JSON objects with a type field. The replay endpoint returns exactly what the socket delivers, so the two sources never disagree.

Replay — never lose state on reconnect

Events are persisted to an append-only log with a monotonic sequence number. A client that disconnects catches up rather than resyncing from scratch:

GET /api/project/sessions/{id}/events?after_seq=421

Returns a bare JSON array of events with seq > after_seq.

• The page is capped server-side. limit can only make a page smaller, never larger.
• The response header X-Next-Seq carries the sequence to pass as after_seq on the next call.
• Page forward until the array comes back empty, then rely on the socket.

The recommended client pattern is: replay from the last applied sequence, open the socket, then replay again from the last applied sequence to close the gap.

#Pagination

Pagination is not uniform across the API.

• Event replay uses after_seq with the X-Next-Seq header.
• List endpoints generally return a bounded collection; where paging parameters exist, they can only narrow the server's own bounds, never widen them.

#Versioning

The API does not currently carry a version in its path.