---
title: "Send Superagent message"
method: POST
path: "/api/agents/{agent_id}/conversations/{conversation_id}/messages"
---

# Send Superagent message

`POST /api/agents/{agent_id}/conversations/{conversation_id}/messages`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages`
- Auth: HTTP bearer

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

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.

<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. Send only the fields documented here. Other request fields are not supported and their behavior can change.</Warning>

## Path parameters

- `conversation_id` string, required: 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).
- `agent_id` string, required: ID of the Superagent. It's the agent's app ID, shown in the agent's developer settings.

## Request body

- object
  - `content` string, required: Text of your message to the agent.
  - `file_urls` string[]: URLs of files to attach to the message, such as a spreadsheet for the agent to read.

## Response `200`

The agent's reply.

- SuperagentMessage: A message in a Superagent conversation.
  - `id` string, required: ID of the message.
  - `role` 'user' | 'assistant', required: Who wrote the message. Either `user` or `assistant`.
  - `content` string, nullable, required: Text of the message, or `null` when the message only carries tool calls.
  - `file_urls` string[], nullable: URLs of files attached to the message, or `null` when it has none.
  - `tool_calls` SuperagentToolCall[], nullable: Tools the agent called while writing the message, or `null` when it called none.
    - `id` string, required: ID of the tool call.
    - `name` string, required: Name of the tool the agent called.
    - `status` 'running' | 'success' | 'error' | 'stopped' | 'waiting_for_user_input', required: Where the tool call is. One of `running`, `success`, `error`, `stopped`, or `waiting_for_user_input`.
    - `requires_user_input` boolean, required: Whether the tool call is waiting for the user to answer or approve something before the agent continues.
  - `metadata` SuperagentMessageMetadata, required
    - `created_date` string, date-time, required: Time the message was created, as a UTC timestamp in ISO 8601 format.

## Other responses

- `400`: `agent_id` belongs to an app that isn't a Superagent, or the agent's workspace is out of credits.
- `401`: Missing or invalid credentials.
- `403`: 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`: Agent or conversation not found.
- `422`: Validation Error
- `429`: Rate limit exceeded (20 requests per minute), or another message to the agent is being received at the same moment.

## Changes

> 58 revisions in range; 1 not diffed.

- **2026-10-12** `5e139db2e643`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-05** `4babe63df3b7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adexad/apis/base44-app-management-api/changes/api/agents/:agent_id/conversations/:conversation_id/messages/post.md)

---

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