> ## 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.
# Send Superagent message
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Sends a message to a Superagent and waits for its reply.
The request stays open while the agent works, which includes any tools it runs, and returns the agent's final reply. A reply that needs many tool calls can take minutes, so set a generous client timeout. The agent's turn uses credits from the agent's workspace.
Send `content`, and optionally `file_urls`, in the body. Use a `conversation_id` from [Create Superagent conversation](/api-reference/create-superagent-conversation) or [List Superagent conversations](/api-reference/list-superagent-conversations).
Each request starts its own reply. Sending another message before the agent answers starts a second reply alongside the first, and retrying a request that timed out runs the turn again and uses credits again. Wait for the reply before you send the next message.
To hear about messages without waiting on this request, subscribe to `message.created` and `message.completed` with [Create Superagent webhook](/api-reference/create-superagent-webhook).
This endpoint is limited to 20 requests per minute.
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.
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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/agents/{agent_id}/conversations/{conversation_id}/messages
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/{conversation_id}/messages:
post:
summary: Send Superagent message
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Sends a message to a Superagent and waits for its reply.
The request stays open while the agent works, which includes any tools
it runs, and returns the agent's final reply. A reply that needs many
tool calls can take minutes, so set a generous client timeout. The
agent's turn uses credits from the agent's workspace.
Send `content`, and optionally `file_urls`, in the body. Use a
`conversation_id` from [Create Superagent
conversation](/api-reference/create-superagent-conversation) or [List
Superagent conversations](/api-reference/list-superagent-conversations).
Each request starts its own reply. Sending another message before the
agent answers starts a second reply alongside the first, and retrying a
request that timed out runs the turn again and uses credits again. Wait
for the reply before you send the next message.
To hear about messages without waiting on this request, subscribe to
`message.created` and `message.completed` with [Create Superagent
webhook](/api-reference/create-superagent-webhook).
This endpoint is limited to 20 requests per minute.
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.
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.
operationId: >-
send_message_api_agents__agent_id__conversations__conversation_id__messages_post
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
description: >-
ID of the conversation to send the message to. Get it from [Create
Superagent
conversation](/api-reference/create-superagent-conversation) or
[List Superagent
conversations](/api-reference/list-superagent-conversations).
title: Conversation Id
description: >-
ID of the conversation to send the message to. Get it from [Create
Superagent
conversation](/api-reference/create-superagent-conversation) or
[List Superagent
conversations](/api-reference/list-superagent-conversations).
example: 68a1c2e4f0b9d3002e7a5c11
- 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:
type: object
title: SendSuperagentMessage
required:
- content
properties:
content:
type: string
description: Text of your message to the agent.
example: Summarize today's sales.
file_urls:
type: array
items:
type: string
description: >-
URLs of files to attach to the message, such as a
spreadsheet for the agent to read.
example:
- >-
https://storage.base44.com/6820f3a4e7b91d003c45a1f2/sales.csv
example:
content: Summarize today's sales.
responses:
'200':
description: The agent's reply.
content:
application/json:
schema:
$ref: '#/components/schemas/SuperagentMessage'
'400':
description: >-
`agent_id` belongs to an app that isn't a Superagent, or the agent's
workspace is out of credits.
'401':
description: Missing or invalid credentials.
'403':
description: >-
You don't have access to this agent, the conversation belongs to
another user or another agent, your API key is read-only, or
Superagent is turned off for the workspace.
'404':
description: Agent or conversation not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: >-
Rate limit exceeded (20 requests per minute), or another message to
the agent is being received at the same moment.
components:
schemas:
SuperagentMessage:
properties:
id:
type: string
title: Id
description: ID of the message.
example: 3f2504e0-4f89-41d3-9a0c-0305e82c3301
role:
type: string
enum:
- user
- assistant
title: Role
description: Who wrote the message. Either `user` or `assistant`.
example: assistant
content:
anyOf:
- type: string
- type: 'null'
title: Content
description: >-
Text of the message, or `null` when the message only carries tool
calls.
example: Here's a summary of today's sales.
file_urls:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: File Urls
description: URLs of files attached to the message, or `null` when it has none.
example:
- https://storage.base44.com/6820f3a4e7b91d003c45a1f2/report.pdf
tool_calls:
anyOf:
- items:
$ref: '#/components/schemas/SuperagentToolCall'
type: array
- type: 'null'
title: Tool Calls
description: >-
Tools the agent called while writing the message, or `null` when it
called none.
example:
- id: toolu_01A09q90qw90lq917835lq9
name: web_search
requires_user_input: false
status: success
metadata:
$ref: '#/components/schemas/SuperagentMessageMetadata'
description: When the message was created.
type: object
required:
- id
- role
- content
- metadata
title: SuperagentMessage
description: A message in a Superagent conversation.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
SuperagentToolCall:
properties:
id:
type: string
title: Id
description: ID of the tool call.
example: toolu_01A09q90qw90lq917835lq9
name:
type: string
title: Name
description: Name of the tool the agent called.
example: web_search
status:
type: string
enum:
- running
- success
- error
- stopped
- waiting_for_user_input
title: Status
description: >-
Where the tool call is. One of `running`, `success`, `error`,
`stopped`, or `waiting_for_user_input`.
example: success
requires_user_input:
type: boolean
title: Requires User Input
description: >-
Whether the tool call is waiting for the user to answer or approve
something before the agent continues.
example: false
type: object
required:
- id
- name
- status
- requires_user_input
title: SuperagentToolCall
SuperagentMessageMetadata:
properties:
created_date:
type: string
format: date-time
title: Created Date
description: Time the message was created, as a UTC timestamp in ISO 8601 format.
example: '2026-08-02T14:30:00Z'
type: object
required:
- created_date
title: SuperagentMessageMetadata
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 `.'
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.