Reference: Endpoints
A compact reference of the HTTP endpoints the console consumes. For the full interactive OpenAPI/Swagger document, use the Open Swagger button above (or the API Reference entry in the sidebar) — both open the live Swagger UI hosted at /docs on your connected AcasoOS instance. You can also hit GET /openapi.json directly for the raw schema.
Auth and identity
| Method | Path | Purpose | Scope |
|---|
POST | /v1/auth/session | Exchange a long-lived key for an 8h session token. | none (auth via parent key) |
GET | /v1/users/me | Current user, tenant, roles, effective scopes. | any authenticated session |
GET | /v1/scopes/catalog | Canonical scope taxonomy. | any authenticated session |
Users and roles
| Method | Path | Scope |
|---|
GET | /v1/users | users:read |
POST | /v1/users | users:write |
GET | /v1/users/{id} | users:read (own profile always) |
PATCH | /v1/users/{id} | users:write (own display_name/metadata allowed without) |
DELETE | /v1/users/{id} | users:write |
POST | /v1/users/{id}/roles | users:write |
DELETE | /v1/users/{id}/roles/{slug} | users:write |
GET | /v1/roles | roles:read |
POST | /v1/roles | roles:write |
GET | /v1/roles/{slug} | roles:read |
PATCH | /v1/roles/{slug} | roles:write |
DELETE | /v1/roles/{slug} | roles:write |
GET | /v1/roles/{slug}/users | roles:read |
Agents and chats
| Method | Path | Scope |
|---|
GET | /v1/agents | filtered by agents:<name>:run |
GET | /v1/agents/{name} | agents:<name>:run (404 otherwise) |
POST | /v1/agents/{name}/stream | agents:<name>:run |
GET | /v1/chats | own chats; conversations:read_others for cross-user |
GET | /v1/chats/{id} | per chat_visibility policy |
GET | /v1/chats/{id}/messages | per chat_visibility policy |
PATCH | /v1/chats/{id} | own chats; conversations:write_others for cross-user |
Graphium (context)
| Method | Path | Scope |
|---|
POST | /v1/graphium/ingest | context:write |
POST | /v1/graphium/search | context:read |
POST | /v1/graphium/recall | context:read |
GET | /v1/graphium/wake-up | context:read |
GET | /v1/graphium/taxonomy | context:read |
POST | /v1/graphium/taxonomy/families | context:write |
POST | /v1/graphium/taxonomy/families/{slug}/genera | context:write |
DELETE | /v1/graphium/taxonomy/families/{slug} | context:write (409 if non-empty) |
DELETE | /v1/graphium/taxonomy/families/{slug}/genera/{genus_slug} | context:write (409 if non-empty) |
GET | /v1/graphium/statements/{id} | context:read + row's required_scopes |
GET | /v1/graphium/statements | context:read |
PATCH | /v1/graphium/statements/{id} | context:write (metadata only — not content) |
DELETE | /v1/graphium/statements/{id} | context:write |
Cultivators
| Method | Path | Scope |
|---|
GET | /v1/cultivators | cultivators:read |
POST | /v1/cultivators | cultivators:write (new binding created disabled) |
PATCH | /v1/cultivators/{kind} | cultivators:write (merge semantics) |
DELETE | /v1/cultivators/{kind} | cultivators:write (Kind stays in catalog) |
GET | /v1/cultivators/runs | cultivators:read |
GET | /v1/cultivators/runs/{run_id} | cultivators:read |
Connections
The tenant-level MCP server registry that investigator Cultivators reach through. This is an engineer/ops surface — the console ships no Connections page today.
| Method | Path | Scope |
|---|
GET | /v1/connections | connections:read |
POST | /v1/connections | connections:write (201; 409 if the name exists) |
PATCH | /v1/connections/{name} | connections:write (404 if absent) |
DELETE | /v1/connections/{name} | connections:write (204; 404 if absent) |
Admin
All admin endpoints require acaso_os:admin.
| Method | Path |
|---|
GET | /v1/admin/tenants |
POST | /v1/admin/tenants |
GET | /v1/admin/tenants/{slug} |
PATCH | /v1/admin/tenants/{slug} |
DELETE | /v1/admin/tenants/{slug} |
GET | /v1/admin/tenants/{slug}/api-keys |
POST | /v1/admin/tenants/{slug}/api-keys |
DELETE | /v1/admin/tenants/{slug}/api-keys/{key_id} |
GET | /v1/admin/tenants/{slug}/audit-log |
GET | /v1/admin/tenants/{slug}/agents/{name}/overrides |
PUT | /v1/admin/tenants/{slug}/agents/{name}/overrides |
DELETE | /v1/admin/tenants/{slug}/agents/{name}/overrides |
GET | /v1/admin/health/detailed |
GET | /v1/admin/metrics/tenants/{slug} |
Query playground
| Method | Path | Scope |
|---|
POST | /v1/query/semantic | bound to active tenant |
POST | /v1/query/cypher | bound to active tenant; mutation keywords rejected |
Errors
The API uses a stable error_code field on 4xx responses. See Troubleshooting for the common ones.