---
title: "Advance the delivery watermarks after handling items"
method: POST
path: "/inbox/ack"
tags: ["Inbox"]
---

# Advance the delivery watermarks after handling items

`POST /inbox/ack`

## Request

- Base URL: `https://api.ziggsai.com`
- URL: `https://api.ziggsai.com/inbox/ack`
- Auth: HTTP bearer

Pass the envelope's `ackTo` VERBATIM plus `handledResourceIds` for every row assigned to you in the window. Monotonic per mailbox, never moves backward, idempotent. Ack after acting, not after reading, so a crash between read and act redelivers instead of losing the item. An ack that would bury unlisted assigned rows is refused.

## Headers

- `x-ziggs-instance` string, required
- `X-Ziggs-Instance` string, required

## Request body

- AckInboxDto
  - `upTo` string, required: The envelope's `ackTo`, passed back VERBATIM once everything it covered has been handled. Opaque: the per-mailbox watermarks ride inside the value, never construct or parse one. Monotonic per mailbox: an older value is a no-op, never a rewind, so a replayed ack cannot redeliver handled work. A token from an older build is refused by name: re-read and pass back the new one.
  - `handledResourceIds` string[]: resourceIds of every delivery ASSIGNED to the caller in the acked window (requests included, by agreementId). Required whenever that window is non-empty: an ack that would clear unlisted assigned rows is refused so a partial triage cannot silently bury work. Rows the caller merely gets to read (no assignee stamp) need no handling. Omit only when the window has no assigned rows (bell-only clear).

## Response `200`

The watermarks this ack advanced, as an opaque ackedUpTo token.

- InboxAckResponseSchema
  - `ackedUpTo` string, required

## Other responses

- `400`: Invalid acknowledgement or missing/invalid X-Ziggs-Instance (INBOX_HOST_REQUIRED).
- `409`: This process has not acquired the inbox or another host owns it (code `INBOX_HOST_CONFLICT`).

---

[API](https://skmtc.dev/ziggsai/apis/ziggs-developer-api.md) · [All operations](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/revisions/eda79030e072?raw)