Update Task Agent

curl --request PATCH \
  --url https://app.tuco.ai/api/tasks/{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/tasks/{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/tasks/{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/tasks/{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/tasks/{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/tasks/{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/tasks/{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

tasks

{id}

Update Task Agent

curl --request PATCH \
  --url https://app.tuco.ai/api/tasks/{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/tasks/{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/tasks/{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/tasks/{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/tasks/{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/tasks/{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/tasks/{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

This is an alias. PATCH /api/tasks/{id} and PATCH /api/goal-bots/{id} are the same route.

Send only the fields you want to change — anything omitted keeps its current value. Array fields 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 agent id. A malformed id returns 400 Invalid id.

Request body

Every field is optional; unknown fields are ignored.

string

Display name.

string

The instructions the model runs on.

string[]

Replaces the tag list that wakes this agent.

string[]

Replaces the exclusion list.

string

autopilot, copilot, manual, or the legacy alias draft. Omit to leave unchanged. An unrecognised value is stored as copilot rather than rejected.

string

active or paused. Anything other than "paused" is read as active.

string

calendly or ghl_calendar.

string

always or auto. On PATCH, anything other than the exact string "always" is stored as "auto" — the mirror of create, so send "always" explicitly when that is what you want.

string

Free-text tone hint.

boolean

Only an explicit false turns it off.

boolean

Only an explicit false turns it off.

number

Clamped to 1–20; a non-numeric value falls back to 8.

string

Tag applied when the agent finishes.

boolean

Only an explicit true enables it.

string[]

Replaces the allowed-tool list.

string[]

Replaces the collect list.

Example

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

Success (`200 OK`)

{
  "success": true,
  "goalBot": { /* the full updated agent */ },
  "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 agent with that id in your workspace	`{ "error": "Not found" }`

Overview

Webhooks

Errors and status codes

iMessage Availability

Messages

Voice / Calling

Replies

Lines & Leads

Campaigns

Analytics

Goal Bots

API Tools

Agency

Workspace settings

Update Task Agent

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