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

# Create agent

> Create a new agent in the workspace.

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

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

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Body parameters

<ParamField body="name" type="string" required>
  Name for the new agent.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"}'
  ```

  ```python Python theme={null}
  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()
  ```

  ```javascript Node.js theme={null}
  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();
  ```
</RequestExample>

## Response

Returns the created agent object.

<ResponseField name="id" type="string">
  Agent ID. Pass this value as `botId` on endpoints that scope behavior to one agent.
</ResponseField>

<ResponseField name="name" type="string">
  Agent name.
</ResponseField>

<ResponseField name="companyId" type="string">
  Workspace company ID that owns the agent.
</ResponseField>

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

<ResponseField name="updatedAt" type="datetime">
  ISO 8601 timestamp for when the agent was last updated.
</ResponseField>

<ResponseField name="hcFlowMode" type="string | null">
  Agent flow mode when present. Current values are `default` and `fast_answer`.
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## Errors

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    The body is malformed or another agent with the same name already exists in the workspace.
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    The API key is missing, malformed, revoked, or invalid.
  </Accordion>

  <Accordion title="403 Forbidden" icon="shield-halved">
    The API key does not include the `write` scope required for this route.
  </Accordion>

  <Accordion title="500 Internal Server Error" icon="triangle-exclamation">
    Fini failed while creating the agent.
  </Accordion>
</AccordionGroup>