# Request 1: List all actions for an agent
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here"

{
  "success": true,
  "data": [
    {
      "id": "action-uuid-1",
      "name": "Schedule Meeting",
      "label": "Schedule Meeting",
      "description": "Schedule a meeting with the customer",
      "type": "webhook",
      "input_schema": [
        {
          "name": "date",
          "type": "string",
          "required": true,
          "description": "Meeting date"
        },
        {
          "name": "time",
          "type": "string",
          "required": true,
          "description": "Meeting time"
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": "https://api.example.com/schedule",
      "authorization_url": "https://api.example.com/auth",
      "current_status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "action-uuid-2",
      "name": "Transfer Call",
      "label": "Transfer Call",
      "description": "Transfer the call to a human agent",
      "type": "transfer",
      "input_schema": [
        {
          "name": "transfer_to",
          "type": "string",
          "required": true,
          "description": "Transfer to",
          "value": "+1234567890"
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": null,
      "authorization_url": null,
      "current_status": "active",
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    },
    {
      "id": "action-uuid-3",
      "name": "Put Call on Hold",
      "label": "Put Call on Hold",
      "description": "Put the current call on hold for a specified duration",
      "type": "hold",
      "input_schema": [
        {
          "name": "hold_duration",
          "type": "integer",
          "required": true,
          "description": "Hold duration in seconds",
          "value": 30
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": null,
      "authorization_url": null,
      "current_status": "inactive",
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

GET

api

agents

{agent_id}

actions

# Request 1: List all actions for an agent
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here"

{
  "success": true,
  "data": [
    {
      "id": "action-uuid-1",
      "name": "Schedule Meeting",
      "label": "Schedule Meeting",
      "description": "Schedule a meeting with the customer",
      "type": "webhook",
      "input_schema": [
        {
          "name": "date",
          "type": "string",
          "required": true,
          "description": "Meeting date"
        },
        {
          "name": "time",
          "type": "string",
          "required": true,
          "description": "Meeting time"
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": "https://api.example.com/schedule",
      "authorization_url": "https://api.example.com/auth",
      "current_status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "action-uuid-2",
      "name": "Transfer Call",
      "label": "Transfer Call",
      "description": "Transfer the call to a human agent",
      "type": "transfer",
      "input_schema": [
        {
          "name": "transfer_to",
          "type": "string",
          "required": true,
          "description": "Transfer to",
          "value": "+1234567890"
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": null,
      "authorization_url": null,
      "current_status": "active",
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    },
    {
      "id": "action-uuid-3",
      "name": "Put Call on Hold",
      "label": "Put Call on Hold",
      "description": "Put the current call on hold for a specified duration",
      "type": "hold",
      "input_schema": [
        {
          "name": "hold_duration",
          "type": "integer",
          "required": true,
          "description": "Hold duration in seconds",
          "value": 30
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": null,
      "authorization_url": null,
      "current_status": "inactive",
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

List Actions

Retrieve all actions associated with a specific voice agent. This endpoint returns a list of webhooks, call transfers, holds, and other actions that the agent can perform during conversations.

Endpoint

GET /api/v1/agents/{agent_id}/actions

Path parameters

agent

string

required

The unique identifier of the voice agent.

Request headers

Authorization

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

Example requests

# Request 1: List all actions for an agent
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Request 2: List actions with error handling
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -w "\nHTTP Status: %{http_code}\n"

Response

Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "action-uuid-1",
      "name": "Schedule Meeting",
      "label": "Schedule Meeting",
      "description": "Schedule a meeting with the customer",
      "type": "webhook",
      "input_schema": [
        {
          "name": "date",
          "type": "string",
          "required": true,
          "description": "Meeting date"
        },
        {
          "name": "time",
          "type": "string",
          "required": true,
          "description": "Meeting time"
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": "https://api.example.com/schedule",
      "authorization_url": "https://api.example.com/auth",
      "current_status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "action-uuid-2",
      "name": "Transfer Call",
      "label": "Transfer Call",
      "description": "Transfer the call to a human agent",
      "type": "transfer",
      "input_schema": [
        {
          "name": "transfer_to",
          "type": "string",
          "required": true,
          "description": "Transfer to",
          "value": "+1234567890"
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": null,
      "authorization_url": null,
      "current_status": "active",
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    },
    {
      "id": "action-uuid-3",
      "name": "Put Call on Hold",
      "label": "Put Call on Hold",
      "description": "Put the current call on hold for a specified duration",
      "type": "hold",
      "input_schema": [
        {
          "name": "hold_duration",
          "type": "integer",
          "required": true,
          "description": "Hold duration in seconds",
          "value": 30
        }
      ],
      "config": null,
      "action_trigger": null,
      "url": null,
      "authorization_url": null,
      "current_status": "inactive",
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

Response fields

success

boolean

required

Indicates if the operation was successful.

data

array

required

Array of action objects associated with the agent.

Show Action Object

string

required

Unique identifier for the action.

name

string

required

The name of the action.

label

string

required

Display label for the action.

description

string

required

What the action does.

type

string

required

Type of action. Options: webhook, transfer, hold, external.

input_schema

array

required

Array of input parameters required for the action.

config

object

Configuration object for the action (if applicable).

action_trigger

object

Trigger conditions for the action (if applicable).

url

string

Webhook URL for webhook-type actions.

authorization_url

string

Authorization URL for webhook-type actions.

current_status

string

required

Current status of the action. Options: active, inactive.

created_at

string

required

ISO 8601 timestamp when the action was created.

updated_at

string

required

ISO 8601 timestamp when the action was last updated.

Error responses

404 Not Found

{
  "success": false,
  "message": "Agent not found"
}

401 Unauthorized

{
  "success": false,
  "message": "Unauthenticated."
}

403 Forbidden

{
  "success": false,
  "message": "You are not authorized to access this agent's actions."
}

500 Server Error

{
  "success": false,
  "message": "Internal server error."
}

Error codes

Code	Description	HTTP Status
`AGENT_NOT_FOUND`	Specified agent does not exist	404
`INVALID_TOKEN`	Authentication token is invalid or missing	401
`UNAUTHORIZED`	User does not have permission to access this agent	403
`SERVER_ERROR`	Internal server error occurred	500

Important notes

Empty response is normal. If an agent has no actions configured, the response will be an empty array [] rather than an error.

Status filtering. The response includes both active and inactive actions. You can filter by current_status on the client side if needed.

Action types vary. Different action types (webhook, transfer, hold) have different properties and configurations.

Create/Update Action: POST /api/v1/agents/{agent_id}/actions
Delete Action: DELETE /api/v1/agents/{agent_id}/actions/{action_id}
Get Agent: GET /api/v1/agents/{agent_id}
List Agents: GET /api/v1/agents

Delete Training Create/Update Action

​List Actions

​Endpoint

​Path parameters

​Request headers

​Example requests

​Response

​Success Response (200 OK)

​Response fields

​Error responses

​404 Not Found

​401 Unauthorized

​403 Forbidden

​500 Server Error

​Error codes

​Important notes

​Related endpoints

List Actions

Endpoint

Path parameters

Request headers

Example requests

Response

Success Response (200 OK)

Response fields

Error responses

404 Not Found

401 Unauthorized

403 Forbidden

500 Server Error

Error codes

Important notes

Related endpoints