REST API

Everything you can do in the AI Agents dashboard can also be done through a REST API: create and edit agents, flows, tools and documents, read the conversations they have had, and monitor or control the conversations that are running now.

This page is an overview of what the API offers and how to authenticate with it. Every endpoint, parameter and response is documented in the API reference:

Two related interfaces are documented separately: Webhooks push events to your service as a conversation progresses, and the MCP server exposes the same configuration operations to AI assistants such as Claude.

API reference

The API reference is an interactive Swagger UI page that documents every endpoint that an integration can call, including each parameter and each response body, with examples that can be sent as they are:

LiveHub AI Agents - REST API

The reference is the authoritative description of what the API accepts and returns, and it is always up to date because the platform serves it directly. This page explains the concepts; the reference describes the individual operations.

Swagger UI can also send the requests for you. Click Authorize and either paste an access token or enter your API client's Client Id and Client Secret to have a token fetched for you. Every endpoint then provides a working Try it out button.

To work with the specification itself, for example to generate a client or to import the API into Postman or Insomnia, download openapi.json. It is an OpenAPI 3.1 document.

Base URL

https://livehub.audiocodes.io/ai-framework-management/api/v1

If you are not using the public cloud service, replace the host with the address of your own environment.

Authentication

The API is secured with OAuth 2.0 access tokens. You exchange the credentials of a LiveHub API client for a short-lived token, and then send that token with every request. For the full LiveHub description, see Secured REST API.

1. Create an API client

Your client_id and client_secret belong to a LiveHub API client, which you create in the Access control (IAM) screen:

  1. Click your account name at the top of the screen, then click Access control (IAM).
  2. Select API Clients in the left menu and click Add API Client. Enter a name, then copy the generated Client Id and Client Secret. The secret is displayed only once.
  3. Grant the client a role: select User groups, edit the group whose permissions the client should have (for example Administrator), open the API Clients tab and add the new client.

The role that you grant here determines what the token is allowed to do. See the role table below.

2. Get an access token

POST https://livehub.audiocodes.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Note: The token endpoint is on the LiveHub gateway (/oauth/token), not under /ai-framework-management.

3. Call the API

Send the token as a bearer token with every request:

curl https://livehub.audiocodes.io/ai-framework-management/api/v1/live_conversations \
  --header "Authorization: Bearer <access_token>"

A token is valid for one hour. Request a new token before the current one expires, because a request that carries an expired token is rejected with 401.

Whichever endpoint you call, a token can only access the data of its own account.

WebSocket connections are authenticated differently. See Streaming the logs.

Roles

Each operation requires a role, which the API client inherits from the group that it was added to:

Role Allows
LIVEHUB/AIFRAMEWORK/READ Reading any data: listing agents, reading conversations, monitoring a live conversation
LIVEHUB/AIFRAMEWORK/CREATE Creating entities
LIVEHUB/AIFRAMEWORK/UPDATE Changing entities, and acting on a live conversation
LIVEHUB/AIFRAMEWORK/DELETE Deleting entities and conversations

Of the built-in user groups, Administrator has all four roles and Monitor has only READ. A Monitor client can therefore watch a live conversation, but cannot end it.

Configuration

Every entity that you can build in the dashboard can be created, read, updated and deleted through the API, and all of them follow the same pattern under /api/v1:

GET    /agents        list
GET    /agents/{id}   read one
POST   /agents        create
PUT    /agents/{id}   update
DELETE /agents/{id}   delete

The same five operations are available for each of the following entities:

Entity Endpoint
Agents /agents
Flows /flows
Tools /tools
Documents /documents
Models /models
Post-call analysis /post_call_analysis
Test suites /test_suites

Listing operations accept the filter, sort, limit and page parameters. Each listing operation in the reference specifies the fields that it can be filtered by, with examples. In addition to plain CRUD, the reference documents the remaining configuration operations: cloning an entity, testing a tool before an agent uses it, running test suites, managing the prompt history of an agent, and exporting or restoring the configuration of an account as an archive.

Conversations

Every conversation is stored when it ends, together with its full log. This is the data behind the dashboard's Logs screen. The /conversations endpoints allow you to:

The content of each log entry, and the behavior of the entries that are hidden or masked by sensitive-information handling, are described in the reference for the individual operations.

Post-call analysis results

The results that post-call analyses extract from conversations, such as summaries, sentiment and structured variables, are read from /post_call_analysis_data, either for a single conversation or as a listing that can be filtered by agent, caller and time.

Live conversations

The /live_conversations endpoints cover the conversations that are running right now. You can list these conversations, stream the log of one of them as it is generated, and intervene in a conversation: end the call, optionally with a parting message, transfer it to a person or to another number, or speak a message into it.

The commands require the UPDATE role, so a read-only client can monitor a conversation but cannot act on it. A speech-to-speech conversation accepts only the end and transfer commands, because it generates its own audio and cannot speak supplied text.

The Live Conversations group in the reference documents every operation except one, which a REST specification cannot describe:

Streaming the logs

WebSocket /api/v1/live_conversations/{conversation_id}/logs?token=<websocket_token>

A browser cannot set headers on a WebSocket handshake, so the credential is passed in the query string. For this reason it is not your access token, but a separate WebSocket token, which you request first:

curl --request POST \
  https://livehub.audiocodes.io/ai-framework-management/api/v1/websocket_token \
  --header "Authorization: Bearer <access_token>"
{
    "token": "wst_hZ3n4Kc0Q1uT8pR2vXbL9sYwE7mA6dJf0gN5iOqB3kU",
    "expires_in": 60
}

The WebSocket token is valid for about a minute and is accepted only once, so request a new token each time you are about to connect, including when you reconnect.

The connection is read-only: it delivers logs and nothing else. Use the command endpoints to act on the conversation.

Frames arrive as JSON:

event Payload When
backlog logs: a list of entries, each in the format described below Sent once, immediately after connecting, and contains everything that has been collected so far
log log: a single entry, in the same format Sent each time a new entry is generated
end reason: currently always conversation_ended Sent when the conversation has finished. The server closes the connection immediately afterwards

For example:

{"event": "backlog", "logs": [{"time": "2026-08-13T09:41:13.100000+00:00", "task_name": "Support", "from_name": "LLM", "to_name": "User", "message": "Hello, how can I help?", "label": "[Support] LLM -> User", "type": "message"}]}
{"event": "log", "log": {"time": "2026-08-13T09:41:19.870000+00:00", "task_name": "Support", "from_name": "User", "to_name": "", "message": "I'd like to check my balance", "label": "[Support] User", "type": "message"}}
{"event": "end", "reason": "conversation_ended"}

Each entry, whether it is streamed here or read later from /conversations/{conversation_id}, describes a single event:

Field Description
time The time at which the event occurred (ISO 8601)
task_name The agent, or in a flow the node, that produced the entry
from_name The source of the entry: User, LLM, a tool name, end_call, and so on
to_name The recipient of the entry, where this applies
message The utterance, or the log text
label A readable summary of the entry, for example [Support] LLM -> User
type message for something that was said, log for everything else
category The display category of a log entry: tool_call, end_call, transfer_call, warning, error, and so on

Sensitive-information handling applies to streamed entries exactly as it does to the stored transcript: a hidden entry is never streamed, and a masked entry arrives masked. Reconnecting starts the stream from the beginning, delivering the backlog first and then the live entries. Several clients can watch the same conversation at the same time without affecting each other.