Update Goal Bot

curl --request PATCH \
  --url https://app.tuco.ai/api/goal-bots/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "prompt": "<string>",
  "includeTags": [
    "<string>"
  ],
  "excludeTags": [
    "<string>"
  ],
  "mode": "<string>",
  "status": "<string>",
  "connector": "<string>",
  "kbRetrieval": "<string>",
  "tone": "<string>",
  "canAsk": true,
  "typingIndicator": true,
  "maxTurns": 123,
  "onDoneTag": "<string>",
  "writeTagToCrm": true,
  "allowedToolIds": [
    "<string>"
  ],
  "collectFields": [
    "<string>"
  ]
}
'

import requests

url = "https://app.tuco.ai/api/goal-bots/{id}"

payload = {
    "name": "<string>",
    "prompt": "<string>",
    "includeTags": ["<string>"],
    "excludeTags": ["<string>"],
    "mode": "<string>",
    "status": "<string>",
    "connector": "<string>",
    "kbRetrieval": "<string>",
    "tone": "<string>",
    "canAsk": True,
    "typingIndicator": True,
    "maxTurns": 123,
    "onDoneTag": "<string>",
    "writeTagToCrm": True,
    "allowedToolIds": ["<string>"],
    "collectFields": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    prompt: '<string>',
    includeTags: ['<string>'],
    excludeTags: ['<string>'],
    mode: '<string>',
    status: '<string>',
    connector: '<string>',
    kbRetrieval: '<string>',
    tone: '<string>',
    canAsk: true,
    typingIndicator: true,
    maxTurns: 123,
    onDoneTag: '<string>',
    writeTagToCrm: true,
    allowedToolIds: ['<string>'],
    collectFields: ['<string>']
  })
};

fetch('https://app.tuco.ai/api/goal-bots/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'prompt' => '<string>',
    'includeTags' => [
        '<string>'
    ],
    'excludeTags' => [
        '<string>'
    ],
    'mode' => '<string>',
    'status' => '<string>',
    'connector' => '<string>',
    'kbRetrieval' => '<string>',
    'tone' => '<string>',
    'canAsk' => true,
    'typingIndicator' => true,
    'maxTurns' => 123,
    'onDoneTag' => '<string>',
    'writeTagToCrm' => true,
    'allowedToolIds' => [
        '<string>'
    ],
    'collectFields' => [
        '<string>'
    ]
  ]),
  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.tuco.ai/api/goal-bots/{id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"includeTags\": [\n    \"<string>\"\n  ],\n  \"excludeTags\": [\n    \"<string>\"\n  ],\n  \"mode\": \"<string>\",\n  \"status\": \"<string>\",\n  \"connector\": \"<string>\",\n  \"kbRetrieval\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"canAsk\": true,\n  \"typingIndicator\": true,\n  \"maxTurns\": 123,\n  \"onDoneTag\": \"<string>\",\n  \"writeTagToCrm\": true,\n  \"allowedToolIds\": [\n    \"<string>\"\n  ],\n  \"collectFields\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://app.tuco.ai/api/goal-bots/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"includeTags\": [\n    \"<string>\"\n  ],\n  \"excludeTags\": [\n    \"<string>\"\n  ],\n  \"mode\": \"<string>\",\n  \"status\": \"<string>\",\n  \"connector\": \"<string>\",\n  \"kbRetrieval\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"canAsk\": true,\n  \"typingIndicator\": true,\n  \"maxTurns\": 123,\n  \"onDoneTag\": \"<string>\",\n  \"writeTagToCrm\": true,\n  \"allowedToolIds\": [\n    \"<string>\"\n  ],\n  \"collectFields\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.tuco.ai/api/goal-bots/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"includeTags\": [\n    \"<string>\"\n  ],\n  \"excludeTags\": [\n    \"<string>\"\n  ],\n  \"mode\": \"<string>\",\n  \"status\": \"<string>\",\n  \"connector\": \"<string>\",\n  \"kbRetrieval\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"canAsk\": true,\n  \"typingIndicator\": true,\n  \"maxTurns\": 123,\n  \"onDoneTag\": \"<string>\",\n  \"writeTagToCrm\": true,\n  \"allowedToolIds\": [\n    \"<string>\"\n  ],\n  \"collectFields\": [\n    \"<string>\"\n  ]\n}"

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

PATCH

api

goal-bots

{id}

Update Goal Bot

curl --request PATCH \
  --url https://app.tuco.ai/api/goal-bots/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "prompt": "<string>",
  "includeTags": [
    "<string>"
  ],
  "excludeTags": [
    "<string>"
  ],
  "mode": "<string>",
  "status": "<string>",
  "connector": "<string>",
  "kbRetrieval": "<string>",
  "tone": "<string>",
  "canAsk": true,
  "typingIndicator": true,
  "maxTurns": 123,
  "onDoneTag": "<string>",
  "writeTagToCrm": true,
  "allowedToolIds": [
    "<string>"
  ],
  "collectFields": [
    "<string>"
  ]
}
'

import requests

url = "https://app.tuco.ai/api/goal-bots/{id}"

payload = {
    "name": "<string>",
    "prompt": "<string>",
    "includeTags": ["<string>"],
    "excludeTags": ["<string>"],
    "mode": "<string>",
    "status": "<string>",
    "connector": "<string>",
    "kbRetrieval": "<string>",
    "tone": "<string>",
    "canAsk": True,
    "typingIndicator": True,
    "maxTurns": 123,
    "onDoneTag": "<string>",
    "writeTagToCrm": True,
    "allowedToolIds": ["<string>"],
    "collectFields": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    prompt: '<string>',
    includeTags: ['<string>'],
    excludeTags: ['<string>'],
    mode: '<string>',
    status: '<string>',
    connector: '<string>',
    kbRetrieval: '<string>',
    tone: '<string>',
    canAsk: true,
    typingIndicator: true,
    maxTurns: 123,
    onDoneTag: '<string>',
    writeTagToCrm: true,
    allowedToolIds: ['<string>'],
    collectFields: ['<string>']
  })
};

fetch('https://app.tuco.ai/api/goal-bots/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'prompt' => '<string>',
    'includeTags' => [
        '<string>'
    ],
    'excludeTags' => [
        '<string>'
    ],
    'mode' => '<string>',
    'status' => '<string>',
    'connector' => '<string>',
    'kbRetrieval' => '<string>',
    'tone' => '<string>',
    'canAsk' => true,
    'typingIndicator' => true,
    'maxTurns' => 123,
    'onDoneTag' => '<string>',
    'writeTagToCrm' => true,
    'allowedToolIds' => [
        '<string>'
    ],
    'collectFields' => [
        '<string>'
    ]
  ]),
  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.tuco.ai/api/goal-bots/{id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"includeTags\": [\n    \"<string>\"\n  ],\n  \"excludeTags\": [\n    \"<string>\"\n  ],\n  \"mode\": \"<string>\",\n  \"status\": \"<string>\",\n  \"connector\": \"<string>\",\n  \"kbRetrieval\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"canAsk\": true,\n  \"typingIndicator\": true,\n  \"maxTurns\": 123,\n  \"onDoneTag\": \"<string>\",\n  \"writeTagToCrm\": true,\n  \"allowedToolIds\": [\n    \"<string>\"\n  ],\n  \"collectFields\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://app.tuco.ai/api/goal-bots/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"includeTags\": [\n    \"<string>\"\n  ],\n  \"excludeTags\": [\n    \"<string>\"\n  ],\n  \"mode\": \"<string>\",\n  \"status\": \"<string>\",\n  \"connector\": \"<string>\",\n  \"kbRetrieval\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"canAsk\": true,\n  \"typingIndicator\": true,\n  \"maxTurns\": 123,\n  \"onDoneTag\": \"<string>\",\n  \"writeTagToCrm\": true,\n  \"allowedToolIds\": [\n    \"<string>\"\n  ],\n  \"collectFields\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.tuco.ai/api/goal-bots/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"includeTags\": [\n    \"<string>\"\n  ],\n  \"excludeTags\": [\n    \"<string>\"\n  ],\n  \"mode\": \"<string>\",\n  \"status\": \"<string>\",\n  \"connector\": \"<string>\",\n  \"kbRetrieval\": \"<string>\",\n  \"tone\": \"<string>\",\n  \"canAsk\": true,\n  \"typingIndicator\": true,\n  \"maxTurns\": 123,\n  \"onDoneTag\": \"<string>\",\n  \"writeTagToCrm\": true,\n  \"allowedToolIds\": [\n    \"<string>\"\n  ],\n  \"collectFields\": [\n    \"<string>\"\n  ]\n}"

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

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.

Send only the fields you want to change. Anything you leave out keeps its current value — there are no defaults applied on update. Array fields (includeTags, excludeTags, allowedToolIds, collectFields) replace the stored array, so send the complete set.

Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

Authorization: Bearer tuco_xxxxxxxxxxxxx

Path parameter

string

required

The bot id. A malformed id returns 400 Invalid id.

Request body

Every field is optional. Unknown fields are ignored.

string

Display name for the bot. An empty or missing name returns 400 Name is required.

string

The instructions the model runs on — who it is, what it is trying to do, what it must not say. An empty or missing prompt returns 400 Prompt is required.

string[]

Tags that wake this bot. A lead carrying any of them is handled by this bot when it replies. Set tags with PATCH /api/leads/{id}. Defaults to [].

string[]

Tags that keep a lead away from this bot, even when includeTags matches. Defaults to [].

string

default:"autopilot"

How replies are delivered.

Value	Behaviour
`autopilot`	The bot replies on its own.
`copilot`	Every reply is saved as a draft for a human to approve.
`manual`	The bot is off. This is the only way to stop the built-in Auto Replies bot, which cannot be deleted.
`draft`	Legacy alias for `copilot`, still accepted.

An unrecognised value is not rejected — it is silently stored as copilot. Read the mode back from the response to confirm what was saved.

string

default:"active"

active or paused. A new bot goes live the moment it exists and starts answering leads whose tags already match, so pass "paused" when you want to create, inspect, then flip it on with PATCH. Any value other than "paused" is stored as active.

string

default:"calendly"

Calendar used for booking: calendly or ghl_calendar. Any other value falls back to calendly.

string

default:"always"

When the bot searches your knowledge base. always searches on every inbound message; auto leaves the decision to the model. On create, anything other than "auto" is stored as always.

string

Free-text tone hint, e.g. "warm and brief".

boolean

default:"true"

Whether the bot may ask the lead follow-up questions. Only an explicit false turns it off.

boolean

default:"true"

Send a typing signal before replying. Only an explicit false turns it off.

number

default:"8"

How many times the bot may reply in one conversation. Clamped to 1–20; a non-numeric or non-positive value falls back to 8.

string

Tag applied to the lead when the bot reaches its goal.

boolean

default:"false"

Push onDoneTag to the connected CRM as well as to Tuco. Only an explicit true enables it.

string[]

Ids of the API tools this bot may call, from GET /api/campaign-tools. Omit to allow none.

string[]

Field names the bot should try to collect during the conversation, e.g. ["email", "company"].

kbRetrieval behaves as the mirror of create here: on PATCH, anything other than the exact string "always" is stored as "auto". Send "always" explicitly if that is what you want.

Example

curl -X PATCH "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused", "maxTurns": 4 }'

Turning the built-in Auto Replies bot off:

curl -X PATCH "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "manual" }'

Success (`200 OK`)

{
  "success": true,
  "goalBot": { /* the full updated bot */ },
  "taskAgent": { /* identical object */ }
}

Errors

Status	When	Body
`400`	Malformed `{id}`	`{{ "error": "Invalid id" }}`
`400`	Key has no active workspace	`{{ "error": "No active workspace" }}`
`401`	Missing or invalid API key	`{{ "error": "Unauthorized" }}`
`404`	No bot with that id in your workspace	`{{ "error": "Not found" }}`

Overview

Webhooks

Errors and status codes

iMessage Availability

Messages

Voice / Calling

Replies

Do Not Contact

Lines & Leads

Analytics

Goal Bots

API Tools

Agency

Workspace settings

Update Goal Bot

Authentication

Path parameter

Request body

Example

Success (`200 OK`)

Errors

​Authentication

​Path parameter

​Request body

​Example

​Success (200 OK)

​Errors

Authentication

Path parameter

Request body

Example

Success (`200 OK`)

Errors