Create Superagent conversation
curl --request POST \
--url https://app.base44.com/api/agents/{agent_id}/conversations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"metadata": {
"source": "crm-sync"
}
}
'import requests
url = "https://app.base44.com/api/agents/{agent_id}/conversations"
payload = { "metadata": { "source": "crm-sync" } }
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({metadata: {source: 'crm-sync'}})
};
fetch('https://app.base44.com/api/agents/{agent_id}/conversations', 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",
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([
'metadata' => [
'source' => 'crm-sync'
]
]),
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"
payload := strings.NewReader("{\n \"metadata\": {\n \"source\": \"crm-sync\"\n }\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")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"metadata\": {\n \"source\": \"crm-sync\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.base44.com/api/agents/{agent_id}/conversations")
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 \"metadata\": {\n \"source\": \"crm-sync\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "68a1c2e4f0b9d3002e7a5c11",
"title": "Weekly sales summary",
"metadata": {
"source": "crm-sync"
},
"created_date": "2026-08-01T09:15:00Z",
"updated_date": "2026-08-02T14:30:00Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}API Reference
Create Superagent conversation
This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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.
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.
POST
/
api
/
agents
/
{agent_id}
/
conversations
Create Superagent conversation
curl --request POST \
--url https://app.base44.com/api/agents/{agent_id}/conversations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"metadata": {
"source": "crm-sync"
}
}
'import requests
url = "https://app.base44.com/api/agents/{agent_id}/conversations"
payload = { "metadata": { "source": "crm-sync" } }
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({metadata: {source: 'crm-sync'}})
};
fetch('https://app.base44.com/api/agents/{agent_id}/conversations', 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",
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([
'metadata' => [
'source' => 'crm-sync'
]
]),
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"
payload := strings.NewReader("{\n \"metadata\": {\n \"source\": \"crm-sync\"\n }\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")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"metadata\": {\n \"source\": \"crm-sync\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.base44.com/api/agents/{agent_id}/conversations")
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 \"metadata\": {\n \"source\": \"crm-sync\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "68a1c2e4f0b9d3002e7a5c11",
"title": "Weekly sales summary",
"metadata": {
"source": "crm-sync"
},
"created_date": "2026-08-01T09:15:00Z",
"updated_date": "2026-08-02T14:30:00Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
Personal access token, sent as Authorization: Bearer <token>.
Path Parameters
ID of the Superagent. It's the agent's app ID, shown in the agent's developer settings.
Body
application/json
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" }
Response
Your conversation with the agent.
A Superagent conversation, without its messages.
ID of the conversation.
Example:
"68a1c2e4f0b9d3002e7a5c11"
Title Base44 generates from the conversation, or null until one is generated.
Example:
"Weekly sales summary"
Metadata stored on the conversation, including what you sent to Create Superagent conversation when it created it.
Example:
{ "source": "crm-sync" }
Time the conversation was created, as a UTC timestamp in ISO 8601 format.
Example:
"2026-08-01T09:15:00Z"
Time the conversation last changed, as a UTC timestamp in ISO 8601 format.
Example:
"2026-08-02T14:30:00Z"
Was this page helpful?