# Admin API
The Admin API provides full platform management capabilities for ARES operators. Use it to provision tenants, manage agents, monitor usage, and operate the platform.
**Base URL:** `http://localhost:3000`
## Authentication
Every request to `/api/admin/*` must include the admin secret:
```
X-Admin-Secret: <secret>
```
This secret is set in your `ares.toml` configuration. Guard it carefully — it grants full platform access.
---
## Tenants
### Create Tenant
```
POST /api/admin/tenants
```
**Request Body:**
```json
{
"name": "acme-corp",
"tier": "pro"
}
```
Valid tiers: `free`, `dev`, `pro`, `enterprise`.
**Response:**
```json
{
"id": "tenant-uuid",
"name": "acme-corp",
"tier": "pro",
"created_at": "2026-03-13T00:00:00Z"
}
```
### List Tenants
```
GET /api/admin/tenants
```
**Response:**
```json
{
"tenants": [
{
"id": "tenant-uuid",
"name": "acme-corp",
"tier": "pro",
"agent_count": 4,
"created_at": "2026-03-13T00:00:00Z"
}
]
}
```
### Get Tenant Details
```
GET /api/admin/tenants/{id}
```
**Response:**
```json
{
"id": "tenant-uuid",
"name": "acme-corp",
"tier": "pro",
"agent_count": 4,
"api_key_count": 2,
"total_runs": 12849,
"total_tokens": 7291034,
"created_at": "2026-03-13T00:00:00Z"
}
```
### Update Tenant Tier
```
PUT /api/admin/tenants/{id}/quota
```
**Request Body:**
```json
{
"tier": "enterprise"
}
```
**Response:** Updated tenant object.
---
## Provisioning
### Provision a Client
```
POST /api/admin/provision-client
```
This is the recommended way to onboard a new enterprise client. It atomically creates a tenant, clones the appropriate agent templates, and generates an API key — all in a single transaction. If any step fails, everything is rolled back.
**Request Body:**
```json
{
"name": "acme-corp",
"tier": "pro",
"product_type": "kasino",
"api_key_name": "production"
}
```
| `name` | string | Yes | Unique tenant name (lowercase, alphanumeric + hyphens) |
| `tier` | string | Yes | One of: `free`, `dev`, `pro`, `enterprise` |
| `product_type` | string | Yes | Template set to clone: `generic`, `kasino`, `ehb` |
| `api_key_name` | string | Yes | Label for the initial API key |
**Response:**
```json
{
"tenant_id": "tenant-uuid",
"tenant_name": "acme-corp",
"tier": "pro",
"product_type": "kasino",
"api_key_id": "key-uuid",
"api_key_prefix": "ares_a1b2",
"raw_api_key": "ares_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
"agents_created": [
"kasino-classifier",
"kasino-risk",
"kasino-transaction",
"kasino-report"
]
}
```
> **Important:** The `raw_api_key` is only returned once. Store it securely and deliver it to the client through a secure channel.
**curl Example:**
```bash
curl -X POST http://localhost:3000/api/admin/provision-client \
-H "X-Admin-Secret: your-admin-secret" \
-H "Content-Type: application/json" \
-d '{
"name": "acme-corp",
"tier": "pro",
"product_type": "kasino",
"api_key_name": "production"
}'
```
---
## API Keys
### Create API Key for Tenant
```
POST /api/admin/tenants/{id}/api-keys
```
**Request Body:**
```json
{
"name": "staging-key"
}
```
**Response:**
```json
{
"id": "key-uuid",
"prefix": "ares_x7k9",
"raw_key": "ares_x7k9m2p4q8r1s5t3...",
"created_at": "2026-03-13T00:00:00Z"
}
```
### List API Keys for Tenant
```
GET /api/admin/tenants/{id}/api-keys
```
**Response:**
```json
{
"keys": [
{
"id": "key-uuid",
"name": "production",
"prefix": "ares_a1b2",
"created_at": "2026-03-13T00:00:00Z",
"last_used": "2026-03-13T14:00:00Z"
}
]
}
```
---
## Tenant Agents
### List Tenant Agents
```
GET /api/admin/tenants/{id}/agents
```
**Response:**
```json
{
"agents": [
{
"id": "agent-uuid",
"name": "kasino-classifier",
"agent_type": "classifier",
"status": "active",
"model": "llama-3.3-70b",
"total_runs": 2841,
"success_rate": 0.991
}
]
}
```
### Create Tenant Agent
```
POST /api/admin/tenants/{id}/agents
```
**Request Body:**
```json
{
"name": "custom-analyzer",
"agent_type": "analyzer",
"config": {
"model": "llama-3.3-70b",
"system_prompt": "You are a financial data analyzer...",
"tools": ["calculator"],
"max_tokens": 4096
}
}
```
### Update Tenant Agent
```
PUT /api/admin/tenants/{id}/agents/{name}
```
**Request Body:** Same structure as create. Fields provided will be updated.
### Delete Tenant Agent
```
DELETE /api/admin/tenants/{id}/agents/{name}
```
Returns `204 No Content` on success.
---
## Templates and Models
### List Agent Templates
```
GET /api/admin/agent-templates?product_type=kasino
```
Returns the pre-configured agent templates available for a given product type. These are cloned during provisioning.
**Response:**
```json
{
"templates": [
{
"name": "kasino-classifier",
"agent_type": "classifier",
"product_type": "kasino",
"config": {
"model": "llama-3.3-70b",
"system_prompt": "You are a transaction classifier...",
"tools": []
}
}
]
}
```
### List Available Models
```
GET /api/admin/models
```
Returns all models configured across all providers.
**Response:**
```json
{
"models": [
{
"id": "llama-3.3-70b",
"provider": "groq",
"context_length": 131072,
"supports_tools": true
},
{
"id": "deepseek-r1",
"provider": "nvidia-deepseek",
"context_length": 65536,
"supports_tools": false
},
{
"id": "claude-3.5-sonnet",
"provider": "anthropic",
"context_length": 200000,
"supports_tools": true
}
]
}
```
---
## Usage and Analytics
### Tenant Usage Summary
```
GET /api/admin/tenants/{id}/usage
```
**Response:**
```json
{
"tenant_id": "tenant-uuid",
"tenant_name": "acme-corp",
"tier": "pro",
"period_start": "2026-03-01T00:00:00Z",
"period_end": "2026-03-31T23:59:59Z",
"total_runs": 4821,
"total_tokens": 2847193,
"quota_runs": 100000,
"quota_tokens": 10000000
}
```
### Daily Usage Breakdown
```
GET /api/admin/tenants/{id}/usage/daily?days=30
```
**Response:**
```json
{
"daily": [
{ "date": "2026-03-13", "runs": 312, "tokens": 184920 },
{ "date": "2026-03-12", "runs": 287, "tokens": 171003 }
]
}
```
### Agent Run History
```
GET /api/admin/tenants/{id}/agents/{name}/runs?limit=50
```
**Response:**
```json
{
"runs": [
{
"id": "run-uuid",
"status": "completed",
"started_at": "2026-03-13T14:22:00Z",
"duration_ms": 1243,
"tokens_used": 847
}
]
}
```
### Agent Stats
```
GET /api/admin/tenants/{id}/agents/{name}/stats
```
**Response:**
```json
{
"agent_name": "kasino-classifier",
"total_runs": 2841,
"successful_runs": 2815,
"failed_runs": 26,
"success_rate": 0.991,
"avg_duration_ms": 1102,
"avg_tokens": 723,
"last_run": "2026-03-13T14:22:00Z"
}
```
### Cross-Tenant Agent List
```
GET /api/admin/agents
```
Returns agents across all tenants. Useful for platform-wide visibility.
### Platform Stats
```
GET /api/admin/stats
```
**Response:**
```json
{
"total_tenants": 12,
"total_agents": 47,
"total_runs_today": 3291,
"total_tokens_today": 1948271,
"active_alerts": 2
}
```
---
## Alerts and Audit
### List Alerts
```
GET /api/admin/alerts?severity=critical&resolved=false&limit=100
```
**Query Parameters:**
| `severity` | string | all | Filter by: `info`, `warning`, `critical` |
| `resolved` | boolean | all | Filter by resolution status |
| `limit` | integer | `100` | Maximum results to return |
**Response:**
```json
{
"alerts": [
{
"id": "alert-uuid",
"severity": "critical",
"message": "Tenant acme-corp approaching token quota (92%)",
"tenant_id": "tenant-uuid",
"created_at": "2026-03-13T10:00:00Z",
"resolved": false
}
]
}
```
### Resolve Alert
```
POST /api/admin/alerts/{id}/resolve
```
Returns `200 OK` with the updated alert object.
### Audit Log
```
GET /api/admin/audit-log?limit=50
```
**Response:**
```json
{
"entries": [
{
"id": "entry-uuid",
"action": "tenant.created",
"actor": "admin",
"details": { "tenant_name": "acme-corp", "tier": "pro" },
"timestamp": "2026-03-13T00:00:00Z"
},
{
"id": "entry-uuid",
"action": "agent.deleted",
"actor": "admin",
"details": { "tenant_id": "...", "agent_name": "old-agent" },
"timestamp": "2026-03-12T23:00:00Z"
}
]
}
```