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

# Create Superagent conversation

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

Returns your conversation with a Superagent, creating it the first time you call this.

Each user has one main conversation per agent, so calling this again returns the same conversation. If you own the agent, it's the conversation you chat in inside Base44. `metadata` is stored only when the conversation is created. When you already have a conversation, it's returned unchanged and the `metadata` you send is ignored.

Send messages to it with [Send Superagent message](/api-reference/send-superagent-message).

<Note>This endpoint accepts a personal API key or personal access token belonging to a user with access to the agent. 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.</Warning>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/agents/{agent_id}/conversations
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/{agent_id}/conversations:
    post:
      summary: Create Superagent conversation
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Returns your conversation with a Superagent, creating it the first time
        you call this.


        Each user has one main conversation per agent, so calling this again
        returns the same conversation. If you own the agent, it's the
        conversation you chat in inside Base44. `metadata` is stored only when
        the conversation is created. When you already have a conversation, it's
        returned unchanged and the `metadata` you send is ignored.


        Send messages to it with [Send Superagent
        message](/api-reference/send-superagent-message).


        <Note>This endpoint accepts a personal API key or personal access token
        belonging to a user with access to the agent. 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.</Warning>
      operationId: create_conversation_api_agents__agent_id__conversations_post
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            description: >-
              ID of the Superagent. It's the agent's app ID, shown in the
              agent's developer settings.
            title: Agent Id
          description: >-
            ID of the Superagent. It's the agent's app ID, shown in the agent's
            developer settings.
          example: 6820f3a4e7b91d003c45a1f2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationPayload'
      responses:
        '200':
          description: Your conversation with the agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuperagentConversationSummary'
        '400':
          description: '`agent_id` belongs to an app that isn''t a Superagent.'
        '401':
          description: Missing or invalid credentials.
        '403':
          description: You don't have access to this agent, or your API key is read-only.
        '404':
          description: Agent not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded (100 requests per minute).
components:
  schemas:
    CreateConversationPayload:
      properties:
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: >-
            Metadata to store on the conversation when this call creates it.
            Ignored when you already have a conversation with the agent.
          example:
            source: crm-sync
      type: object
      title: CreateConversationPayload
    SuperagentConversationSummary:
      properties:
        id:
          type: string
          title: Id
          description: ID of the conversation.
          example: 68a1c2e4f0b9d3002e7a5c11
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: >-
            Title Base44 generates from the conversation, or `null` until one is
            generated.
          example: Weekly sales summary
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: >-
            Metadata stored on the conversation, including what you sent to
            [Create Superagent
            conversation](/api-reference/create-superagent-conversation) when it
            created it.
          example:
            source: crm-sync
        created_date:
          type: string
          format: date-time
          title: Created Date
          description: >-
            Time the conversation was created, as a UTC timestamp in ISO 8601
            format.
          example: '2026-08-01T09:15:00Z'
        updated_date:
          type: string
          format: date-time
          title: Updated Date
          description: >-
            Time the conversation last changed, as a UTC timestamp in ISO 8601
            format.
          example: '2026-08-02T14:30:00Z'
      type: object
      required:
        - id
        - title
        - metadata
        - created_date
        - updated_date
      title: SuperagentConversationSummary
      description: A Superagent conversation, without its messages.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  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.