SITEMAP / DOCS / API REFERENCE

Capabilities API

The capability gateway is the canonical public API for external agents. API, CLI, and MCP all call this layer instead of legacy dashboard routes.

Base path:

/api/v1/capabilities

Authenticate with Authorization: Bearer wp_live_... or X-API-Key: wp_live_....

01List capabilities

GET /api/v1/capabilities
Authorization: Bearer wp_live_...

The response is filtered by the active key's grants and allowed modes.

{
  "capabilities": [
    {
      "id": "context.get",
      "title": "Get Customer Context",
      "description": "Fetch a compressed customer context bundle by customer id or email.",
      "version": "2026-06-28",
      "grant": "capability:context.get",
      "legacy_scope": "v1:context:read",
      "allowed_modes": ["dry_run", "execute"],
      "action_credit_cost": 1,
      "side_effect": "none",
      "approval_behavior": {
        "kind": "none"
      },
      "mcp_tool_name": "get_customer_context",
      "input_schema": {},
      "output_schema": {},
      "examples": []
    }
  ],
  "key": {
    "id": "key_91ab2c",
    "agent": "cursor",
    "grants": ["capability:context.get"],
    "allowed_modes": ["dry_run", "execute"],
    "auto_run": false
  }
}

02Invoke a capability

POST /api/v1/capabilities/:id/invoke
Authorization: Bearer wp_live_...
Content-Type: application/json

{
  "mode": "execute",
  "source": "api",
  "idempotency_key": "ctx-001",
  "input": {
    "email": "jane@acme.com"
  }
}

mode is one of:

Mode	Behavior
`dry_run`	Validate input and return preview metadata without side effects or credit charge.
`queue`	Create an AOS pending action for operator approval.
`execute`	Read-only and low-risk writeback capabilities execute after grant, mode, quota, and idempotency checks. Side-effecting capabilities also require key `auto_run`, workspace policy, and AOS approval; otherwise they queue when possible.

Response:

{
  "status": "committed",
  "result": {},
  "pending_action_id": null,
  "action_credit_cost": 1,
  "request_id": "req_123",
  "quota": {
    "plan": "starter",
    "limit": 500,
    "used": 41,
    "remaining": 459
  },
  "receipt_url": "/api/v1/capabilities/actions/req_123"
}

03Usage

GET /api/v1/capabilities/usage/actions?limit=25
Authorization: Bearer wp_live_...

Returns monthly usage, plan limit, remaining credits, and recent ledger rows for the workspace and key.

Plan limits:

Plan	Monthly action credits
Free	100
Starter	500
Growth	3000
Pro	15000
Enterprise	configurable

04Receipts

Fetch by request id:

GET /api/v1/capabilities/actions/:request_id
Authorization: Bearer wp_live_...

Fetch by pending action id:

GET /api/v1/capabilities/pending/:pending_action_id
Authorization: Bearer wp_live_...

Receipts include the ledger row, sanitized response, pending action state, and AOS timeline when a queued action is involved.

05Error taxonomy

Code	Meaning
`capability_not_found`	Unknown capability id.
`invalid_input`	Input did not match the capability schema.
`grant_denied`	The key lacks the required grant or legacy scope.
`mode_denied`	The requested mode is not allowed by the capability or key.
`quota_exceeded`	Monthly action credits are exhausted.
`approval_required`	Execution requires operator approval.
`aos_unavailable`	AOS could not queue or inspect the action.
`policy_forbid`	Workspace policy forbids the action.
`capability_failed`	The executor failed.
`idempotency_conflict`	The idempotency key conflicts with an existing request.

06Current readiness notes

The production target is Supabase-backed durable action ledger, quota, and AOS receipts, with local JSON fallback only for development. The current scaffold already routes API, CLI, and MCP through this gateway and records receipts; the remaining hardening work is to make quota check plus ledger insert fully transactional and wire optional Stripe meter event emission for charged rows.