What Finn is
Finn is a no-code platform for building AI voice agents that place and answer phone calls. You configure an agent (its prompt, voice, language, tools, and knowledge), attach a phone number, and Finn handles the telephony, speech recognition, model turn-taking, and speech synthesis for each call.
The API exists to automate what the dashboard already does. It is not a lower-level voice runtime. You do not stream audio frames, manage WebRTC sessions, or control turn detection through it. You create and configure agents, start and inspect calls, manage numbers and audiences, and read results after the fact.
To use the API end to end, from an API key to a finished call, follow api-quickstart. If you'd rather build your first agent in the dashboard, start with quickstart-inbound or quickstart-outbound.
What the API covers
| Area | Endpoints | Notes |
|---|---|---|
| Agents | api-finns | Create and update agent configuration |
| Deployments | api-deployments | Bind an agent to a number and a run configuration |
| Calls | api-calls | Start outbound calls, read call records and analysis answers |
| Audiences | api-audiences | Contact lists used by outbound runs |
| Phone numbers | api-phone-numbers | List, rent and release numbers |
| Voices | api-voices | List available voices |
| Webhooks | api-webhooks | Receive the call.completed event. Endpoints are added in the dashboard |
| Wallet | api-wallet | Read balance and usage |
Requests are authenticated with an API key sent as a bearer token. See authentication.
What the API does not cover
Some things are dashboard-only. Do not build against an endpoint you have not seen in the reference pages listed above.
| Task | Where it happens |
|---|---|
| Billing, plan changes, adding credits | Dashboard |
| Team members, roles, invites | Dashboard |
| Compliance applications and number verification | Dashboard, and often a manual review step |
| Call flows, tools and the knowledge base | Dashboard editor |
Beyond that, the API does not give you real-time audio. There is no endpoint that returns a live media stream, and no way to inject audio mid-call. What you get is webhooks: one call.completed event pushed to your endpoint after each call ends.
What will go wrong
Read these before you build anything that matters.
Calls are asynchronous. Creating a call returns once the request is accepted, not once the call is answered. The outcome arrives later through a webhook or by polling the call record. Code that treats a 2xx from the create endpoint as "the call succeeded" will report nonsense. See call-outcomes.
Concurrency is capped. Your account has a limit on simultaneous calls. Firing a thousand create requests does not produce a thousand simultaneous calls, and how the excess is handled is described in concurrency. This is separate from HTTP request rate limits, which are covered in api-rate-limits.
Retries can double-dial. A network timeout on a create-call request does not tell you whether the call was created. The API has no idempotency keys, so check before you retry. See api-idempotency.
Webhook deliveries repeat. Your endpoint must verify signatures (webhook-security) and tolerate duplicate deliveries (webhook-retries).
Telephony fails in ways HTTP does not. Busy, no answer, voicemail, carrier rejection, and spam labelling are normal outcomes, not bugs. troubleshooting covers the common ones.
Where to go next
- concepts for the object model: agents, deployments, calls, audiences.
- api-conventions for request and response shape, then api-errors and api-pagination.
- agents-overview for what actually determines call quality, which is mostly prompting and voice, not API usage.
- local-development for testing webhooks before you have a public endpoint.