Label a conversation
PATCH /v1/threads/{thread_id}
Read as Markdown ↗PATCH /v1/threads/{thread_id}
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
PATCH /v1/threads/{thread_id} adds or removes labels across all current received and sent members, not just one page. Use Content-Type: application/json with a body up to 20 KiB:
The ordinary label validation rules apply. Changes publish together and preserve unrelated labels. Future replies do not inherit the changes. No sending or deletion permission is needed, and no sending allowance is consumed.
Returns the update result.
id is the canonical thread ID when members were selected. Counts describe updated copies, including those whose labels already matched, excluding any deleted before the update. add_labels and remove_labels contain the normalized changes, not each message's complete label set.
Invalid changes return 400 invalid_labels. Empty, missing or other-account threads return 404.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
thread_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
Request body
JSON object. Total UTF-8 request body limit: 20480 bytes.
Schema: LabelChange
At least one array must contain a label. A normalized label cannot occur in both arrays.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
add_labels | No | array of Label | Trimmed, deduplicated and case-sensitive. Order is not significant. maxItems: 32 |
remove_labels | No | array of Label | Trimmed, deduplicated and case-sensitive. Order is not significant. maxItems: 32 |
Unknown fields are rejected.
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
Save the intended payload as a private request.json file and replace illustrative values. For an uncertain response, follow the operation-specific recovery rules.
{
"add_labels": [
"handled"
]
}curl --silent --show-error --include --request PATCH \
"https://cherami.to/v1/threads/THREAD_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
{
"id": "11111111-1111-4111-8111-111111111111",
"inbox_id": "11111111-1111-4111-8111-111111111111",
"message_count": 0,
"received_count": 0,
"sent_count": 0,
"add_labels": [],
"remove_labels": []
}HTTP 400
invalid_json: Send a valid UTF-8 JSON object, not an array or scalar.
invalid_labels: Correct label names, changes, filter groups, or discovery prefix.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 413
body_too_large: Reduce the JSON request to the endpoint's body limit.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 500
internal_error: Operation failed; a write may already have happened. Follow the operation-specific recovery below.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: ThreadLabelResult
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
inbox_id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
message_count | Yes | integer | minimum: 0 |
received_count | Yes | integer | minimum: 0 |
sent_count | Yes | integer | minimum: 0 |
add_labels | Yes | array of string | |
remove_labels | Yes | array of string |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
Schema: Label
1–128 UTF-8 bytes after trimming. Well-formed Unicode without control characters; case-sensitive.
string. x-max-utf8-bytes: 128
HTTP conventions, errors and pagination · Download OpenAPI 3.1