# Update a conversation

`PATCH /v1/inbox/conversations/{conversation_id}`

Marks a conversation read or unread, or archives or restores it.

**Scope:** `inbox:reply`

**Access:** The key's member must be able to see the conversation in the inbox.

Send exactly one of `read` or `archived` per request; to change both, send two requests. It is the same change your team makes in the inbox, and it never takes messages out of the inbound feed. There is no delete.

Archiving closes the conversation (`status` becomes `closed` unless it is `suppressed`), marks it read, turns the AI agent off for it (`ai_status` becomes `disabled`) and cancels its pending AI replies. Replies are refused while it is archived. Restoring (`archived: false`) sets `status` back to `open` (a `suppressed` conversation stays `suppressed`); it does not turn the AI agent back on and sends nothing.

Repeating a request is safe. If a `PATCH` after a reply fails, retry the `PATCH`; never resend the email to fix the conversation's state.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | `UUID` | Yes | The conversation. |

## Body

**Content type:** `application/json`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `read` | `boolean` | No | `true` marks it read, `false` unread. Send exactly one of `read` or `archived`. A JSON boolean; strings and numbers are rejected. |
| `archived` | `boolean` | No | `true` archives it, `false` restores it. Send exactly one of `read` or `archived`. A JSON boolean; strings and numbers are rejected. |

## Response

**Status:** `200 OK`

| Name | Type | Description |
| --- | --- | --- |
| `id` | `UUID` | The conversation. |
| `read` | `boolean` | Whether it is read now. |
| `archived` | `boolean` | Whether it is archived now. |
| `status` | `string` | Its status now. One of `open`, `needs_review`, `booked`, `not_interested`, `closed`, `suppressed`. |
| `updated_at` | `timestamp` | When it last changed (RFC 3339, UTC). |

## Example request

**curl**

```bash
curl -X PATCH "https://development.agencydevworks.ai/v1/inbox/conversations/44444444-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer dei_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "archived": true
}'
```

**JavaScript**

```js
const response = await fetch("https://development.agencydevworks.ai/v1/inbox/conversations/44444444-0000-4000-8000-000000000002", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer dei_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "archived": true
  }),
});
const data = await response.json();
```

## Example response

**Status:** `200 OK`

```json
{
  "id": "44444444-0000-4000-8000-000000000002",
  "read": true,
  "archived": true,
  "status": "closed",
  "updated_at": "2026-11-02T16:25:41Z"
}
```

## Errors

| HTTP | Code | When |
| --- | --- | --- |
| 403 | `insufficient_scope` | The key does not have `inbox:reply`. Checked before the body is validated. |
| 404 | `not_found` | The conversation does not exist, was deleted, or the key's member cannot see it. |
| 409 | `reply_in_progress` | Archiving: a reply to the conversation is being sent right now. `retryable` is `true`: retry shortly. |
| 413 | `payload_too_large` | The body is larger than 1 MB. It was not read and nothing changed. |
| 422 | `invalid_request` | `conversation_id` is not a UUID, or the body is not exactly one of `read` or `archived` as a boolean. `error.fields` names `body` (none or both sent), the field that is not a boolean, or an unknown field. |
| 503 | `dependency_unavailable` | The inbox or the access check is temporarily unavailable. Retry with backoff. |

Every endpoint can also answer `401 invalid_api_key`, `429 rate_limited` and `503 dependency_unavailable`. See [Errors](/api/#errors) in the overview.

## Related endpoints

- `GET /v1/inbox/conversations/{conversation_id}` · [Retrieve a conversation](/api/inbox/get-conversation)
- `POST /v1/inbox/conversations/{conversation_id}/replies` · [Reply to a conversation](/api/inbox/reply)
- `GET /v1/inbox/conversations` · [List conversations](/api/inbox/list-conversations)