Send Superagent message

curl --request POST \
  --url https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "content": "Summarize today's sales."
}
EOF

import requests

url = "https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages"

payload = { "content": "Summarize today's sales." }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({content: 'Summarize today\'s sales.'})
};

fetch('https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'content' => 'Summarize today\'s sales.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages"

	payload := strings.NewReader("{\n  \"content\": \"Summarize today's sales.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content\": \"Summarize today's sales.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content\": \"Summarize today's sales.\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

API Reference

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

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.

POST

api

agents

{agent_id}

conversations

{conversation_id}

messages

Send Superagent message

curl --request POST \
  --url https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "content": "Summarize today's sales."
}
EOF

import requests

url = "https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages"

payload = { "content": "Summarize today's sales." }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({content: 'Summarize today\'s sales.'})
};

fetch('https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'content' => 'Summarize today\'s sales.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages"

	payload := strings.NewReader("{\n  \"content\": \"Summarize today's sales.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content\": \"Summarize today's sales.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.base44.com/api/agents/{agent_id}/conversations/{conversation_id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content\": \"Summarize today's sales.\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Personal access token, sent as Authorization: Bearer <token>.

Path Parameters

conversation_id

string

required

ID of the conversation to send the message to. Get it from Create Superagent conversation or 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.

Body

application/json

content

string

required

Text of your message to the agent.

Example:

"Summarize today's sales."

file_urls

string[]

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

Response

The agent's reply.

A message in a Superagent conversation.

string

required

ID of the message.

Example:

"3f2504e0-4f89-41d3-9a0c-0305e82c3301"

role

enum<string>

required

Who wrote the message. Either user or assistant.

Available options:

user,

assistant

Example:

"assistant"

content

string | null

required

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

Example:

"Here's a summary of today's sales."

metadata

SuperagentMessageMetadata · object

required

When the message was created.

Show child attributes

file_urls

string[] | null

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

Example:

[
  "https://storage.base44.com/6820f3a4e7b91d003c45a1f2/report.pdf"
]

tool_calls

SuperagentToolCall · object[] | null

Tools the agent called while writing the message, or null when it called none.

Show child attributes

Example:

[
  {
    "id": "toolu_01A09q90qw90lq917835lq9",
    "name": "web_search",
    "requires_user_input": false,
    "status": "success"
  }
]

Base44 APIs

Apps API (Beta)

Superagents

Monitoring API

Audit Logs API

Send Superagent message

Authorizations

Path Parameters

Body

Response