cherami.
API referenceConversations

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

ParameterLocationRequiredTypeMeaning
thread_idpathYesstringCherami 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.

FieldRequiredTypeMeaning and constraints
add_labelsNoarray of LabelLabel names, case-sensitive; order and duplicates don't matter. maxItems: 32
remove_labelsNoarray of LabelLabel 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.json

Responses

HTTP 200

Success.

  • X-Request-ID: Identifies this request; include it when reporting a problem.

Content type: application/json.

ThreadLabelResult

{
  "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.

Error

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.

Error

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.

Error

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.

Error

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.

Error

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.

Error

Schema: ThreadLabelResult

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
message_countYesintegerminimum: 0
received_countYesintegerminimum: 0
sent_countYesintegerminimum: 0
add_labelsYesarray of string
remove_labelsYesarray of string

Schema: Error

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation 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

Errors, limits and pagination · Download OpenAPI 3.1

On this page