curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"label": {
"title": "refund",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": true
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels"
payload = { "label": {
"title": "refund",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": True
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
label: {
title: 'refund',
description: 'Customers asking for their money back.',
color: '#5C6BC0',
show_on_sidebar: true
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels', 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",
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([
'label' => [
'title' => 'refund',
'description' => 'Customers asking for their money back.',
'color' => '#5C6BC0',
'show_on_sidebar' => true
]
]),
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"
payload := strings.NewReader("{\n \"label\": {\n \"title\": \"refund\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": true\n }\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": {\n \"title\": \"refund\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": {\n \"title\": \"refund\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 14,
"title": "refund",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": false,
"created_at": "2026-05-02T11:04:17.000Z",
"updated_at": "2026-08-10T14:32:05.123Z"
}{
"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": "color",
"code": "invalid",
"message": "Use a hex color such as #1f93ff or #fff."
}
]
}
}{
"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."
}
}Create a label
Requires an administrator or a CX engineer token; any other role gets 403. Send the label under a label wrapper. Only title is required: color defaults to #1f93ff, show_on_sidebar defaults to false, and description stays empty when omitted.
Creating is idempotent on the title. Titles are trimmed and lowercased, and a title that after that matches a label the account already has answers 200 with that existing label, unchanged: the color, description and show_on_sidebar you sent are ignored, so use Update a label to change them. A new title answers 201. A duplicate title is never a 422, so a retry after a timeout or a second call with the same title is safe. Labels are matched to conversations by title, so creating a label whose title is still on past conversations or contacts (for example, one deleted earlier) makes that history show up under the new label. ClaudIA applies its tags by the same title, so a label created ahead of time with the tag’s name is the one ClaudIA’s tagged conversations will use.
There is no delete operation: removing a label and creating another with the same title would bring the old tags back.
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"label": {
"title": "refund",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": true
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels"
payload = { "label": {
"title": "refund",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": True
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
label: {
title: 'refund',
description: 'Customers asking for their money back.',
color: '#5C6BC0',
show_on_sidebar: true
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels', 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",
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([
'label' => [
'title' => 'refund',
'description' => 'Customers asking for their money back.',
'color' => '#5C6BC0',
'show_on_sidebar' => true
]
]),
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"
payload := strings.NewReader("{\n \"label\": {\n \"title\": \"refund\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": true\n }\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": {\n \"title\": \"refund\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/labels")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": {\n \"title\": \"refund\",\n \"description\": \"Customers asking for their money back.\",\n \"color\": \"#5C6BC0\",\n \"show_on_sidebar\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 14,
"title": "refund",
"description": "Customers asking for their money back.",
"color": "#5C6BC0",
"show_on_sidebar": false,
"created_at": "2026-05-02T11:04:17.000Z",
"updated_at": "2026-08-10T14:32:05.123Z"
}{
"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": "color",
"code": "invalid",
"message": "Use a hex color such as #1f93ff or #fff."
}
]
}
}{
"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
Body
Response
A label of the account already has this title, compared trimmed and lowercased. It comes back as it is stored, nothing is written, and the color, description and show_on_sidebar you sent are ignored; use Update a label to change them.
A label definition of the account — the tag conversations and contacts carry.