SITEMAP / DOCS / AGENTS

Quickstart

Five minutes from zero to a working external-agent call.

Waypath is the secure customer intelligence and action layer for external agents. API, CLI, and MCP all use the same capability gateway, so grants, approval behavior, quota, receipts, and audit history stay identical across surfaces.

011. Get an agent key

Sign in to https://platform.waypath.app, then open Settings > API Keys > Issue Key. Create a wp_live_... key with the capability grants and modes your agent needs.

Good starter grants:

Good starter modes:

Only enable auto_run for keys that should be allowed to execute approved side-effecting actions without a human click.

022. Check the key

wp auth login --key wp_live_...
wp auth whoami
wp doctor

wp doctor checks API reachability, key validity, workspace binding, available capabilities, modes, quota, and MCP config readiness.

033. Discover capabilities

wp capabilities list
wp capabilities explain context.get

REST callers use the same contract:

curl https://api.waypath.app/api/v1/capabilities \
  -H "Authorization: Bearer wp_live_..."

Every capability includes its input schema, output schema, examples, grant, allowed modes, action-credit cost, side-effect class, approval behavior, MCP tool name, and version.

044. Fetch customer context

CLI:

wp context get jane@acme.com

REST:

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

TypeScript:

const res = await fetch(
  'https://api.waypath.app/api/v1/capabilities/context.get/invoke',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.WAYPATH_API_KEY!}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 'execute',
      source: 'api',
      input: { email: 'jane@acme.com' },
    }),
  },
)

const envelope = await res.json()

Python:

import os, requests

envelope = requests.post(
    'https://api.waypath.app/api/v1/capabilities/context.get/invoke',
    headers={
        'Authorization': f"Bearer {os.environ['WAYPATH_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'mode': 'execute',
        'source': 'api',
        'input': {'email': 'jane@acme.com'},
    },
).json()

055. Write memory back

After your agent makes a decision, log it with an idempotency key:

wp invoke memory.write \
  --mode execute \
  --idempotency-key esc-1284-v2 \
  --input '{
    "customer": "cus_8af2",
    "type": "decision",
    "agent": "support_v2",
    "payload": {
      "action": "escalate_to_human",
      "reason": "customer_frustrated"
    },
    "idempotency_key": "esc-1284-v2"
  }'

That entry is written to Waypath memory, mirrored into the workspace timeline, and returned with a request_id and receipt_url.

066. Queue an action

Side effects should usually start in dry_run or queue mode:

wp outreach queue cus_8af2 \
  --subject "Following up" \
  --body "Quick note based on your recent activity."

Queued responses include:

Poll the receipt:

curl https://api.waypath.app/api/v1/capabilities/pending/pa_123 \
  -H "Authorization: Bearer wp_live_..."

077. Connect MCP

Hosted HTTP:

claude mcp add --transport http waypath https://mcp.waypath.app \
  --header "Authorization: Bearer wp_live_..." \
  -s user

Local stdio:

{
  "mcpServers": {
    "waypath": {
      "command": "npx",
      "args": ["-y", "@waypath/mcp"],
      "env": {
        "WAYPATH_API_KEY": "wp_live_...",
        "WAYPATH_API_BASE": "https://api.waypath.app"
      }
    }
  }
}

MCP tools are generated from GET /api/v1/capabilities and filtered by the active key's grants. Tool calls invoke only POST /api/v1/capabilities/:id/invoke.

08See also