curl --request PATCH \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"label": {
"title": "reembolso",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": false
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}"
payload = { "label": {
"title": "reembolso",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": False
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
label: {
title: 'reembolso',
description: 'Customers asking for their money back.',
color: '#5C6BC0',
show_on_sidebar: false
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}', 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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}",
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([
'label' => [
'title' => 'reembolso',
'description' => 'Customers asking for their money back.',
'color' => '#5C6BC0',
'show_on_sidebar' => false
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}"
payload := strings.NewReader("{\n \"label\": {\n \"title\": \"reembolso\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": false\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": {\n \"title\": \"reembolso\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": false\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": {\n \"title\": \"reembolso\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": false\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 14,
"title": "vip",
"description": "High-value customers.",
"color": "#5C6BC0",
"show_on_sidebar": true,
"created_at": "2026-05-02T11:04:17.000Z",
"updated_at": "2026-08-10T14:32:05.123Z"
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "label",
"code": "invalid_shape",
"message": "Send the fields inside a label object, for example {\"label\": {\"title\": \"refund\"}}."
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "You are not allowed to perform this action."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "title",
"code": "taken",
"message": "Another label of this account already uses this title. Titles are compared after trimming and lowercasing."
}
]
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait a minute and try again."
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Update a label
Requires an administrator or a CX engineer token; any other role gets 403. Send the fields to change under a label wrapper; whatever you leave out stays as it is, and an update with none of the four writable fields is a 400, not a no-op.
Changing title renames the label and retags every native conversation, contact and company that carries it, asynchronously. Conversations mirrored from ClaudIA are not retagged: they keep the old title, so on accounts that only use ClaudIA the history stays under the old name. ClaudIA applies tags by name, so it keeps applying the old title, which recreates the old label, until the tags on its knowledge base contents (or the channel’s tag-to-label map) are renamed too. To change only color, description or sidebar visibility, omit title.
The response comes back as soon as the label itself is saved; the retag of the records that carried the old title runs after it.
curl --request PATCH \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"label": {
"title": "reembolso",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": false
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}"
payload = { "label": {
"title": "reembolso",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": False
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
label: {
title: 'reembolso',
description: 'Customers asking for their money back.',
color: '#5C6BC0',
show_on_sidebar: false
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}', 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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}",
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([
'label' => [
'title' => 'reembolso',
'description' => 'Customers asking for their money back.',
'color' => '#5C6BC0',
'show_on_sidebar' => false
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}"
payload := strings.NewReader("{\n \"label\": {\n \"title\": \"reembolso\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": false\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
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://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": {\n \"title\": \"reembolso\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": false\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels/{labelId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": {\n \"title\": \"reembolso\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": false\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 14,
"title": "vip",
"description": "High-value customers.",
"color": "#5C6BC0",
"show_on_sidebar": true,
"created_at": "2026-05-02T11:04:17.000Z",
"updated_at": "2026-08-10T14:32:05.123Z"
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "label",
"code": "invalid_shape",
"message": "Send the fields inside a label object, for example {\"label\": {\"title\": \"refund\"}}."
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "You are not allowed to perform this action."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "title",
"code": "taken",
"message": "Another label of this account already uses this title. Titles are compared after trimming and lowercasing."
}
]
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait a minute and try again."
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Authorizations
Headers
Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.
1
Path Parameters
Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.
1
The label id returned by List labels, Get a label or Create a label. It is the label's id, not its title.
14
Body
Response
The label as stored. A title change is applied to the label right away; the retag of the records that carried the old title runs after this answer.
A label definition of the account — the tag conversations and contacts carry.