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>"
}
]
}{
"error": {
"code": "database_unavailable",
"message": "Database temporarily unavailable, please retry",
"details": {}
}
}Create Superagent conversation
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.
Runs as your user in this app, so the app’s access rules decide which records you can read or change.
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>"
}
]
}{
"error": {
"code": "database_unavailable",
"message": "Database temporarily unavailable, please retry",
"details": {}
}
}Authorizations
Personal access token, sent as Authorization: Bearer <token>. Each operation lists the permission it needs: read_only or full_access. A full-access token can call every operation. A read-only token can call only the operations that list read_only; anything else returns 403 read_only_credential_route_not_allowed.
Path Parameters
Body
Response
Your conversation with the agent.
A Superagent conversation, without its messages.
Metadata stored on the conversation, including what you sent to Create Superagent conversation when it created it.
{ "source": "crm-sync" }
Was this page helpful?