# Label a conversation

PATCH /v1/threads/{thread_id}

Source: https://cherami.to/docs/api/threads/update-thread-labels



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`PATCH /v1/threads/{thread_id}`

Requires an [API key](https://cherami.to/docs/api#authentication): `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](https://cherami.to/docs/api/labels/update-message-labels) 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 [#parameters]

| Parameter   | Location | Required | Type   | Meaning                                  |
| ----------- | -------- | -------- | ------ | ---------------------------------------- |
| `thread_id` | path     | Yes      | string | Cherami resource ID returned by the API. |

## Request body [#request-body]

JSON object, at most 20 KiB in total.

### Schema: LabelChange [#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](#schema-label) | Label names, case-sensitive; order and duplicates don't matter. `maxItems`: `32` |
| `remove_labels` | No       | array of [Label](#schema-label) | Label names, case-sensitive; order and duplicates don't matter. `maxItems`: `32` |

Unknown fields are rejected.

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

Save the payload as `request.json`, replacing the example values.

```json
{
  "add_labels": [
    "handled"
  ]
}
```

```sh
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 [#responses]

### HTTP 200 [#http-200]

Success.

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

Content type: `application/json`.

[ThreadLabelResult](#schema-threadlabelresult)

```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 [#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](#schema-error)

### HTTP 401 [#http-401]

`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#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](#schema-error)

### HTTP 413 [#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](#schema-error)

### HTTP 415 [#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](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.

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

Content type: `application/json`.

[Error](#schema-error)

## Schema: ThreadLabelResult [#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 [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#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 [#schema-label]

1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.

string. `x-max-utf8-bytes`: `128`

[Errors, limits and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)
