API

The dashboard talks to a JSON API you can call yourself. This page covers the main tenant-facing and public surfaces (core tenant ops, MCP capabilities, jobs, scheduling, media, connections). A few dashboard-only or agency/ops routes are omitted. Programmatic access authenticates with your tenant access key (wgk_…) — find and rotate it under Settings → API access.

The access key is your API credential. Day-to-day dashboard sign-in uses email links instead; you only need the key for scripts and integrations.

Base URL: https://waveguide.adwave.com

Authentication

Exchange your access key for a tenant-scoped session token (30-day expiry):

curl -X POST https://waveguide.adwave.com/auth/login \
  -H "content-type: application/json" \
  -d '{"access_key": "wgk_..."}'
# → { "token": "eyJ...", "tenant": { "tenantId": "ten_...", "name": "Acme" } }

Use it as a bearer on every call:

export WG_TOKEN="eyJ..."
curl -H "authorization: Bearer $WG_TOKEN" \
  https://waveguide.adwave.com/tenants/ten_.../spend

Tokens are scoped to your tenant only. “Sign out everywhere” (Settings) and key rotation both invalidate outstanding sessions.

Endpoints

All paths below are relative to the base URL. :id is your tenant id (ten_…). Unless noted, endpoints require Authorization: Bearer $WG_TOKEN.

Tenant core

Persona enrichment & media

Scheduling

Configure mode (Waveguide / Calendly / external) on the soul profile. Native public booking is gated by BOOKING_NATIVE_ENABLED.

Connections (OAuth / social / Twilio)

Capabilities (MCP tools)

See Capabilities for product behavior. Catalog ids match MCP_CATALOG in code.

OAuth-protected arbitrary MCP servers complete at GET /oauth/mcp/callback (browser redirect; not bearer-auth).

Hosted sending

Jobs (missions)

Audience exports

Examples

Wake the agent with a task:

curl -X POST -H "authorization: Bearer $WG_TOKEN" \
  -H "content-type: application/json" \
  -d '{"text": "Summarize this week and flag anything odd."}' \
  https://waveguide.adwave.com/tenants/ten_.../wake

Connect a curated MCP tool (Apollo):

curl -X POST -H "authorization: Bearer $WG_TOKEN" \
  -H "content-type: application/json" \
  -d "{\"catalog_id\": \"apollo\", \"secret\": \"$APOLLO_API_KEY\"}" \
  https://waveguide.adwave.com/tenants/ten_.../mcp/connections

Create a standing policy (auto-approve budget changes with a delta under $50):

curl -X POST -H "authorization: Bearer $WG_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "action_type": "campaign.budget_change",
    "predicate": {"budget_delta_cents": {"lt": 5000}},
    "effect": "auto_approve"
  }' \
  https://waveguide.adwave.com/tenants/ten_.../policies

Predicates map dotted paths in the tool input to constraints (lt, lte, gt, gte, eq, in), combined with AND semantics. An empty predicate {} matches every action of that type. Policies apply to T2 only — T3 always requires a human — and tainted input forces approval regardless of policy.

Kill switch:

curl -X POST -H "authorization: Bearer $WG_TOKEN" \
  https://waveguide.adwave.com/tenants/ten_.../kill

Approval links

Approval resolution endpoints (/a/:token/approve, /a/:token/deny) use the signed single-use token carried in the approval card — they are not access-key-authenticated, because the token itself is the credential. Treat approval links like passwords: don’t forward them.

Rate limits and errors

Auth endpoints are rate-limited per IP; /wake allows 5 manual runs per hour. Public /book/:slug POSTs are rate-limited per IP. Errors return JSON ({"error": "message"}) with conventional status codes: 401 bad/expired credentials, 403 wrong tenant scope, 429 rate-limited, 5xx our problem.

Not in this reference

Agent-runtime callbacks (/runtime/*), provider webhooks (/webhooks/*), and internal/service routes are platform-internal — sandboxes call them with capability tokens, not your access key. Operator docs: docs/external-accounts.md, docs/runbook.md, docs/adr/0009-scheduling-service.md.