Skip to main content
GET
/
api
/
v1
/
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"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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. You can find this in your dashboard under Voice Agents.

​
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.

​
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

CodeDescriptionHTTP Status
AGENT_NOT_FOUNDSpecified agent does not exist404
INVALID_TOKENAuthentication token is invalid or missing401
UNAUTHORIZEDUser does not have permission to access this agent403
SERVER_ERRORInternal server error occurred500

​
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.

​
Best Practices

  1. Cache action data - Action data doesn’t change frequently, so consider caching the response
  2. Handle empty responses - Always check if the data array is empty before processing
  3. Monitor action status - Check the current_status to ensure actions are active
  4. Understand action types - Different action types require different handling in your application
  5. Error handling - Implement proper error handling for authentication and authorization failures
  6. Rate limiting - Be mindful of API rate limits when fetching action data
  • 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