Back to Foan

REST API

Foan ships a public REST API for everything you can do in the dashboard.

If you're integrating Foan into your own product, building a custom dashboard, or running automations beyond what Zapier covers — this is the lowest-level interface.

Auth

Bearer token. Get one at /dashboard/integrations → REST API → Generate.

Authorization: Bearer foan_pk_live_…

Tokens are workspace-scoped. Rotate or revoke from the same page.

Base URL

https://foan.me/api

All endpoints accept JSON, return JSON. UTF-8 throughout. Times in ISO 8601 UTC.

Common endpoints

  • GET /agents — list agents in the workspace.
  • GET /agents/:id — single agent with full config.
  • PATCH /agents/:id — update name, system prompt, voice, status.
  • GET /calls — list calls with filters: ?direction=inbound&status=completed&limit=50.
  • GET /calls/:id — single call detail with transcript + summary.
  • GET /contacts — list contacts in the workspace.
  • POST /contacts — create a contact.
  • POST /campaigns — create an outbound campaign.
  • POST /campaigns/:id/start — kick off a paused/draft campaign.

Full reference at /api-reference — generated from the OpenAPI spec.

Rate limits

  • 100 req/min per token for read endpoints.
  • 20 req/min per token for write endpoints.
  • 5 req/min for POST /campaigns/:id/start to prevent accidental fire.

429s include Retry-After. Above the limit, the rate-limit window is rolling per-minute.

Pagination

List endpoints use cursor pagination:

GET /calls?cursor=<opaque>&limit=50
→ { items: [...], next_cursor: <opaque|null> }

When next_cursor is null, you've reached the end.

Errors

Standard HTTP status codes plus a JSON body:

{
  "success": false,
  "error": "Agent not found",
  "code": "agent_not_found"
}

code is a stable string you can match on. error is human-readable and may change.

Pricing

API access is included in every Foan plan, no per-call API charge. Calls triggered via the API count toward your normal billable minutes.

Common questions

SDK? Official SDKs are coming. Today the API is plain HTTP — works with any HTTP client.

Webhooks vs API? Use webhooks for push (events as they happen). Use the API for pull (fetching state on demand).

Read-only token? Toggle when generating. Read-only tokens can't PATCH or POST.

CORS? Yes — the API allows browser requests from any origin when authenticated. We assume you're not putting the secret token in front-end code.

OAuth? Not yet. Bearer-token auth only.

Last updated 7 May 2026