HTTP API

This page documents management-plane HTTP endpoints that use session auth. It excludes agent API key endpoints. WorkspaceAPIKeyAuth middleware exists for ws_live_... keys, but it is not mounted to these management routes in the current router.

Dashboard drilldowns

Path prefix: /api/v1/dashboard. Endpoints:

GET /overview
GET /spend
GET /spend/series
GET /top-agents
GET /top-agents/details
GET /budget-blocked
GET /budget-blocked/details
GET /guard-blocked
GET /guard-blocked/details

Auth/runtime behavior:

Requires gw_session
Tenant is resolved from /w/{slug}
Returns 401 when unauthenticated, 403 when tenant access is denied

Query parameters:

range (optional, default current_month)
Allowed values: 15s, 30s, 1min, 5min, 10min, 15min, 30min, 45min, today, yesterday, 1m, 3m, current_month
timezone (optional, IANA timezone string)

Unknown range values currently fall back to current_month. Detail endpoint requirements:

top-agents/details: requires agent_id
budget-blocked/details: requires run_id or event_id
guard-blocked/details: requires run_id or event_id

Example (GET /api/v1/dashboard/spend?range=current_month):

{
  "window": {
    "kind": "current_month",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-13T14:51:22Z"
  },
  "metrics": {
    "total_micros": 3400000,
    "unique_settlements": 42,
    "avg_micros_per_settlement": 80952.38,
    "budget_used_pct": 34.0
  }
}

Budgets (workspace, agent, plan)

Path prefix: /api/v1/workspaces/{tenant_id}/budgets. Auth/runtime behavior:

Requires gw_session
Requires owner access for {tenant_id}
Returns 401 for unauthenticated, 403 for non-owner/non-member

Workspace budget

GET /workspace
PUT /workspace

PUT request:

{"daily_budget_usd_micros": 10000000}

Response shape:

{
  "tenant_id": "...",
  "daily_budget_usd_micros": 10000000
}

daily_budget_usd_micros may be null (unset). Negative values return 400.

Agent budgets

GET /agents
PUT /agents/{agent_id}

PUT request:

{"daily_budget_usd_micros": 2500000}

PUT response:

{
  "agent_id": "agent_123",
  "daily_budget_usd_micros": 2500000
}

PUT /agents/{agent_id} returns 404 when the agent does not exist in that tenant.

Plan budgets

GET /plans
POST /plans
PUT /plans/{plan_key}
DELETE /plans/{plan_key} (returns 204)

POST /plans request:

{
  "plan_key": "pro",
  "display_name": "Pro",
  "description": "Higher daily limit",
  "daily_budget_usd_micros": 20000000
}

plan_key must match ^[a-z0-9][a-z0-9_-]*$. PUT /plans/{plan_key} supports partial updates:

display_name
description
daily_budget_usd_micros
is_active

Plan responses include:

{
  "id": "...",
  "tenant_id": "...",
  "plan_key": "pro",
  "display_name": "Pro",
  "description": "Higher daily limit",
  "daily_budget_usd_micros": 20000000,
  "is_active": true,
  "created_at": "2026-03-10T12:00:00Z",
  "updated_at": "2026-03-10T12:00:00Z"
}

Alerts (rules, channels, history)

Path prefix: /api/v1/alerts. Auth/runtime behavior:

Requires gw_session
Requires admin-or-higher tenant membership
Tenant is resolved from /w/{slug} before membership checks

System status

GET /system

Current wire keys are Go struct keys (no JSON tags), for example:

{
  "EvaluatorEnabled": true,
  "DispatcherEnabled": true,
  "QueueSize": 0,
  "LastEvaluationTime": "2026-03-13T14:50:00Z",
  "LastDispatchTime": "2026-03-13T14:50:02Z",
  "EnabledRules": 4,
  "ConfiguredChannels": 2
}

Rules

POST /rules
GET /rules
GET /rules/{rule_id}
PATCH /rules/{rule_id}
DELETE /rules/{rule_id} (204)

Rule fields:

severity: info | low | medium | high | critical
scope_type: tenant | workspace | agent
rule_kind: event_count_gte | first_occurrence
rule_config.window_seconds: required, > 0
rule_config.threshold: required for event_count_gte (> 0), omitted or 0 for first_occurrence
cooldown_seconds: >= 0
channel_config_ids: optional channel references

POST /rules example:

{
  "name": "Budget blocked spike",
  "description": "High volume of blocked budget events",
  "enabled": true,
  "severity": "high",
  "scope_type": "workspace",
  "scope_id": "tenant_123",
  "rule_kind": "event_count_gte",
  "rule_config": {
    "window_seconds": 300,
    "threshold": 5,
    "filters": {
      "event_types": ["budget.blocked"]
    }
  },
  "cooldown_seconds": 600,
  "channel_config_ids": ["channel_1"]
}

Channels

POST /channels
GET /channels
GET /channels/{channel_id}
PATCH /channels/{channel_id}
DELETE /channels/{channel_id} (204)
POST /channels/{channel_id}/test

Supported channel_type values:

slack with config { "webhook_url": "https://..." }
webhook with config { "url": "https://...", "signing_secret": "optional" }

POST /channels example:

{
  "channel_type": "slack",
  "enabled": true,
  "config": {
    "webhook_url": "https://hooks.slack.com/services/..."
  }
}

POST /channels/{channel_id}/test returns 200 for successful test sends. Current wire keys are:

{
  "ResponseStatus": 200,
  "ResponseSnippet": "ok"
}

Alert history

GET /
GET /{alert_id}

List query parameters:

limit (default 50)
offset (default 0)
rule_id
severity
status
from (RFC3339)
to (RFC3339)

List response:

{
  "items": [],
  "total": 0,
  "limit": 50,
  "offset": 0
}

Workspace management keys

Path prefix: /api/v1/management/workspace-keys. Auth/runtime behavior:

Requires gw_session
Owner access required
Tenant is resolved from /w/{slug}

`GET /`

{
  "items": [
    {
      "id": "wk_123",
      "name": "ci-key",
      "role": "developer",
      "created_at": "2026-03-10T12:00:00Z",
      "last_used_at": "2026-03-10T15:00:00Z",
      "revoked_at": null
    }
  ]
}

`POST /`

Request:

{"name":"ci-key","role":"developer"}

Success (201) returns the key record and api_key once:

{
  "id": "wk_123",
  "name": "ci-key",
  "role": "developer",
  "created_at": "2026-03-10T12:00:00Z",
  "api_key": "ws_live_<key_id>.<secret>"
}

Valid role values: read_only, developer, admin.

`POST /{id}:revoke`

{"ok":true}

Disabled endpoint

`POST /api/v1/execute`

Always returns 410 Gone:

{"error":"execute endpoint is disabled"}

Overview

Budgets

Agents reference

Dashboard drilldowns

Budgets (workspace, agent, plan)

Workspace budget

Agent budgets

Plan budgets

Alerts (rules, channels, history)

System status

Rules

Channels

Alert history

Workspace management keys

`GET /`

`POST /`

`POST /{id}:revoke`

Disabled endpoint

`POST /api/v1/execute`

​Dashboard drilldowns

​Budgets (workspace, agent, plan)

​Workspace budget

​Agent budgets

​Plan budgets

​Alerts (rules, channels, history)

​System status

​Rules

​Channels

​Alert history

​Workspace management keys

​GET /

​POST /

​POST /{id}:revoke

​Disabled endpoint

​POST /api/v1/execute

Dashboard drilldowns

Budgets (workspace, agent, plan)

Workspace budget

Agent budgets

Plan budgets

Alerts (rules, channels, history)

System status

Rules

Channels

Alert history

Workspace management keys

`GET /`

`POST /`

`POST /{id}:revoke`

Disabled endpoint

`POST /api/v1/execute`