Public API

The public API connects Tala to your CRM, n8n, Make, Zapier, or another server-side application. Its base URL is https://api.tala-assistant.com/api/v1/public.

Create a limited API key

In Tala, open API keys, create a key and select its permissions and the agents it may access. A key never grants access to agents you have not selected, including agents created later. Keys expire after 180 days by default. You may choose another future date or explicitly select no expiration. The full key is displayed only once. Store it securely on your server; do not put it in browser code, URLs, or a public repository. Revoke a key from the same page when it is no longer needed. Send it in the X-API-Key header on every request:

curl "https://api.tala-assistant.com/api/v1/public/agents" \
  -H "X-API-Key: YOUR_API_KEY"

Method and path	Required permission	Purpose
`GET /agents`	`agents:read`	List active, authorized agents
`POST /agents/{agent_id}/calls`	`calls:create`	Start an outbound call
`GET /agents/{agent_id}/calls`	`calls:read`	Read an authorized agent’s call history
`GET /calls/{call_id}`	`calls:read`	Read one authorized call

Agent and call identifiers are stable UUID strings. Obtain the agent identifier from GET /agents and the call identifier from a creation response or call history. Use them exactly as returned.

List agents

GET /agents returns only the active agents selected for your key:

{
  "data": [
    {"id": "5a7fc653-56f2-436f-a743-cc12ac412bfd", "name": "Accueil"}
  ]
}

Start an outbound call

The agent must be active and outbound calling must be available for your account.

curl -X POST "https://api.tala-assistant.com/api/v1/public/agents/YOUR_AGENT_ID/calls" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+33612345678",
    "initial_context": {"customer_reference": "CRM-42", "reason": "Demande de devis"}
  }'

Field	Required	Description
`phone_number`	Yes	Valid international E.164 number, with `+` and country code, without spaces or punctuation
`initial_context`	No	Business variables available to the agent during the call

The context variable phone_number is kept in sync with the destination above; a different value supplied inside initial_context does not override it. The response is 202 Accepted:

{
  "id": "17541952-aa5d-4a14-92af-e09908e8178c",
  "agent_id": "5a7fc653-56f2-436f-a743-cc12ac412bfd",
  "status": "pending"
}

Acceptance does not mean the recipient answered or the conversation finished. Read the returned call identifier to follow its progress. Each POST creates a new call attempt: do not automatically retry a request whose outcome is unknown, as that could call the recipient twice. Requests must be uncompressed JSON of at most 64 KiB. Only the two documented body fields are accepted. Context is limited to five nesting levels, 100 object keys in total, 100 items per array, and 4 KiB of UTF-8 text per string. System-reserved names and non-finite numbers are rejected. Prefer business-specific variable names such as customer_reference or appointment_date.

Read call results

GET /calls/{call_id} returns the following business data. Fields unavailable for a call are null or empty objects.

{
  "id": "17541952-aa5d-4a14-92af-e09908e8178c",
  "agent_id": "5a7fc653-56f2-436f-a743-cc12ac412bfd",
  "status": "completed",
  "created_at": "2026-09-04T10:00:00Z",
  "duration_seconds": 42.5,
  "disposition": "completed",
  "caller": {"phone_number": "+33612345678", "direction": "outbound"},
  "initial_context": {"customer_reference": "CRM-42"},
  "gathered_context": {"callback_needed": true},
  "call_overview": {
    "headline": "Demande de rappel",
    "summary": "La personne souhaite être rappelée demain.",
    "topic_label": "Demande commerciale",
    "next_action_label": "Rappeler",
    "appointment_status": "requested"
  }
}

status is pending, in_progress, completed, or failed. Duration may appear after the call has finished. disposition is a recognized outcome (completed, no_answer, busy, voicemail, failed, cancelled, or XFER for a transfer), or null when no supported outcome is available. caller.phone_number identifies the other party; it may be absent, for example when a number is withheld. call_overview contains available business summaries and may be null. Returned context is deliberately limited: initial_context includes only business variables declared in the agent’s context settings, and gathered_context includes only its declared extraction variables. Extra submitted variables can guide the conversation without automatically becoming readable through the API. Reserved fields are removed recursively. Recordings and transcripts are not included in this API.

List and paginate calls

GET /agents/{agent_id}/calls includes the authorized agent’s recorded sessions, regardless of how they were started. Results are ordered from newest to oldest. An archived agent’s history remains readable by keys that already authorize it, but it is no longer listed by GET /agents and cannot start new calls.

Query parameter	Description
`limit`	Page size, from 1 to 100; default 50
`cursor`	The `next_cursor` returned by the previous page
`status`	One of the four documented statuses
`created_after`	Exclusive lower date bound, including a timezone
`created_before`	Exclusive upper date bound, including a timezone

The response has the form {"data": [...], "next_cursor": "..."}. Each item has the same fields as a single-call response. When next_cursor is null, there are no more results. Keep the same filters when requesting another page. Date bounds refer to call creation, not completion.

Limits and errors

Creation is limited to 60 requests per minute per key. The three read endpoints share a limit of 120 requests per minute per key. Unsuccessful authentication attempts are limited to 20 per minute per source address. Limits apply across agents and use rolling one-minute windows. A 429 response includes Retry-After: 60.

HTTP status	Meaning
`200`	Read succeeded
`202`	Call creation accepted
`401`	Key missing, invalid, expired, or revoked
`402`	Call creation unavailable for the account
`403`	Key lacks the required permission
`404`	Agent or call unavailable to this key
`409`	Call capacity temporarily unavailable
`410`	Retired endpoint
`413`	Request exceeds the size limit
`415`	Unsupported content type or encoding
`422`	Invalid body, date, filter, or cursor
`429`	Rate limit exceeded
`503`	Service temporarily unavailable

Errors have the form {"detail": "Invalid request"}. An unavailable identifier produces the same 404 whether it is absent or outside the key’s access. Responses must not be cached.

Migration from the previous API

The old POST /api/v1/public/agent/{trigger_uuid} endpoint is retired and returns 410. Previously issued unrestricted keys cannot access the new endpoints. Create a new limited key and use the agent UUID returned by GET /agents; a previous trigger identifier is not an agent identifier.

Getting Started

Workflows

Integrations

Phone Numbers

Pricing

Features

API

Create a limited API key

List agents

Start an outbound call

Read call results

List and paginate calls

Limits and errors

Migration from the previous API

​Create a limited API key

​List agents

​Start an outbound call

​Read call results

​List and paginate calls

​Limits and errors

​Migration from the previous API

Create a limited API key

List agents

Start an outbound call

Read call results

List and paginate calls

Limits and errors

Migration from the previous API