Actions Gateway

The Actions Gateway is a bot-facing HTTP API over the same domain services the dashboard uses. It does not invent a second business layer. For AI agents, use the MCP server: it takes the same keys and adds brand, settings and Autopilot tools.

Stable catalog URL

The Phase 0 OpenAPI catalog (v0.1, read-heavy) is served without authentication:

• GET /api/v1/actions/openapi.yaml — canonical
• GET /actions/openapi.yaml — alias

Point Voiceflow, Botpress, or any OpenAPI-capable client at that URL.

Action keys are not df_ keys

Secret keys (df_…) authenticate the public ingest API: contacts, events, and enroll. They are workspace-scoped and otherwise unscoped. They do not list campaigns, read billing, or operate Autopilot.

Action keys (act_…) are a separate credential class with explicit scopes:

• read — Phase 0 read Actions (required for every Action below)
• write:draft — draft writes; on the MCP server, dismiss Autopilot opportunities
• write:live — live sends; maps to dashboard RBAC campaign:publish
• configure — configuration; used by the MCP server for brand, settings and Autopilot

Create and revoke Action keys with a dashboard session (owner/admin, apikey:manage):

POST /api/v1/action-keys
{ "name": "Voiceflow", "scopes": ["read"] }

GET /api/v1/action-keys
DELETE /api/v1/action-keys/:id

The plaintext key is shown once. Send it as X-API-Key: act_… or Authorization: Bearer act_….

Phase 0 read Actions

• GET /api/v1/actions/credits — get_credit_balance
• GET /api/v1/actions/campaigns — list_campaigns
• GET /api/v1/actions/campaigns/:id — get_campaign
• GET /api/v1/actions/segments — list_segments
• POST /api/v1/actions/segments/preview — preview_segment
• GET /api/v1/actions/segments/:id — get_segment
• GET /api/v1/actions/channels — list_channels (provider credentials omitted)
• GET /api/v1/actions/autopilot — get_autopilot_status
• GET /api/v1/actions/autopilot/opportunities — list_autopilot_opportunities

A campaign returned by those reads includes critical, critical_reason, critical_set_by, and critical_set_at. Action keys can read the flag. They cannot turn it on or off. That stays on Campaign settings for an owner or admin.

Idempotency, rate limits, audit

Send Idempotency-Key to replay a stored response for 24 hours. Reusing the same key on a different request returns 409.

Requests are rate-limited per workspace and per Action key. Every invocation — success or failure — is written to the Action audit log.

What this is not

The HTTP Actions do not include Slack, WhatsApp WABA hosting, draft/send/confirm Actions, Autopilot approve, or an HMAC webhook receiver. The dashboard JWT API remains the full operator surface; public df_ keys remain ingest-only.