> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List agents

> List the agents in the workspace tied to your API key so you can map names to bot IDs.

Returns every agent in the workspace tied to your API key, sorted by creation time, newest first. Use it to look up the `botId` values accepted by [List conversations](/en/api-reference/list-conversations), [Generate Answer](/en/api-reference/generate-answer), and any other public route that scopes behavior to one agent.

This endpoint returns all agents in a single response, there is no pagination, filtering, or limit.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token containing your Fini workspace API key. Format: `Bearer fini_...`
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api-prod.usefini.com/v2/bots/public' \
    --header 'Authorization: Bearer fini_your_api_key'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api-prod.usefini.com/v2/bots/public",
      headers={"Authorization": "Bearer fini_your_api_key"},
  )
  agents = response.json()
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api-prod.usefini.com/v2/bots/public",
    {
      headers: {
        Authorization: "Bearer fini_your_api_key",
      },
    }
  );
  const agents = await response.json();
  ```
</RequestExample>

## Response

The response is a top-level array of agent objects.

<ResponseField name="[]" type="array">
  Array of agents in the workspace.

  <Expandable title="agent object">
    <ResponseField name="id" type="string">
      The agent's `botId`. Pass this value as `botId` on endpoints that support agent-level filtering.
    </ResponseField>

    <ResponseField name="name" type="string">
      Agent name as configured in the workspace.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp for when the agent was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  [
    {
      "id": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
      "name": "Support Agent",
      "createdAt": "2026-05-20T12:34:56.789Z"
    },
    {
      "id": "0f4da4fe-b2ae-4787-8c3b-854f36d9eb1b",
      "name": "Billing Agent",
      "createdAt": "2026-05-12T08:41:10.201Z"
    }
  ]
  ```

  ```json 401 Unauthorized theme={null}
  {
    "statusCode": 401,
    "message": "Invalid or revoked API key",
    "error": "Unauthorized"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "statusCode": 403,
    "message": "API key is missing the required `read` scope",
    "error": "Forbidden"
  }
  ```
</ResponseExample>

## Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock">
    The workspace API key is missing, malformed, revoked, or invalid. Confirm you are sending `Authorization: Bearer fini_...` with the full key.
  </Accordion>

  <Accordion title="403 Forbidden" icon="shield-halved">
    The key is valid but doesn't include the `read` scope, or it's scoped to a different workspace.
  </Accordion>

  <Accordion title="The response is an empty array" icon="circle-question">
    The key's workspace has no non-deleted agents available to the public route. Create an agent in the dashboard or confirm you're authenticating against the right workspace.
  </Accordion>
</AccordionGroup>