​
API Overview

The AIUS API is the server-side brain behind the AIUS agent. It exposes an OpenAI-wire-compatible LLM proxy, a backend-driven agent run loop over WebSocket, and account/billing endpoints for users, clients (organizations), projects, and API tokens. This reference documents the public HTTP/WebSocket contract so you can build your own client — a CLI, a backend integration, or a custom tool-executor — without using the official AIUS CLI. Everything here is the externally observable behavior of the service.

​
Base URLs

https://aius.co/api/v1
The WebSocket run-loop endpoint lives under the same host: 
wss://aius.co/api/v1/runs/ws
Against the dev gateway, send Accept-Encoding: identity on HTTP requests. The dev edge can return compressed bodies that some HTTP clients mishandle; asking for an identity (uncompressed) encoding avoids decoding surprises.

​
Authentication model

AIUS uses two credential types, for two different layers:
CredentialLooks likeUsed forHow you get it
Session tokenan HS256 JWT (eyJ…)Minting API tokens; account/billing readsReturned by POST /v1/login / POST /v1/register (and POST /v1/2fa/login) as session_token
API token (PAT)aius_…All day-to-day API calls (chat proxy, run loop)Minted once via POST /v1/tokens using a session
The typical lifecycle:
1

Authenticate

Register or log in with email + password to obtain a session_token (completing a 2FA challenge if the account requires it).
2

Mint a durable API token

Exchange the session for a long-lived aius_… token via POST /v1/tokens. Store it securely — it is shown only once.
3

Call the API

Send Authorization: Bearer aius_… on every request to the chat proxy, and as the auth frame token on the run-loop WebSocket.
See Authentication for the full request/response shapes. A statically configured AIUS_API_KEY (a pre-issued aius_… token) works identically to a minted token — it is just a bearer credential.

​
Endpoint map

Authentication

/v1/register, /v1/login, /v1/2fa/*, /v1/tokens

Chat proxy

POST /v1/chat/completions — OpenAI-wire LLM proxy (model forced server-side)

Run-loop WebSocket

wss://…/v1/runs/ws — backend-driven agent loop

Clients & projects

/v1/clients, /v1/projects, /v1/tokens

Build a minimal client

End-to-end Python + TypeScript walkthrough

Errors

The detail error shape and common codes

​
Models

The LLM is server-owned and not client-selectable. The gateway ignores any model you send on the chat proxy or run loop and forces the platform-selected model (resolved from a server-side catalog), then scrubs the model identity to aius-default on every user-facing surface. You never choose, name, or see the real upstream model. GET /v1/models is unrelated to LLM selection — it is the per-client model registry (the ML/AI model cards your runs publish as deliverables), scoped by a required org_id query parameter.

​
Rate limits

The gateway applies per-IP rate limits to sensitive endpoints:
EndpointLimit
POST /v1/chat/completions60 / minute
POST /v1/tokens10 / minute
POST /v1/login10 / minute
POST /v1/register5 / minute
Exceeding a limit returns 429 Too Many Requests. Back off and retry.