Guides

List Agents

Suggest Edits

List Agents

The Flyflow API allows you to retrieve a list of agents associated with your account by making a GET request to the /agents endpoint. This endpoint returns paginated results, allowing you to specify the number of agents to retrieve and navigate through the agent list.

Request

Endpoint

GET /agents

Headers

  • Authorization: The API key prefixed with Bearer. Example: Bearer your_api_key.

Query Parameters

  • cursor (string, optional): The cursor value to start the list from. This value is returned in the response of the previous request and allows for pagination.
  • limit (integer, optional): The maximum number of agents to return in the response. The default value is 10, and the maximum allowed value is 100.

cURL Example

curl -X GET \
  -H "Authorization: Bearer your_api_key" \
  "https://api.flyflow.dev/v1/agents?limit=20"

Python Client Example

from flyflowclient import Flyflow

client = Flyflow(api_key='your_api_key')

agents = client.list_agents(limit=20)

for agent in agents['agents']:
    print(agent)

Response

Status Codes

  • 200 OK: The list of agents was successfully retrieved.
  • 401 Unauthorized: The API key is missing or invalid.
  • 500 Internal Server Error: An unexpected error occurred on the server side.

Response Body

If the list of agents is successfully retrieved, the response body will be a JSON object containing the paginated agent results:

{
  "num_items": 20,
  "cursor": "next_cursor_value",
  "agents": [
    {
      "id": "agent_id_1",
      "name": "Agent 1",
      "phone_number": "+1234567890",
      "system_prompt": "System prompt for Agent 1",
      "initial_message": "Initial message for Agent 1",
      "llm_model": "gpt-3.5-turbo",
      "voice_id": "voice_id_1",
      "webhook": "https://webhook-url-1.com",
      "tools": [],
      "filler_words": true,
      "filler_words_whitelist": [],
      "created_at": "timestamp",
      "updated_at": "timestamp"
    },
    {
      "id": "agent_id_2",
      "name": "Agent 2",
      "phone_number": "+9876543210",
      "system_prompt": "System prompt for Agent 2",
      "initial_message": "Initial message for Agent 2",
      "llm_model": "gpt-4o",
      "voice_id": "voice_id_2",
      "webhook": "https://webhook-url-2.com",
      "tools": [],
      "filler_words": false,
      "filler_words_whitelist": [],
      "created_at": "timestamp",
      "updated_at": "timestamp"
    },
    ...
  ]
}
  • num_items (integer): The total number of agents returned in the response.
  • cursor (string): The cursor value to use for retrieving the next page of results (if applicable).
  • agents (array): An array of agent objects representing the retrieved agents.
    • id (string): The unique identifier of the agent.
    • name (string): The name of the agent.
    • phone_number (string): The phone number associated with the agent.
    • system_prompt (string): The system prompt for the agent.
    • initial_message (string): The initial message for the agent.
    • llm_model (string): The language model used by the agent (e.g., "gpt-3.5-turbo", "gpt-4o").
    • voice_id (string): The identifier of the voice used by the agent.
    • webhook (string): The webhook URL for the agent (if applicable).
    • tools (array): An array of tools available to the agent.
    • filler_words (boolean): Indicates whether filler words are enabled for the agent.
    • filler_words_whitelist (array): An array of whitelisted filler words for the agent.
    • created_at (string): The timestamp indicating when the agent was created.
    • updated_at (string): The timestamp indicating when the agent was last updated.

Error Handling

If an error occurs while retrieving the list of agents, the API will return an appropriate error response with a corresponding status code and error message in the response body.

For example, if the API key is missing or invalid:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Make sure to handle errors appropriately in your application and provide the necessary authentication and query parameters.

Pagination

The Flyflow API supports pagination for the /agents endpoint to handle large numbers of agents efficiently. The response includes a cursor value that represents the starting point for the next page of results. To retrieve the next page, include the cursor value as a query parameter in the subsequent request.

For example, to retrieve the next page of agents:

curl -X GET \
  -H "Authorization: Bearer your_api_key" \
  "https://api.flyflow.dev/v1/agents?cursor=next_cursor_value&limit=20"

Continue using the cursor value from each response to navigate through the entire agent list.

Conclusion

Retrieving a list of agents using the Flyflow API is a straightforward process. By making a GET request to the /agents endpoint, you can fetch paginated results of agents associated with your account. The API provides query parameters to control the number of agents returned. The response includes a cursor value for pagination, allowing you to retrieve subsequent pages of results. Remember to handle errors and provide the necessary authentication and query parameters to ensure a smooth integration with the Flyflow platform.

Updated 6 months ago