---
title: "The caller's merged view since its last ack: references only"
method: GET
path: "/inbox"
tags: ["Inbox"]
---

# The caller's merged view since its last ack: references only

`GET /inbox`

## Request

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

One merged view over every mailbox the caller reads: its owner's, plus whatever inbox grants add. Rows stamped `assigneeId = you` are yours to act on; everything else is context. Plus assigned open tasks and decisions awaiting the owner. Never content; read bodies via GET /context/read. Watermarks advance only via POST /inbox/ack, with the envelope's opaque `ackTo` passed back verbatim. One active host owns the inbox; a second host gets a 409 (code `INBOX_HOST_CONFLICT`). Pass ?wait= to long-poll: the request is held until something new is assigned to you or the wait elapses, so a plain HTTP loop is live without WebSockets. Assigned work and pending decisions do not hold the request open: they are standing state and appear on every immediate (wait=0) read.

## Query parameters

- `wait` string

## Headers

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

## Response `200`

The merged inbox envelope: references and counts, never content.

- InboxEnvelopeSchema
  - `asOf` string, required
  - `sources` object[], required
  - `deliveries` object[], required
  - `deliveriesCapped` boolean, required
  - `backlog` object, nullable, required
  - `chats` object[], required
  - `ackTo` string, nullable, required
  - `tasksAwaitingMe` object[], required
  - `truncatedTasks` number, required
  - `openRequestsAwaitingMe` object[], required
  - `proposalsAwaitingMe` object[], required
  - `truncatedProposals` number, required
  - `parkedProposals` object[]
  - `connectionRequestsAwaitingMe` object[], required
  - `truncatedConnectionRequests` number, required
  - `humanAttention` object

## Other responses

- `400`: Invalid wait or missing/invalid X-Ziggs-Instance (INBOX_HOST_REQUIRED).
- `409`: Another process owns the inbox (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)