> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Agent

> Create an agent with empty dev, staging, and production environments.

### Overview

Creates an agent and its three environments (`dev`, `staging`, `production`) in one step. The environments start unpinned; save a version with [Create Agent Version](https://docs.bland.ai/api-v2/post/agents-id-versions.md) and promote it to pin one. To build an agent from the dashboard instead, see [Build your first agent](https://docs.bland.ai/build-your-first-agent.md).

Requires an admin, owner, operator, or prompter role.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

**name** `string` *required*

Display name for the agent. Must be non-empty after trimming whitespace. Returns `400 INVALID_NAME` otherwise.

### Response

Returns `201` on success.

**data.agent** `object`

The new agent.

**agent object**

**id** `string`

Unique identifier for the agent.

**org\_id** `string`

The organization that owns the agent.

**name** `string`

The agent's display name.

**created\_by** `string | null`

ID of the user who created the agent, or `null` when created with an org-level key.

**created\_at** `string`

ISO 8601 timestamp of creation.

**updated\_at** `string`

ISO 8601 timestamp of the last update.

**deleted\_at** `null`

Always `null` on a live agent.

**data.environments** `array`

The agent's three environments, all unpinned.

**environment object**

**id** `string`

Unique identifier for the environment.

**env\_type** `string`

One of `dev`, `staging`, `production`.

**current\_version\_id** `string | null`

The version this environment is pinned to. `null` until a version is published or promoted into it.

**errors** `null | array`

`null` on success, or a list of error objects if the request failed.

```json Response theme={null}
{
  "data": {
    "agent": {
      "id": "2f2750b7-fed3-4798-992a-421ccf8b93b2",
      "org_id": "45794f66-94ca-44a2-9248-202c5ff22717",
      "name": "Front desk",
      "created_by": "bd8ae00b-c51d-4364-b1b3-245ad579c44a",
      "created_at": "2026-09-10T22:59:51.569Z",
      "updated_at": "2026-09-10T22:59:51.569Z",
      "deleted_at": null
    },
    "environments": [
      {
        "id": "7a043546-b896-4680-80e4-5eb9cbde6977",
        "env_type": "dev",
        "current_version_id": null
      },
      {
        "id": "ab412aa2-8827-4e12-ad45-9a964c2c8690",
        "env_type": "staging",
        "current_version_id": null
      },
      {
        "id": "1595512d-ea18-4692-a40b-6c90932396b4",
        "env_type": "production",
        "current_version_id": null
      }
    ]
  },
  "errors": null
}
```

```json Invalid Name theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "INVALID_NAME",
      "message": "name must be a non-empty string"
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.