Label a conversation
PATCH /v1/threads/{thread_id}
Read as Markdown ↗PATCH /v1/threads/{thread_id}
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Adds and removes labels on every message currently in the conversation, received and sent, leaving their other labels as they are. The label rules apply. Messages that arrive later don't get the labels.
The counts cover every message updated, including those that already matched, and add_labels and remove_labels echo the change rather than each message's labels.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
thread_id | path | Yes | string | Cherami resource ID returned by the API. |
Request body
JSON object, at most 20 KiB in total.
Schema: LabelChange
At least one array must contain a label, and a name can't be in both.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
add_labels | No | array of Label | Label names, case-sensitive; order and duplicates don't matter. maxItems: 32 |
remove_labels | No | array of Label | Label names, case-sensitive; order and duplicates don't matter. maxItems: 32 |
Unknown fields are rejected.
curl example
Supply CHERAMI_API_KEY privately.
Save the payload as request.json, replacing the example values.
{
"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
Success.
X-Request-ID: Identifies this request; include it when reporting a problem.
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 the label name, label change, filter group or discovery prefix the message names.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 401
unauthorized: Send a valid API key as Authorization: Bearer <key>. If the key stopped working, get a new one through recovery.
X-Request-ID: Identifies this request; include it when reporting a problem.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 413
body_too_large: Reduce the JSON request to the operation's body limit.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 500
internal_error: The operation failed. Retry a read; after a write the change may have happened, so recover as retry by operation describes.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
Schema: ThreadLabelResult
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
inbox_id | Yes | string | Cherami resource ID. |
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 | Code to handle. Handle a code you don't recognize by its HTTP status. |
message | Yes | string | Explanation of this case; its wording can change. |
Schema: Label
1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.
string. x-max-utf8-bytes: 128