List Goal Bots
curl --request GET \
--url https://app.tuco.ai/api/goal-bots \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/goal-bots"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/goal-bots', 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.tuco.ai/api/goal-bots",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/goal-bots"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.tuco.ai/api/goal-bots")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/goal-bots")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"goalBots": [
{
"_id": "<string>",
"name": "<string>",
"prompt": "<string>",
"mode": "<string>",
"status": "<string>",
"connector": "<string>",
"includeTags": [
"<string>"
],
"excludeTags": [
"<string>"
],
"kbRetrieval": "<string>",
"canAsk": true,
"maxTurns": 123,
"typingIndicator": true,
"writeTagToCrm": true,
"onDoneTag": "<string>",
"allowedToolIds": [
"<string>"
],
"collectFields": [
"<string>"
],
"isDefault": true,
"createdAt": "<string>",
"updatedAt": "<string>"
}
],
"taskAgents": [
{}
]
}Goal Bots
List Goal Bots
List all AI goal bots in your Tuco AI workspace — returns goal, persona, status (active or archived), approval mode, and enrollment counts for each bot.
GET
/
api
/
goal-bots
List Goal Bots
curl --request GET \
--url https://app.tuco.ai/api/goal-bots \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/goal-bots"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/goal-bots', 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.tuco.ai/api/goal-bots",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/goal-bots"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.tuco.ai/api/goal-bots")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/goal-bots")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"goalBots": [
{
"_id": "<string>",
"name": "<string>",
"prompt": "<string>",
"mode": "<string>",
"status": "<string>",
"connector": "<string>",
"includeTags": [
"<string>"
],
"excludeTags": [
"<string>"
],
"kbRetrieval": "<string>",
"canAsk": true,
"maxTurns": 123,
"typingIndicator": true,
"writeTagToCrm": true,
"onDoneTag": "<string>",
"allowedToolIds": [
"<string>"
],
"collectFields": [
"<string>"
],
"isDefault": true,
"createdAt": "<string>",
"updatedAt": "<string>"
}
],
"taskAgents": [
{}
]
}Goal bots and task agents are the same object. The two engines merged;
/api/goal-bots
and /api/tasks are aliases over one collection and return identical bodies. Every response
carries both goalBot and taskAgent (or goalBots and taskAgents) so integrations written
against either name keep working.The older stage-based engine moved to /api/instructions
and is being retired.Authentication
Pass your workspace API key as a Bearer token, or use a Clerk session token.Authorization: Bearer tuco_xxxxxxxxxxxxx
Example
curl "https://app.tuco.ai/api/goal-bots" \
-H "Authorization: Bearer tuco_xxxxxxxxxxxxx"
Success (200 OK)
{
"goalBots": [
{
"_id": "6aa9813105bb2cbf5931ac1f",
"name": "Auto Replies",
"prompt": "You're Raj from Tuco. You text people who checked out Tuco...",
"mode": "autopilot",
"status": "active",
"connector": "calendly",
"includeTags": [],
"excludeTags": [],
"kbRetrieval": "always",
"canAsk": true,
"maxTurns": 8,
"typingIndicator": true,
"writeTagToCrm": false,
"isDefault": true,
"createdAt": "2026-09-03T18:11:29.004Z",
"updatedAt": "2026-10-02T09:40:12.551Z"
}
],
"taskAgents": [ /* identical array */ ]
}
The first call from a brand-new workspace creates the default Auto Replies bot, so this
endpoint never returns an empty list. That bot is marked
isDefault: true and cannot be deleted —
set its mode to manual to stop it.Response
object[]
Every bot in the workspace. Default bot first, then newest first.
Show Goal bot fields
Show Goal bot fields
string
Bot id. Use it on every
{id} route.string
Display name.
string
The instructions the model runs on.
string
autopilot, copilot, manual, or the legacy alias draft.string
active or paused.string
calendly or ghl_calendar.string[]
Tags that wake the bot.
string[]
Tags that keep it out.
string
always or auto.boolean
Whether the bot may ask follow-up questions.
number
Reply cap per conversation.
boolean
Whether it sends a typing signal before replying.
boolean
Whether
onDoneTag is pushed to the connected CRM.string
Tag applied when the bot finishes.
string[]
Ids from
GET /api/campaign-tools the bot may call.string[]
Fields the bot tries to collect.
boolean
true for the built-in Auto Replies bot, which cannot be deleted.string
ISO 8601 timestamp.
string
ISO 8601 timestamp.
object[]
The same array under the pre-rename key. Read either one.
Errors
| Status | When | Body |
|---|---|---|
400 | Key has no active workspace | { "error": "No active workspace" } |
401 | Missing or invalid API key | { "error": "Unauthorized" } |