curl --request GET \
--url 'https://api-prod.usefini.com/v2/bots/public' \
--header 'Authorization: Bearer fini_your_api_key'
import requests
response = requests.get(
"https://api-prod.usefini.com/v2/bots/public",
headers={"Authorization": "Bearer fini_your_api_key"},
)
agents = response.json()
const response = await fetch(
"https://api-prod.usefini.com/v2/bots/public",
{
headers: {
Authorization: "Bearer fini_your_api_key",
},
}
);
const agents = await response.json();
[
{
"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"
}
]
{
"statusCode": 401,
"message": "Invalid or revoked API key",
"error": "Unauthorized"
}
{
"statusCode": 403,
"message": "API key does not have the required scope for this operation",
"error": "Forbidden"
}
Agents
List agents
List workspace agents with their IDs and serialized prompt text.
GET
/
v2
/
bots
/
public
curl --request GET \
--url 'https://api-prod.usefini.com/v2/bots/public' \
--header 'Authorization: Bearer fini_your_api_key'
import requests
response = requests.get(
"https://api-prod.usefini.com/v2/bots/public",
headers={"Authorization": "Bearer fini_your_api_key"},
)
agents = response.json()
const response = await fetch(
"https://api-prod.usefini.com/v2/bots/public",
{
headers: {
Authorization: "Bearer fini_your_api_key",
},
}
);
const agents = await response.json();
[
{
"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"
}
]
{
"statusCode": 401,
"message": "Invalid or revoked API key",
"error": "Unauthorized"
}
{
"statusCode": 403,
"message": "API key does not have the required scope for this operation",
"error": "Forbidden"
}
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, Generate Answer, and other public routes that scope behavior to one agent. For structured prompt sections, use Get prompts.
For the full agent endpoint family, including create and delete routes, see Agents. Use Analytics for agent-level reporting endpoints and Prompts for prompt-version routes.
This endpoint returns all agents in a single response, there is no pagination, filtering, or limit.
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.Headers
string
required
Bearer token containing your Fini workspace API key. Format:
Bearer fini_... The key needs read scope.curl --request GET \
--url 'https://api-prod.usefini.com/v2/bots/public' \
--header 'Authorization: Bearer fini_your_api_key'
import requests
response = requests.get(
"https://api-prod.usefini.com/v2/bots/public",
headers={"Authorization": "Bearer fini_your_api_key"},
)
agents = response.json()
const response = await fetch(
"https://api-prod.usefini.com/v2/bots/public",
{
headers: {
Authorization: "Bearer fini_your_api_key",
},
}
);
const agents = await response.json();
Response
The response is a top-level array of agent objects.array
Array of agents in the workspace.
Show agent object
Show agent object
string
The agent’s
botId. Pass this value as botId on endpoints that support agent-level filtering.string
Agent name as configured in the workspace.
datetime
ISO 8601 timestamp for when the agent was created.
string
Serialized planning prompt built from enabled planning sections and subsections.
string
Serialized main-guidelines prompt built from enabled guideline sections and subsections.
string
Serialized prompt for enabled email-channel sections. An empty string means no enabled email prompt content is available.
string
Serialized prompt for enabled chat-channel sections. An empty string means no enabled chat prompt content is available.
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.
[
{
"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"
}
]
{
"statusCode": 401,
"message": "Invalid or revoked API key",
"error": "Unauthorized"
}
{
"statusCode": 403,
"message": "API key does not have the required scope for this operation",
"error": "Forbidden"
}
Errors
401 Unauthorized
401 Unauthorized
The workspace API key is missing, malformed, revoked, or invalid. Confirm you are sending
Authorization: Bearer fini_... with the full key.403 Forbidden
403 Forbidden
The key is valid but doesn’t include the
read scope, or it’s scoped to a different workspace.The response is an empty array
The response is an empty array
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.
Was this page helpful?