> ## 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 workspace agents with their IDs and serialized prompt text.
Returns every non-deleted agent in the workspace tied to your API key, sorted by most recently updated first. Each item includes the agent ID, name, creation timestamp, and serialized planning, guideline, email-channel, and chat-channel prompts.
Use this endpoint to look up the `botId` values accepted by [List conversations](/en/api-reference/list-conversations), [Generate Answer](/en/api-reference/generate-answer), and other public routes that scope behavior to one agent. For structured prompt sections, use [Get prompts](/en/api-reference/get-prompts).
For the full agent endpoint family, including create and delete routes, see [Agents](/en/api-reference/agents). Use [Analytics](/en/api-reference/analytics) for agent-level reporting endpoints and [Prompts](/en/api-reference/prompts) for prompt-version routes.
This endpoint returns all agents in a single response, there is no pagination, filtering, or limit.
<Info>
The endpoint path uses `/bots` because that is the current API contract. In the dashboard and the rest of these docs, the same workspace entities are called agents.
</Info>
## Headers
<ParamField header="Authorization" type="string" required>
Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `read` scope.
</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="datetime">
ISO 8601 timestamp for when the agent was created.
</ResponseField>
<ResponseField name="hcPlanningPrompt" type="string">
Serialized planning prompt built from enabled planning sections and subsections.
</ResponseField>
<ResponseField name="hcGuidelinePrompt" type="string">
Serialized main-guidelines prompt built from enabled guideline sections and subsections.
</ResponseField>
<ResponseField name="hcEmailChannelPrompt" type="string">
Serialized prompt for enabled email-channel sections. An empty string means no enabled email prompt content is available.
</ResponseField>
<ResponseField name="hcChatChannelPrompt" type="string">
Serialized prompt for enabled chat-channel sections. An empty string means no enabled chat prompt content is available.
</ResponseField>
</Expandable>
</ResponseField>
<Note>
The four prompt fields are rendered strings intended for inspection or downstream text use. They include enabled prompt sections serialized from the agent prompt configuration. To edit prompts or preserve section IDs and ordering, read the structured arrays from [Get prompts](/en/api-reference/get-prompts).
</Note>
<ResponseExample>
~~~json 200 OK theme={null}
[
{
"id": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
"name": "Support Agent",
"createdAt": "2026-05-20T12:34:56.789Z",
"hcPlanningPrompt": "<PLANNING>\n\n## PLAN THE RESPONSE\n...\n\n</PLANNING>\n\n\n",
"hcGuidelinePrompt": "<MAIN GUIDELINES>\n\n## ANSWER ACCURATELY\n...\n\n</MAIN GUIDELINES>\n\n\n",
"hcEmailChannelPrompt": "<EMAIL>\n\n## FORMAT\n...\n\n</EMAIL>\n\n\n",
"hcChatChannelPrompt": "<CHAT>\n\n## FORMAT\n...\n\n</CHAT>\n\n\n"
},
{
"id": "0f4da4fe-b2ae-4787-8c3b-854f36d9eb1b",
"name": "Billing Agent",
"createdAt": "2026-05-12T08:41:10.201Z",
"hcPlanningPrompt": "<PLANNING>\n\n## PLAN THE RESPONSE\n...\n\n</PLANNING>\n\n\n",
"hcGuidelinePrompt": "<MAIN GUIDELINES>\n\n## ANSWER ACCURATELY\n...\n\n</MAIN GUIDELINES>\n\n\n",
"hcEmailChannelPrompt": "",
"hcChatChannelPrompt": "<CHAT>\n\n## FORMAT\n...\n\n</CHAT>\n\n\n"
}
]
~~~
~~~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 does not have the required scope for this operation",
"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>
## Related topics
- [List agent assignments](/en/api-reference/list-attribute-agents.md)
- [List conversations](/en/api-reference/list-conversations.md)
- [Delete agent](/en/api-reference/delete-agent.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
Agents