curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/public' \
--header 'Authorization: Bearer fini_your_api_key' \
--header 'Content-Type: application/json' \
--data '{"name":"Support Agent"}'
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/bots/public",
headers={
"Authorization": "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
json={"name": "Support Agent"},
)
agent = response.json()
const response = await fetch("https://api-prod.usefini.com/v2/bots/public", {
method: "POST",
headers: {
Authorization: "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "Support Agent" }),
});
const agent = await response.json();
{
"id": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
"name": "Support Agent",
"companyId": "5c9c6da2-0ed8-4f75-8b21-7c5fcb0bb14a",
"createdAt": "2026-07-21T06:12:31.456Z",
"updatedAt": "2026-07-21T06:12:31.456Z",
"hcFlowMode": "default"
}
Agents
Create agent
Create a new agent in the workspace.
POST
/
v2
/
bots
/
public
curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/public' \
--header 'Authorization: Bearer fini_your_api_key' \
--header 'Content-Type: application/json' \
--data '{"name":"Support Agent"}'
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/bots/public",
headers={
"Authorization": "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
json={"name": "Support Agent"},
)
agent = response.json()
const response = await fetch("https://api-prod.usefini.com/v2/bots/public", {
method: "POST",
headers: {
Authorization: "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "Support Agent" }),
});
const agent = await response.json();
{
"id": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
"name": "Support Agent",
"companyId": "5c9c6da2-0ed8-4f75-8b21-7c5fcb0bb14a",
"createdAt": "2026-07-21T06:12:31.456Z",
"updatedAt": "2026-07-21T06:12:31.456Z",
"hcFlowMode": "default"
}
Creates a new agent in the workspace tied to your API key and returns the stored agent object.
Agent names must be unique within the workspace. If another agent already has the same name, this route returns
400 Bad Request.
Headers
string
required
Bearer token containing your Fini workspace API key. Format:
Bearer fini_... The key needs write scope.string
required
application/jsonBody parameters
string
required
Name for the new agent.
curl --request POST \
--url 'https://api-prod.usefini.com/v2/bots/public' \
--header 'Authorization: Bearer fini_your_api_key' \
--header 'Content-Type: application/json' \
--data '{"name":"Support Agent"}'
import requests
response = requests.post(
"https://api-prod.usefini.com/v2/bots/public",
headers={
"Authorization": "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
json={"name": "Support Agent"},
)
agent = response.json()
const response = await fetch("https://api-prod.usefini.com/v2/bots/public", {
method: "POST",
headers: {
Authorization: "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "Support Agent" }),
});
const agent = await response.json();
Response
Returns the created agent object.string
Agent ID. Pass this value as
botId on endpoints that scope behavior to one agent.string
Agent name.
string
Workspace company ID that owns the agent.
datetime
ISO 8601 timestamp for when the agent was created.
datetime
ISO 8601 timestamp for when the agent was last updated.
string | null
Agent flow mode when present. Current values are
default and fast_answer.{
"id": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
"name": "Support Agent",
"companyId": "5c9c6da2-0ed8-4f75-8b21-7c5fcb0bb14a",
"createdAt": "2026-07-21T06:12:31.456Z",
"updatedAt": "2026-07-21T06:12:31.456Z",
"hcFlowMode": "default"
}
Errors
400 Bad Request
400 Bad Request
The body is malformed or another agent with the same name already exists in the workspace.
401 Unauthorized
401 Unauthorized
The API key is missing, malformed, revoked, or invalid.
403 Forbidden
403 Forbidden
The API key does not include the
write scope required for this route.500 Internal Server Error
500 Internal Server Error
Fini failed while creating the agent.
Was this page helpful?