---
title: "Create Superagent"
method: POST
path: "/api/agents"
---

# Create Superagent

`POST /api/agents`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/agents`
- Auth: HTTP bearer

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Creates a Superagent that you own. Send it messages through [Create Superagent conversation](/api-reference/create-superagent-conversation), using the `id` this returns as `agent_id`.

The agent is created in your access token's workspace, or in your default workspace when you use a personal API key. The request waits while the agent's workspace is set up, which takes a few seconds. If setup fails, the agent is removed and you can retry. A retry after a lost response creates a second agent. A personal access token limited to selected apps can't call the new agent afterwards, because the agent isn't on its list.

This endpoint is limited to 5 requests per minute, shared with [Create app](/api-reference/create-app).

<Note>This endpoint accepts a personal API key or personal access token belonging to a workspace editor. A read-only key is refused, and workspace API keys are not accepted.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time. Send only the fields documented here. Other request fields are not supported and their behavior can change.</Warning>

## Request body

- CreateSuperagent
  - `name` string, required: Name of the agent. Leading and trailing spaces are removed.
  - `description` string, nullable: Short description of what the agent is for.
  - `logo_url` string, nullable: URL of the agent's logo image.

## Response `201`

The new agent.

- Superagent
  - `id` string, required: ID of the agent. Use it as `agent_id` in the other Superagent endpoints, such as [Create Superagent conversation](/api-reference/create-superagent-conversation).
  - `name` string, required: Name of the agent.
  - `description` string, nullable: Description of the agent, or `null` if none was set.
  - `logo_url` string, nullable: URL of the agent's logo, or `null` if none was set.

## Other responses

- `400`: You have no workspace to create the agent in.
- `401`: Missing or invalid credentials.
- `403`: You're a viewer or guest in the workspace, you aren't a member of it, Superagents are turned off in it, or your API key is read-only.
- `422`: `name` is missing or blank, a field is too long, or the body has an unknown field.
- `429`: Rate limit exceeded (5 requests per minute, shared with Create app).

## Changes

- **2026-10-11** `80287813ab84`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-10** `fc604cdcc3a2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/agents/post.md)

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) - [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/idealspot/apis/base44-app-management-api/revisions/b5b4ebd82a1e?raw)