> ## 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 a list of actions for a specific voice agent

# 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

<ParamField path="agent" type="string" required>
  The unique identifier of the voice agent.
</ParamField>

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

## Example requests

<RequestExample>
  ```bash theme={null}
  # 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"
  ```

  ```javascript theme={null}
  // Request 1: List all actions for an agent
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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"
  ```

  ```javascript theme={null}
  // Request 2: List actions with error handling
  try {
    const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/actions', {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer talq_your_environment_token_here'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();
    console.log('Actions:', result.data);
  } catch (error) {
    console.error('Error fetching actions:', error);
  }
  ```
</RequestExample>

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "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"
      }
    ]
  }
  ```
</ResponseExample>

### Response fields

<ResponseField name="success" type="boolean" required>
  Indicates if the operation was successful.
</ResponseField>

<ResponseField name="data" type="array" required>
  Array of action objects associated with the agent.

  <Expandable title="Action Object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the action.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      The name of the action.
    </ResponseField>

    <ResponseField name="label" type="string" required>
      Display label for the action.
    </ResponseField>

    <ResponseField name="description" type="string" required>
      What the action does.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Type of action. Options: `webhook`, `transfer`, `hold`, `external`.
    </ResponseField>

    <ResponseField name="input_schema" type="array" required>
      Array of input parameters required for the action.
    </ResponseField>

    <ResponseField name="config" type="object">
      Configuration object for the action (if applicable).
    </ResponseField>

    <ResponseField name="action_trigger" type="object">
      Trigger conditions for the action (if applicable).
    </ResponseField>

    <ResponseField name="url" type="string">
      Webhook URL for webhook-type actions.
    </ResponseField>

    <ResponseField name="authorization_url" type="string">
      Authorization URL for webhook-type actions.
    </ResponseField>

    <ResponseField name="current_status" type="string" required>
      Current status of the action. Options: `active`, `inactive`.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 timestamp when the action was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      ISO 8601 timestamp when the action was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

### 404 Not Found

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Agent not found"
  }
  ```
</ResponseExample>

### 401 Unauthorized

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthenticated."
  }
  ```
</ResponseExample>

### 403 Forbidden

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "You are not authorized to access this agent's actions."
  }
  ```
</ResponseExample>

### 500 Server Error

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Internal server error."
  }
  ```
</ResponseExample>

## 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

<Info>
  **Empty response is normal.** If an agent has no actions configured, the response will be an empty array `[]` rather than an error.
</Info>

<Info>
  **Status filtering.** The response includes both active and inactive actions. You can filter by `current_status` on the client side if needed.
</Info>

<Info>
  **Action types vary.** Different action types (webhook, transfer, hold) have different properties and configurations.
</Info>

## Related endpoints

* **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`