List agents

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"
}

GET

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

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

The workspace API key is missing, malformed, revoked, or invalid. Confirm you are sending Authorization: Bearer fini_... with the full key.

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

​Headers

​Response

​Errors

Headers

Response

Errors