API docs by Redocly

Fonella API (1.0.0)

Download OpenAPI specification:

Fonella Support: support@fonella.ai URL: https://fonella.ai License: Proprietary

The Fonella REST API lets you programmatically manage your AI phone assistant. Create API keys, subscribe to real-time call webhooks, build custom tools that the AI can invoke during live calls, and access call logs with transcripts and summaries.

Authentication

All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer fon_live_...

API keys are created in the Fonella Dashboard under Developers → API Keys, or via the POST /v1/me/api-keys endpoint (requires an existing JWT or API key session).

Base URL

All requests go to https://api.fonella.ai.

API Keys

Create, list, and delete API keys for programmatic access.

Create API Key

Creates a new API key for the authenticated user. The full plaintext token is returned only once in the response — store it securely. A maximum of 10 keys per account is enforced.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string

A descriptive name for the key (e.g. "CRM Integration").

scopes
Array of strings
Items Enum: "webhooks:manage" "calls:read" "tools:manage"

Permission scopes. Defaults to all scopes if omitted.

expiresAt
string <date-time>

Optional expiration timestamp. The key becomes invalid after this date.

Responses

Request samples

Content type
application/json
{
  • "name": "CRM Integration",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "apiKey": {
    }
}

List API Keys

Returns all API keys for the authenticated user. The full token is never returned — only the first 16 characters (prefix).

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "apiKeys": [
    ]
}

Delete API Key

Permanently deletes an API key. Any integrations using this key will immediately stop working.

Authorizations:
BearerAuth
path Parameters
keyId
required
string <uuid>

The unique identifier of the API key.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Webhooks

Subscribe to real-time call event notifications.

Create Webhook

Registers a new webhook subscription. Fonella will send HTTP POST requests to the specified URL when any of the subscribed events occur. The url must use HTTPS. A signing secret is generated and returned for HMAC-SHA-256 signature verification. Maximum 10 webhooks per account.

Authorizations:
BearerAuth
Request Body schema: application/json
required
url
required
string <uri>

The HTTPS URL to receive webhook deliveries.

events
required
Array of strings (WebhookEventType) non-empty
Items Enum: "call.started" "call.ended" "call.failed" "call.transcript" "call.speech_update" "call.tool_call" "call.hang" "call.summary"

List of event types to subscribe to.

description
string

Optional human-readable description.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "success": true,
  • "webhook": {
    }
}

List Webhooks

Returns all webhook subscriptions for the authenticated user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "webhooks": [
    ]
}

Update Webhook

Updates an existing webhook subscription. Only the provided fields are changed. Re-enabling a webhook resets the failure counter to 0.

Authorizations:
BearerAuth
path Parameters
webhookId
required
string <uuid>

The unique identifier of the webhook subscription.

Request Body schema: application/json
required
url
string <uri>
events
Array of strings (WebhookEventType) non-empty
Items Enum: "call.started" "call.ended" "call.failed" "call.transcript" "call.speech_update" "call.tool_call" "call.hang" "call.summary"
description
string
enabled
boolean

Set to true to re-enable a disabled webhook (resets failure counter).

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "webhook": {
    }
}

Delete Webhook

Permanently deletes a webhook subscription. No further events will be delivered.

Authorizations:
BearerAuth
path Parameters
webhookId
required
string <uuid>

The unique identifier of the webhook subscription.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Custom Tools

Register HTTP endpoints the AI can call during live phone calls.

Create Custom Tool

Registers a new custom tool. During live phone calls, the AI assistant can invoke this tool by calling the specified HTTPS endpoint with the parameters defined in inputSchema. The endpoint must respond within 5 seconds with a JSON body containing a result string. Maximum 20 tools per account.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string

Machine-readable tool name (camelCase, no spaces).

description
required
string

Human-readable description telling the AI when to use this tool.

url
required
string <uri>

HTTPS endpoint called when the tool is invoked.

method
string
Default: "POST"
Enum: "GET" "POST"

HTTP method for tool invocation.

object

Additional HTTP headers sent with each tool request.

inputSchema
object

JSON Schema describing the input parameters the AI should extract from the conversation.

Responses

Request samples

Content type
application/json
{
  • "name": "lookupOrder",
  • "description": "Look up the status of a customer order by order number",
  • "url": "https://your-server.com/api/orders/lookup",
  • "method": "POST",
  • "inputSchema": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tool": {
    }
}

List Custom Tools

Returns all custom tools registered by the authenticated user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "tools": [
    ]
}

Update Custom Tool

Updates an existing custom tool. Only the provided fields are changed.

Authorizations:
BearerAuth
path Parameters
toolId
required
string <uuid>

The unique identifier of the custom tool.

Request Body schema: application/json
required
name
string
description
string
url
string <uri>
method
string
Enum: "GET" "POST"
object
inputSchema
object
enabled
boolean

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "success": true,
  • "tool": {
    }
}

Delete Custom Tool

Permanently deletes a custom tool. The AI will no longer be able to invoke it during calls.

Authorizations:
BearerAuth
path Parameters
toolId
required
string <uuid>

The unique identifier of the custom tool.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Calls

Access call logs, transcripts, and summaries.

List Calls

Returns a paginated list of calls for the authenticated user, ordered by start time (newest first).

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of calls to return.

startAfter
string

Pagination cursor — the callId of the last item from the previous page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "calls": [
    ]
}

Get Call

Returns detailed information about a specific call, including transcript messages and summary.

Authorizations:
BearerAuth
path Parameters
callId
required
string

The unique identifier of the call.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "call": {
    }
}