Send Superagent message

Changed on

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

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>

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

Path parameters

conversation_idstring required

ID of the conversation to send the message to. Get it from Create Superagent conversation or List Superagent conversations.

agent_idstring required

ID of the Superagent. It's the agent's app ID, shown in the agent's developer settings.

Request body

contentstring required

Text of your message to the agent.

file_urlsstring[]

URLs of files to attach to the message, such as a spreadsheet for the agent to read.

Example request

{
  "content": "Summarize today's sales.",
  "file_urls": [
    "https://storage.base44.com/6820f3a4e7b91d003c45a1f2/sales.csv"
  ]
}

Response

The agent's reply.

idstring required

ID of the message.

role'user' | 'assistant' required

Who wrote the message. Either user or assistant.

contentstring nullable required

Text of the message, or null when the message only carries tool calls.

file_urlsstring[] nullable

URLs of files attached to the message, or null when it has none.

Example response

{
  "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "role": "assistant",
  "content": "Here's a summary of today's sales.",
  "file_urls": [
    "https://storage.base44.com/6820f3a4e7b91d003c45a1f2/report.pdf"
  ],
  "tool_calls": [
    {
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "web_search",
      "requires_user_input": false,
      "status": "success"
    }
  ],
  "metadata": {
    "created_date": "2026-08-02T14:30:00Z"
  }
}

Changes