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:

{
  "name": "acme-corp",
  "tier": "pro"
}

Valid tiers: free, dev, pro, enterprise.

Response:

{
  "id": "tenant-uuid",
  "name": "acme-corp",
  "tier": "pro",
  "created_at": "2026-03-13T00:00:00Z"
}

List Tenants

GET /api/admin/tenants

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "name": "acme-corp",
  "tier": "pro",
  "product_type": "kasino",
  "api_key_name": "production"
}
FieldTypeRequiredDescription
namestringYesUnique tenant name (lowercase, alphanumeric + hyphens)
tierstringYesOne of: free, dev, pro, enterprise
product_typestringYesTemplate set to clone: generic, kasino, ehb
api_key_namestringYesLabel for the initial API key

Response:

{
  "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:

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:

{
  "name": "staging-key"
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

ParameterTypeDefaultDescription
severitystringallFilter by: info, warning, critical
resolvedbooleanallFilter by resolution status
limitinteger100Maximum results to return

Response:

{
  "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:

{
  "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"
    }
  ]
}