> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/threads/openapi.json](/docs/api/threads/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Threads: Update a thread

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Threads](/docs/api/threads.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Update a thread

`PATCH /v1/threads/{threadId}` - operationId `threads.update`

| Permission | Rate limit |
| --- | --- |
| Inbox edit | 4,800 requests a minute per API key |

Changes a thread's state and keeps every field you leave out. The body is a JSON object with at least one of
these fields:

- `isRead`, `isArchived`, `isSaved`: true or false. Archiving an email thread archives every reply
in it.
- `interest`: the label, one of `interested`, `question` (email threads of a workspace with
reply_question_type; LinkedIn and Instagram threads do not take it), `not_interested`, `negative`,
`automated`, `unclassified`, `unsubscribe`, `objection`, `wrong_contact`,
`referral` or `out_of_office`. `not_interested` reads back as `negative`. A LinkedIn or
Instagram thread does not take `automated`.
- `reminderAt`: when to remind you, as an ISO 8601 instant. Null clears the reminder.
- `personId`: links the thread's contact to this person in Accounts and replaces any earlier link. A merged
person links as the person it merged into.

On an email thread, an `interest` that says a person wrote back (any value but `automated`,
`out_of_office` and `unclassified`) clears the reply's auto-reply marks. Kenso then treats it as a human
reply and stops the contact's sequence.

On an iMessage thread, `reminderAt` is `400 validation_failed`: iMessage threads take no reminders.
`interest` needs a text from the person on the thread (`400 validation_failed` otherwise, detail
`imessage_no_inbound` on `interest`). If a newer text from them arrives before the write, it is
`400 validation_failed` with detail `imessage_newer_text` on `interest`, and neither the interest nor
the other fields change: reload the thread and set `interest` again in a new request (a new
`Idempotency-Key`, or none: the same key replays this answer for 24 hours). `unsubscribe` opts the number
out of texts, as the person's own STOP does, so Kenso texts it no more, and a later `interest` does not undo
it. Kenso checks that the thread exists and holds a text from the person before it writes the opt-out, so a thread
already gone when Kenso checks it (`404`) or with no text from the person (`400`, detail
`imessage_no_inbound`) gets no opt-out. The opt-out is written before the
interest, so the interest is never stored without it: a text that arrives, or a delete that lands, while the
opt-out is written answers `400` (detail `imessage_newer_text`) or `404`, and the opt-out stands. If the opt-out cannot be written, the
answer is `500 internal_error` and the interest is not stored, but part of the opt-out may already stand. An
`interest` set before Kenso classed the person's earlier texts still lets Kenso read those texts for a stop in
words: one opts the number out within about a minute, and the interest you set stays.

`personId` needs the `unified_inbox` feature on the workspace and Accounts edit. Kenso checks the link
before it writes any field and writes the link last, so a refused field leaves no link.

The response is the updated thread. It carries `hasDraft` and `draftAuthor`, and leaves out
`accountId`, `replyTouchId` and `scheduledMessages`.

A Facebook thread takes `isRead` only. A WhatsApp thread takes no `interest` or `reminderAt`. A
WhatsApp or iMessage thread does not take `personId`: its person comes from its number.

Errors:

- `400 validation_failed`: the body is not an object, has no field, names an unknown field, or holds a value
of the wrong type or an unknown value; the thread's channel does not take a field (see above); or an iMessage
`interest` has no text from the person to label (detail `imessage_no_inbound`), or a newer one arrived
first (detail `imessage_newer_text`).
- `403 forbidden`: the caller is a workspace key and the body sets `interest`. The label reads as set by a
person, and a workspace key is not one. Every other field works for it.
- `403 permission_denied`: the body sets `personId` and the caller lacks Accounts edit.
- `404 not_found`: the thread is not in this workspace, or the body sets `personId` and the person is
not in the workspace, was deleted, or the `unified_inbox` feature is off.
- `422 unprocessable`: the body sets `personId` and the thread has no contact.
- `500 internal_error`: Kenso could not update the thread, or read it back after the update, for a fault of
its own (try it again), for example an iMessage `unsubscribe` that could not write its opt-out (see above).

Requires Inbox edit.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/threads/PATCH/v1/threads/%7BthreadId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `threadId` | path | string | yes | The thread's `thr_` id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |
| `Idempotency-Key` | header | string | no | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the `Idempotent-Replayed: true` header, and Kenso does not run the action twice. The same key with a different request answers `422 idempotency_key_reused`. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get `503 service_unavailable` with `Retry-After`. Retry it with the same key. Kenso does not store a `5xx` response, so a retry after one runs the action again. It does not store a `408`, a `429` or another `4xx` that carries `Retry-After` either: retry with the same key after that time and Kenso runs the action again. |

### Request body

`application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isRead` | boolean | no | True marks the thread read, false unread. Null is refused. |
| `isArchived` | boolean | no | True archives the thread, false moves it back to the inbox. Archiving an email thread archives every reply in it. Null is refused. |
| `isSaved` | boolean | no | True saves the thread, false takes it out of the saved threads. Null is refused. |
| `interest` | string | no | The label: `interested`, `not_interested`, `negative`, `automated`, `unclassified`, `unsubscribe`, `objection`, `wrong_contact`, `referral` or `out_of_office`. `not_interested` reads back as `negative`, and a LinkedIn thread does not take `automated`. On an email thread, any value but `automated`, `out_of_office` and `unclassified` marks the reply as written by a person and stops the contact's sequence. Null is refused. |
| `reminderAt` | string (date-time) | no | When to remind you, as an ISO 8601 instant. Null clears the reminder. |
| `personId` | integer (int64) | no | Links the thread's contact to this person in Accounts, replacing any earlier link. A merged person links as the person it merged into. Needs the `unified_inbox` feature on the workspace and Accounts edit. Null is refused. |

### Response 200

`data` is a `Thread`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The thread's `thr_` id. |
| `channel` | string | The channel: `email`, `linkedin`, `instagram`, `facebook`, `whatsapp` or `imessage`. |
| `direction` | string | Only on `GET /v1/threads`: who sent the newest message the row shows, `inbound` (the contact) or `outbound` (the workspace). On an outbound email row `fromName` is yours, so the contact is the first entry of `to`. A LinkedIn row's `fromName` is the contact either way. Omitted from a single thread and from updates, whose messages carry their own direction. |
| `campaignId` | integer (int64) | The campaign the thread belongs to. Null for a thread outside any campaign. |
| `contactId` | integer (int64) | The contact the thread is with. Null when Kenso matched no contact. |
| `accountId` | integer (int64) | The account the thread belongs to: the account whose touch the thread is. `GET /v1/threads/{threadId}` falls back to the account where the thread's contact is a stakeholder, matched by email, else LinkedIn URL. Omitted when there is none, when the account is outside the accounts the caller may see, or while the accounts feature is off for the caller. |
| `accountName` | string | The name of the `accountId` account. Omitted with it. |
| `replyTouchId` | integer (int64) | Email threads of an account touch, on lists and `GET /v1/threads/{threadId}`: the account's open reply touch that answers a message in this thread, the newest when there are several. Its status is `planned`, `drafted`, `awaiting_approval` or `approved`. Send the reply by approving the touch with `POST /v1/touches/{touchId}/approve`, so the account's plan records it. Omitted without `accountId`, on LinkedIn threads, when there is none or Kenso could not read it, and from updates. |
| `hasDraft` | boolean | True when a reply draft is saved on the thread, whoever wrote it. `GET /v1/threads/{threadId}/draft` returns it. False when Kenso could not read the draft. |
| `draftAuthor` | string | Who last wrote the draft: `user` (a person in the Kenso app) or `agent` (an agent or API key). Omitted without a draft. |
| `inboxId` | integer (int64) | The thread's inbox. For a LinkedIn thread, the LinkedIn account. For an iMessage thread, its line's id. For an email thread, the workspace inbox its message was sent to (a reply you received) or sent from (your own), even when that inbox was deleted since. On `GET /v1/threads` the message is the row's. On `GET /v1/threads/{threadId}` it is the newest inbound message, else the newest. Omitted when the message names no inbox of the workspace. |
| `subject` | string | The subject of the thread's email. Null when it has none. |
| `preview` | string | The newest message's text for a preview, or its HTML when it has no text part. |
| `isRead` | boolean | True when the thread is marked read. |
| `isArchived` | boolean | True when the thread is archived. |
| `isSaved` | boolean | True when the thread is saved. |
| `interest` | string | The label on the thread's newest reply: `interested`, `question`, `not_interested`, `negative`, `automated`, `unclassified`, `unsubscribe`, `objection`, `wrong_contact`, `referral`, `out_of_office`, `hard_bounce`, `soft_bounce`, `complaint`, `unknown` or `ndr` (a non-delivery report). `unclassified` when it has no label. |
| `reminderAt` | string (date-time) | When the reminder on the thread is due, in UTC. Null without a reminder. |
| `lastMessageAt` | string (date-time) | When the newest message was sent or received, in UTC. |
| `waitingSince` | string (date-time) | Only on `GET /v1/threads`: when the contact's newest message arrived, on any tab. It is a wait on your reply only on the To Reply tab: a thread marked done or archived still carries it. A thread you answered whose reminder came due is on To Reply for that reminder, so it carries the reminder's due time. Omitted when the newest message is yours and no reminder is due. |
| `updatedAt` | string (date-time) | When the thread last changed, in UTC. |
| `senderName` | string | The same value as `fromName`. |
| `fromName` | string | Email: the name of the newest message's sender, yours when that message is outbound. LinkedIn: the contact's name, omitted when the conversation names nobody. |
| `fromEmailAddress` | string | Email only: the address of the newest message's sender. |
| `htmlBody` | string | Email only: the newest message's body as HTML. |
| `tags` | array of ThreadTag | The tags on the thread. |
| `to` | array of ThreadRecipient | Email only: the newest message's To recipients. |
| `cc` | array of ThreadRecipient | Email only: the newest message's Cc recipients. |
| `bcc` | array of ThreadRecipient | Email only: the newest message's Bcc recipients. |
| `scheduledMessages` | array of ScheduledMessage | Only on `GET /v1/threads/{threadId}` for an email thread: the replies and forwards queued on this thread that have not sent yet, in `scheduled`, `sending` or `awaiting_approval` status, the soonest due first. An empty list means none are pending. Omitted from lists, from updates, and when Kenso could not read them. |
| `referral` | ThreadReferral | The person a recruiting reply referred you to, when its `interest` is `referral`. Set on `GET /v1/threads/{threadId}` for an email thread. Null on lists, on LinkedIn threads and for every other reply. |
| `browserRun` | ThreadBrowserRun | The workflow browser run whose web form submission this thread answers, or null. Set on `GET /v1/threads` rows and `GET /v1/threads/{threadId}`. The Kenso app labels such a thread as a browser run and never counts it as a reply. |
| `language` | string | The language of the newest inbound message, as an ISO 639-1 code such as `en`. On `GET /v1/threads` an email row carries its own message's, so a row whose newest message is yours has none. Omitted when unknown. |
| `imessage` | ThreadImessage | iMessage only: the line, the number, whether the person replied (images and voice notes need it) and whether the thread goes by SMS (text only). Omitted on other channels. |
| `historyStartsAt` | string (date-time) | Facebook only: the oldest point this thread's history reaches while the account's history is locked. Omitted once it is unlocked and on every other channel. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/threads/thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "isRead": true,
  "isArchived": false,
  "isSaved": true,
  "interest": "interested",
  "reminderAt": "2026-10-15T18:30:00Z",
  "personId": 77310
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20",
    "channel": "email",
    "direction": "inbound",
    "campaignId": 4821,
    "contactId": 90125,
    "hasDraft": false,
    "inboxId": 5530,
    "subject": "Re: Onboarding new engineers at Northwind Labs",
    "preview": "Thanks Alex, this is timely. We are hiring 12 engineers this quarter. Could we talk Thursday afternoon?",
    "isRead": false,
    "isArchived": false,
    "isSaved": false,
    "interest": "interested",
    "lastMessageAt": "2026-10-13T16:22:05Z",
    "waitingSince": "2026-10-13T16:22:05Z",
    "updatedAt": "2026-10-13T16:22:05Z",
    "senderName": "Amanda Chen",
    "fromName": "Amanda Chen",
    "fromEmailAddress": "amanda.chen@northwind.example.com",
    "htmlBody": "<p>Thanks Alex, this is timely. We are hiring 12 engineers this quarter.</p><p>Could we talk Thursday afternoon?</p><p>Amanda</p>",
    "tags": [
      {
        "id": 341,
        "name": "Hot lead",
        "color": "#FFD6A5"
      }
    ],
    "to": [
      {
        "name": "Alex Rivera",
        "address": "alex@mail.example.com"
      }
    ],
    "language": "en"
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### ThreadTag

A tag on a thread or message.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The tag's id. |
| `name` | string | no | The tag's name. |
| `color` | string | no | The tag's display color. |
| `systemKey` | string | no | Set on a built-in Kenso tag: a fixed key to find it by, which stays the same when its name changes. Null on the workspace's own tags. |

### ThreadRecipient

An email recipient.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The display name. Null when the email gives none. |
| `address` | string | no | The email address. |

### ScheduledMessage

An email reply or forward that Kenso queued to send after its undo window.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The scheduled message's id. `POST /v1/scheduled-messages/{scheduledMessageId}/cancel` takes it. |
| `messageId` | string | no | The `msg_` id of the message it replies to or forwards. |
| `kind` | string | no | The kind of message: `reply` or `forward`. |
| `status` | string | no | The message's status: `scheduled`, `sending`, `sent`, `cancelled`, `failed` or `awaiting_approval`. |
| `approverMemberId` | integer (int64) | no | With status `awaiting_approval`: the member who must approve the message before it sends, the owner of the sending mailbox. `GET /v1/members` gives their name. |
| `delaySeconds` | integer (int32) | no | The undo window in seconds, 60 or 300. |
| `sendAt` | string (date-time) | no | When Kenso sends the message, in UTC. |
| `createdAt` | string (date-time) | no | When Kenso queued the message, in UTC. |
| `body` | string | no | The message's body. |
| `senderEmailId` | integer (int32) | no | The id of the inbox that sends the message. |
| `to` | array of ThreadRecipient | no | The To recipients. Null when none were named. |
| `cc` | array of ThreadRecipient | no | The Cc recipients. Null when none were named. |
| `bcc` | array of ThreadRecipient | no | The Bcc recipients. Null when none were named. |
| `draft` | ScheduledMessageDraft | no | On a cancel: the message, saved back as the thread's draft. |

### ThreadReferral

The person a recruiting reply referred you to, when its interest is `referral`. Every part comes from the reply itself, and a part the reply does not give is null.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The person's name. |
| `email` | string | no | The person's email address. |
| `linkedinUrl` | string | no | The person's LinkedIn profile URL. |
| `phone` | string | no | The person's phone number as the reply writes it. Kenso cannot add a person with only a phone number as a contact, so add them by hand. |

### ThreadBrowserRun

The workflow browser run whose web form submission a thread or message answers.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `runId` | string | no | The browser run's id, as a string. |
| `automated` | boolean | no | True when the headers and the sender show that a machine sent the email, such as a form confirmation or a notification. |

### ThreadImessage

An iMessage thread's line, number and reply state.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `lineId` | integer (int64) | no | The workspace's iMessage line the thread is on (`GET /v1/imessage-lines/{lineId}`). |
| `phone` | string | no | The person's number in E.164 (`+14155550100`). |
| `hasReplied` | boolean | no | The person texted this line at least once. Images and voice notes go only after that. |
| `isSmsThread` | boolean | no | The thread goes by SMS (green bubbles): text only, no images or voice notes. A tapback there arrives as a text, so only a member sends one; an agent's or API key's is `409` `imessage_sms_thread`. |
| `personId` | integer (int64) | no | The person the conversation is with: the `personId` to make a voice note for this thread with (`POST /v1/voice-notes`). Omitted when the conversation has no person. |
| `isNameless` | boolean | no | No name was found for the person on this thread, so the thread's `fromName` and `senderName` are their number. Show the thread as a conversation with an unknown person. |
| `voiceNoteInProgress` | ThreadVoiceNoteInProgress | no | The voice note Kenso is making for this thread right now (`POST /v1/voice-notes` with this thread's `threadId`), so the app can show it being made after a reload instead of starting a second one. Poll it with `GET /v1/voice-notes/{voiceNoteId}`. Omitted when none is being made. |
| `ownerName` | string | no | The member who owns the thread's line: texts on this thread go out in their name. Their first and last name, else their email. Omitted when the owner's account is gone. |
| `ownerLeft` | boolean | no | The line's owner can't send from it anymore (they are no longer an active member of the workspace, or are a network member), so nothing goes on this thread until an admin gives the line a new owner in Delivery. Always false for a released or failed line. |
| `voiceNoteReady` | ThreadVoiceNoteReady | no | The newest voice note you made for this thread in the last 30 minutes (`POST /v1/voice-notes` with this thread's `threadId`, or with neither a touch nor a thread while this was the person's latest thread) that is ready and not sent yet, so a create that timed out on your side but finished is offered instead of made and charged again. Only a note the calling member asked for (`createdByMemberId`); never another member's, and none for an API key with no member. Only on a single thread (`GET /v1/threads/{threadId}` and the thread an update returns), never on a list row; omitted when there is none. A read that fails fails the thread read (500 `internal_error`), so a missing field always means there is no such note. |

### ScheduledMessageDraft

A cancelled message, saved back as the thread's draft.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messageId` | string | no | The `msg_` id of the message the draft replies to or forwards. |
| `kind` | string | no | The kind of message: `reply` or `forward`. |
| `body` | string | no | The draft's body. |
| `senderEmailId` | integer (int32) | no | The id of the inbox the draft sends from. |
| `to` | array of ThreadRecipient | no | The draft's To recipients. Null when none. |
| `cc` | array of ThreadRecipient | no | The draft's Cc recipients. Null when none. |
| `bcc` | array of ThreadRecipient | no | The draft's Bcc recipients. Null when none. |
| `saved` | boolean | no | False when the cancel went through but Kenso could not save this draft as the thread's draft. The draft is still here, so save it yourself. |

### ThreadVoiceNoteInProgress

A voice note being made for an iMessage thread.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The voice note's id. |
| `status` | string | no | Its status: `generating` while it is being made. |
| `createdByMemberId` | integer (int64) | no | The member who asked for it, as their member id. Omitted for a note an API key with no member asked for. |

### ThreadVoiceNoteReady

A ready voice note made for an iMessage thread and not sent yet.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voiceNoteId` | integer (int64) | no | The voice note's id: send it as the `voiceNoteId` of a reply, or read it with `GET /v1/voice-notes/{voiceNoteId}`. |
| `createdAt` | string (date-time) | no | When the note was asked for. |
| `createdByMemberId` | integer (int64) | no | The member who asked for it, as their member id. Omitted for a note an API key with no member asked for. |
| `durationMs` | integer (int32) | no | The note's length in milliseconds. Omitted when it was not measured. |
