API Reference

Base URL

https://api.warpflow.ai/api/v1

Application endpoints in the tables are prefixed with /api/v1, except /health. Most application endpoints require Bearer authentication. Health, public documentation, /api/v1/public/*, and the location_id session flow are exceptions; custom events, assistant tools, and provider webhooks use their own credentials—see Authentication.

Interactive API docs

Explore and test the documented endpoints in the browser using the interactive API documentation:

Open Interactive API Docs →

The interactive docs (Scalar) let you authorize with the credential supported by each endpoint and make live requests against the API. Use them to explore request/response schemas, try out endpoints, and generate code snippets.

The OpenAPI spec is also available for importing into Postman, Insomnia, or code generators: Download OpenAPI spec

Credential capabilities

Published endpoints can require different credentials. Tenant API keys can access same-tenant endpoints protected by tenant scope alone, including basic contact CRUD, conversations, email send, aliases GET, and tasks. Configuration writes, Signal Guard, SMS filters, and email settings writes require manager or higher rights through Cognito ID tokens or the operator admin key. Usage reads and tenant scaffolding require admin rights; usage writes require superuser rights. Embedded session tokens have agent rights. Custom events use a source webhook key, the Telnyx assistant tool uses an assistant secret, and other provider webhooks verify provider signatures.

Endpoint groups

Webhooks—Inbound event ingestion

Webhook endpoints for connected integrations are configured automatically. They use provider-specific signature verification, not Bearer auth.

AI Actions—Classify, score, generate reply

Email—Send, receive, manage

Conversations—Multi-channel history

Contacts

Search

Leads

Sessions

Request — the direct tenant_id flow requires an admin API key or authorized Cognito token:

{ "tenant_id": "acme" }

Response (200):

{
  "token": "eyJzdWIiOiJhY21lIiwibG9jIjpudWxsLCJpYXQiOjE3NzE3ODA2MDAwMDAsImV4cCI6MTc3MTc4NDIwMDAwMH0.k3Jq7f8XyR2mNvB0aL9pQwZs1TcHdEfGiJkLmNoPqRs",
  "tenant_id": "acme",
  "expires_at": 1771784200000
}

expires_at is Unix epoch milliseconds, not an ISO-8601 string. The token is two base64url segments joined by a dot — it resembles a JWT but is not one, so do not hand it to a JWT library.

Errors: 400 BAD_REQUEST (no tenant_id, or malformed JSON), 401 UNAUTHORIZED (missing or invalid admin key), 403 FORBIDDEN (the caller has no access to that tenant), 503 SERVICE_UNAVAILABLE (session signing is not configured).

The alternative { "location_id": "YOUR_LOCATION_ID" } flow currently requires no credential; this behavior is tracked in #2237.

See Session tokens for the full walkthrough.

API Keys

Config

Webhook Subscriptions—Outbound event delivery

Calls

Tasks

Guardrails

Pipeline—Test & process

SMS Filters

All SMS filter operations require manager or higher rights. DELETE accepts { "phone": "+15551234567" } and removes that one phone, returning { "status": "removed" }.

Billing

Additional published operations

The unauthenticated health endpoint is GET /health, outside the /api/v1 prefix. GET /usage/{tenant_id} and POST /config/{tenant_id}/scaffold are tenant-admin reachable. PUT /usage/{tenant_id} is superuser-only and excluded; bare GET /config is dashboard-only, not role-gated, and excluded.

Common response patterns

Success

Success envelopes vary by endpoint. This illustrative action response does not apply to every route.

{
  "success": true,
  "data": { ... }
}

Paginated list

{
  "conversations": [ ... ],
  "next_cursor": "next_page_token"
}

This is a conversation list example. Use its next_cursor value as ?cursor=<value> for the next page.

Error

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

The HTTP status carries the status; error.code is the machine-readable value to branch on. Some errors add an error.details field with the failing fields.

See Errors for the full error code reference.

Rate limits

Limits vary by route. Email sending is limited to 50 requests per hour per tenant; public lead submissions use a separate IP-based limit. Custom events do not promise a per-tenant throttle.

The shared admin API limiter covers /config/*, /guardrails/*, /billing/*, /tenants/*, and /admin/*. Zapier pipeline and standalone Zapier actions have a webhook limiter; workflow actions use a separate limiter. Normal limiter evaluations emit X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds), including on allowed requests. Store-error or skipped-key branches can omit those headers.

Some rate-limited responses include Retry-After in seconds. Use it when present; do not assume every usage-cap or throttling response supplies that header.

Pagination

Pagination varies by endpoint. Conversation lists accept cursor, use a fixed page size of 50 leads, and return next_cursor. Conversation detail currently returns next_cursor: null. Consult each endpoint schema rather than assuming every list supports limit or returns has_more.