Update a tag definition
Updates the name, color, or both for one tag definition in the current organization.
/api/tag-definitions/{id}Updates the name, color, or both for one tag definition in the current organization. Renaming a definition also renames matching tags already assigned to conversations. Existing duplicate target tags are merged safely. The route returns 404 when the definition does not exist and 409 when another definition already uses the requested name.
Endpoint requirements
- Credentials
- Use either
Bearer API keyorX-API-Key header. - Required scope
tag-definitions:write- Module
- Automation & API module (
api_access) - Organization and site scope
- Requests can access only resources owned by the authenticated organization. The API does not reveal whether an identifier belongs to another organization or site.
- Retry behavior
- Idempotent write: Retrying with the same inputs has the same effect as the original request. The response may show the resource's current state.
Path Parameters
Resource identifier.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request body accepted by this operation.
1 <= propertiesRequest body accepted by this operation.
1 <= propertiesResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "priority", "color": "#2563EB", "projectScope": "all", "projectIds": [ "11111111-1111-4111-8111-111111111111" ], "createdAt": "2026-06-23T08:00:00.000Z", "updatedAt": "2026-06-23T09:00:00.000Z"}Request examples
curl
curl --request PATCH \
'https://api.convor.io/api/tag-definitions/11111111-1111-4111-8111-111111111111' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer convor_sk_...' \
--header 'Content-Type: application/json' \
--data '{
"name": "priority",
"color": "#2563EB"
}'JavaScript
const response = await fetch("https://api.convor.io/api/tag-definitions/11111111-1111-4111-8111-111111111111", {
method: "PATCH",
headers: {
"Accept": "application/json",
"Authorization": "Bearer convor_sk_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "priority",
"color": "#2563EB"
}),
});
const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
? null
: contentType.includes("json")
? await response.json()
: contentType.startsWith("text/")
? await response.text()
: await response.blob();
if (!response.ok) {
const message = typeof data === "object" && data !== null
&& "error" in data && typeof data.error === "object"
&& data.error !== null && "message" in data.error
? String(data.error.message)
: "Convor API request failed (" + response.status + ")";
throw new Error(message);
}
console.log(data);Was this page helpful?