---
title: "Upsert inbox-item state in one transaction"
method: PATCH
path: "/api/inbox-state/bulk"
tags: ["Inbox State"]
---

# Upsert inbox-item state in one transaction

`PATCH /api/inbox-state/bulk`

## Request

- Base URL: `http://localhost:3013`
- URL: `http://localhost:3013/api/inbox-state/bulk`
- Auth: HTTP bearer

## Request body

- object
  - `userId` string, required
  - `items` object[], required
    - `itemType` 'approval' | 'credential_missing' | 'broken_task' | 'to_read' | 'to_start_template' | 'notification', required
    - `itemId` string, required
    - `status` 'open' | 'snoozed' | 'dismissed' | 'done', required
    - `snoozeUntil` string, date-time
    - `readAt` string, date-time
    - `lastReadAt` string, date-time, nullable: Omit to preserve the read cursor, send null to clear it, or send a timestamp to set it, including an earlier time.

## Response `200`

Upserted inbox state rows in request order

- object
  - `items` InboxItemState[], required
    - `id` string, required
    - `userId` string, required
    - `itemType` 'approval' | 'credential_missing' | 'broken_task' | 'to_read' | 'to_start_template' | 'notification', required
    - `itemId` string, required
    - `status` 'open' | 'snoozed' | 'dismissed' | 'done', required
    - `snoozeUntil` string
    - `dismissedAt` string
    - `doneAt` string
    - `readAt` string
    - `lastReadAt` string
    - `createdAt` string, required
    - `lastUpdatedAt` string, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: A non-admin user token wrote another user's state

## Changes

- **2026-10-27** `b6cfdb1f4830`: 1 info
  - added the non-success response with the status `403`
- **2026-10-18** `995a545ba2c9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/inbox-state/bulk/patch.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) - [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/7e4c7198192a?raw)