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

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Create Superagent

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



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/agents
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/agents:
    post:
      summary: Create Superagent
      description: >-
        <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>
      operationId: create_personal_agent_api_agents_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSuperagent'
        required: true
      responses:
        '201':
          description: The new agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Superagent'
        '400':
          description: You have no workspace to create the agent in.
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            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':
          description: >-
            `name` is missing or blank, a field is too long, or the body has an
            unknown field.
        '429':
          description: Rate limit exceeded (5 requests per minute, shared with Create app).
components:
  schemas:
    CreateSuperagent:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Name of the agent. Leading and trailing spaces are removed.
          example: Sales assistant
        description:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Description
          description: Short description of what the agent is for.
          example: Answers questions about our weekly sales.
        logo_url:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Logo Url
          description: URL of the agent's logo image.
          example: https://cdn.acme.com/sales-assistant.png
      additionalProperties: false
      type: object
      required:
        - name
      title: CreateSuperagent
    Superagent:
      properties:
        id:
          type: string
          title: Id
          description: >-
            ID of the agent. Use it as `agent_id` in the other Superagent
            endpoints, such as [Create Superagent
            conversation](/api-reference/create-superagent-conversation).
          example: 6820f3a4e7b91d003c45a1f2
        name:
          type: string
          title: Name
          description: Name of the agent.
          example: Sales assistant
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Description of the agent, or `null` if none was set.
          example: Answers questions about our weekly sales.
        logo_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Logo Url
          description: URL of the agent's logo, or `null` if none was set.
          example: https://cdn.acme.com/sales-assistant.png
      type: object
      required:
        - id
        - name
      title: Superagent
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: 'Personal access token, sent as `Authorization: Bearer <token>`.'

````

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