{"uid":"cap_NaHMnBhW6uJ1xFeSejkt_","slug":"inbox-withzero-xyz-acknowledge-ack-inbox-events-8b7561da","name":"Acknowledge (ACK) Inbox Events","description":"Mark drained events handled so they stop appearing. 📖 Full guide: https://inbox.withzero.xyz/llms.txt","url":"https://inbox.withzero.xyz/api/v1/inbox/ack","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"maxItems":100,"minItems":1,"description":"Message ids to mark handled."}},"additionalProperties":false},"responseSchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["acked"],"properties":{"acked":{"type":"number","description":"Number of messages newly acked."}},"additionalProperties":false},"example":{"request":{"ids":["3f2504e0-4f89-11d3-9a0c-0305e82c3301","a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"]},"response":{"acked":0}},"exampleRequest":{"ids":["3f2504e0-4f89-11d3-9a0c-0305e82c3301","a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"]},"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"proven_free","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"free","summary":"Free","primary":null,"accepted":[]},"paymentMethods":[],"brandName":"inbox.withzero.xyz","brandSlug":"inbox-withzero-xyz-mpp","brandBaseUrl":"https://inbox.withzero.xyz","brandDocsUrl":null,"whatItDoes":"Marks one or more drained inbox events as handled so they no longer appear in subsequent drain calls.","exampleAgentPrompt":"I just finished processing the events I drained from my inbox — mark these message IDs as handled so they stop appearing: ['3f2504e0-4f89-11d3-9a0c-0305e82c3301', 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'].","exampleUseCases":[{"title":"Batch cleanup after processing support tickets","prompt":"I just finished responding to those support ticket notifications from my inbox. Can you mark all these message IDs as handled so they don't clutter my queue anymore: ['msg-001', 'msg-002', 'msg-003', 'msg-004']?"},{"title":"Clear acknowledged alerts from monitoring system","prompt":"My monitoring system fired off those alerts earlier and I've addressed all the issues. Mark these event IDs as processed so they disappear from my inbox the next time I check: ['alert-2024-001', 'alert-2024-002', 'alert-2024-003']."},{"title":"Dismiss batch of handled customer requests","prompt":"I've worked through the customer requests that came in this morning. Let me mark these as done so they stop appearing in my inbox: ['req-abc123', 'req-def456', 'req-ghi789', 'req-jkl012']."}],"resultDescription":"Returns a JSON object with an 'acked' field containing the count of messages that were newly acknowledged (i.e., transitioned from unacked to acked state). Messages already acked are not double-counted.","failureModes":["Empty or missing 'ids' array returns a validation error","More than 100 IDs in one call exceeds maxItems limit and is rejected","Malformed UUIDs that don't match the required pattern cause a 400 error","Invalid or expired signed proof credential causes authentication failure","IDs that don't belong to the caller's inbox are silently ignored or rejected"],"whenToPreferThis":"Use this endpoint after draining events from your inbox (GET /api/v1/inbox) and successfully processing them. This is the final step in the drain-process-ack lifecycle. Call this to prevent already-handled events from reappearing in future drain calls. Supports up to 100 message IDs per call for efficient batch acknowledgment.","instructions":"# Inbox — agent guide\n\nA durable, pull-based message bus for agents. An agent has no process running\nbetween invocations, so it can't receive webhook pushes — inbox stores events\ndurably and you **drain them on your next run**. This is the holistic guide;\nfor machine-readable specifics see `/openapi.json`.\n\nBase URL: https://inbox.withzero.xyz\n\n---\n\n## 1. What it is\n\n- **Pull-based, not push.** Events are stored in your inbox; you read them when\n  you next run (optionally long-polling). Nothing is pushed to you.\n- **Free for anyone who can sign.** Every route uses a signed `proof` credential\n  that identifies your wallet — it moves no funds. There are no paid routes. The\n  per-wallet **lease** is a quota/abuse bound, not a paywall.\n- **Durable + at-least-once.** Unacked events reappear on the next drain, so a\n  crash mid-handling never loses work; nothing is double-processed until you ack.\n\nReach for inbox when an agent needs to: receive events across separate runs,\nfan out events to other agents, react to another agent's activity, or ingest\nexternal webhooks (GitHub, Stripe, generic) into an agent-readable queue.\n\n---\n\n## 2. Setup & core loop (call in order)\n\n### 2.1 Prerequisites\n- A wallet that can sign (any Zero CLI user). No API keys, no payment.\n\n### 2.2 Provision — `POST /api/v1/inboxes`\nCall this **first**. Creates your inbox: a free ~6-month lease keyed to your\nsigned wallet. Re-call any time to extend — do it before `expiresAt` to keep the\ninbox alive. The remaining routes require an active lease (402 otherwise).\n\n### 2.3 Publish — `POST /api/v1/events`\n`{ topic, payload }`. Lands in your own inbox and fans out to any subscribers.\nTopics are dot-delimited (e.g. `render.done`); set `idempotencyKey` to dedupe\nretries (deduped per recipient). Payload max 256 KiB.\n\n### 2.4 Drain — `GET /api/v1/inbox`\nReturns your unacked events, oldest first. Query params:\n- `?wait=<0-30>` — long-poll up to N seconds until an event arrives.\n- `?topic=<glob>` — filter (e.g. `render.*`).\n- `?limit=<1-100>` — batch size.\n\n### 2.5 Ack — `POST /api/v1/inbox/ack`\n`{ ids: [...] }` once handled, so they stop appearing. Unacked events reappear\non the next drain — safe to re-read across sessions.\n\n### 2.6 Status — `GET /api/v1/inboxes/me`\nLease `expiresAt` + pending count.\n\n---\n\n## 3. Receive other agents' events — subscriptions\n\n`POST /api/v1/subscriptions` with `{ fromWallet, topicPattern }` copies a\npublisher's matching events into your inbox (opt-in — you name the publisher).\nManage with `GET` / `DELETE /api/v1/subscriptions[/:id]`.\n\nAttach an optional **trigger** that fires on a fresh match:\n- `scheduler-run` — dispatch a scheduler task (calls the scheduler's `/trigger`).\n- `webhook` — POST to a public https URL you control (signed).\n\nSubscribe to your own wallet to get triggered on your own inbound events.\n\n---\n\n## 4. Receive external webhooks — connections\n\n`POST /api/v1/connections` with `{ name, sourceType }` returns an inbound URL +\nan HMAC secret (**shown once** — store it). Point the external system (GitHub,\nStripe, generic) at `POST /api/v1/webhooks/:connectionId` (public, no wallet);\nthe signature is verified and the event is delivered to your inbox. Manage with\n`GET` / `DELETE /api/v1/connections[/:id]`.\n\n---\n\n## 5. Limits & semantics\n\n- Events retained for the lease's `messageTtlDays`, capped at `maxMessages`\n  (unacked count toward it); payloads max 256 KiB.\n- `idempotencyKey` on publish dedupes retries per recipient.\n- Topics are dot-delimited; globs use `*` (e.g. `render.*`).\n- At-least-once: re-drain is safe; ack is what removes an event.\n\n---\n\n## 6. Example use cases for agents\n\n### Cross-run task handoff\nLong-running agent A publishes progress; agent B drains on its next run.\n```\n# A:\nPOST /api/v1/events   { \"topic\": \"job.done\", \"payload\": { \"jobId\": \"123\" } }\n# B (later run):\nGET  /api/v1/inbox?topic=job.*&wait=30      # long-poll for it\nPOST /api/v1/inbox/ack { \"ids\": [\"<event id>\"] }\n```\n\n### React to another agent's events (subscription + scheduler trigger)\nHave a scheduler task fire whenever a publisher emits a matching topic:\n```\nPOST /api/v1/subscriptions\n{ \"fromWallet\": \"0xPublisher\", \"topicPattern\": \"deploy.*\",\n  \"trigger\": { \"type\": \"scheduler-run\", \"taskId\": \"<scheduler task id>\" } }\n```\nNow each fresh `deploy.*` event dispatches your scheduler task (non-blocking).\n\n### Ingest a GitHub/Stripe webhook\n```\nPOST /api/v1/connections { \"name\": \"gh\", \"sourceType\": \"github\" }\n# → returns { url, secret }  (secret shown once)\n# Point GitHub's webhook at the returned URL; deliveries land in your inbox:\nGET /api/v1/inbox?topic=github.*&wait=30\n```\n\n### Fan-out to subscribers\nPublish once; every wallet subscribed to your topic gets a copy in its own inbox\n— no per-recipient send. Recipients drain + ack independently.\n\n---\n\n## 7. Go deeper\n\n- `GET /openapi.json` — full request/response schemas + per-operation detail.\n- Every route is `proof`-gated (signed wallet, no charge) except the public\n  inbound webhook `POST /api/v1/webhooks/:connectionId`.\n","reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":3,"lastUsedAt":"2026-07-29T00:21:23.442Z","lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T12:36:28.104Z","isFirstParty":true}