SITEMAP / DOCS / AGENTS

Capabilities

Capabilities are Waypath's public contract for external agents. API, CLI, and MCP all call the same gateway, so auth, grants, action credits, idempotency, AOS approval, and receipts behave the same no matter which client you use.

01List capabilities

curl https://api.waypath.app/api/v1/capabilities \
  -H "X-API-Key: wp_live_..."

Each item is filtered by the active key's grants and includes:

FieldMeaning
idStable capability id, for example context.get.
title, descriptionAgent-facing explanation.
input_schema, output_schemaJSON schemas used by API, CLI explain, and MCP tool schemas.
examplesCopyable invoke examples.
allowed_modesModes this key may use after capability and key filtering.
side_effectnone, memory, event_ingest, outbound_email, voice_call, crm_mutation, campaign_write, or report_write.
action_credit_costCredits charged when the action is queued or committed. dry_run costs 0.
approval_behaviorWhether the capability is read-only, queue-required, or AOS-gated for execute.
mcp_tool_nameTool name exposed by MCP.
versionCapability contract version.

02Invoke

curl https://api.waypath.app/api/v1/capabilities/context.get/invoke \
  -H "X-API-Key: wp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "execute",
    "source": "api",
    "input": { "email": "jane@acme.com" }
  }'

Request body:

{
  "input": {},
  "mode": "dry_run",
  "idempotency_key": "optional-stable-key",
  "source": "api"
}

Response envelope:

{
  "status": "committed",
  "result": {},
  "pending_action_id": null,
  "action_credit_cost": 1,
  "request_id": "8a1c...",
  "quota": {
    "plan": "starter",
    "limit": 500,
    "used": 42,
    "remaining": 458,
    "allowed": true
  },
  "receipt_url": "/api/v1/capabilities/actions/8a1c..."
}

03Modes

ModeBehavior
dry_runValidates input and returns a sanitized preview. Costs 0 and performs no side effects.
queueCreates an AOS pending action when the capability has side effects. Charges on successful queue.
executeRead-only and low-risk writeback capabilities execute after grant, mode, quota, and idempotency checks. Side-effecting capabilities commit only when key auto_run, workspace policy, and AOS auto_approve also pass; otherwise they queue when allowed.

External invocations ignore global AOS_SILENT_MODE; external agents do not inherit internal silent-mode auto-approval.

04Receipts

curl https://api.waypath.app/api/v1/capabilities/actions/<request_id> \
  -H "X-API-Key: wp_live_..."

curl https://api.waypath.app/api/v1/capabilities/pending/<pending_action_id> \
  -H "X-API-Key: wp_live_..."

Receipts show the ledger row, sanitized response, pending action status, and AOS timeline when a queued action exists.

05Usage

curl https://api.waypath.app/api/v1/capabilities/usage/actions \
  -H "X-API-Key: wp_live_..."

Monthly action-credit limits:

PlanCredits
Free100
Starter500
Growth3,000
Pro15,000
EnterpriseConfigurable

Credits are charged only for queued and committed actions. Validation failures, grant denial, mode denial, quota denial, policy denial, and failed execution cost 0.

06CLI and MCP

wp capabilities list
wp capabilities explain context.get
wp invoke context.get --mode execute --input '{"email":"jane@acme.com"}'
wp doctor

MCP tools are generated from GET /api/v1/capabilities; the MCP server does not own a separate hard-coded tool catalog. Tool calls invoke the same gateway and include _mode when an agent wants to override the default mode.

07Current caveats