---
title: Poll opening revisions
description: Read exact captured openings, resume a checkpoint, and discover later corrections.
sidebar:
  order: 5
---

Warehouse staff record openings and corrections independently of outbound
reporting. An external consumer reads the feed and owns its ingestion
checkpoint. A recorded opening or a successful poll does not acknowledge that
consumer's ingestion.
Warehouse stock outcomes are tracked separately from the recorded contents.

## Ordinary customer HTTP access

A current customer Viewer or above can read recorded openings for an authorized
organization. No opening-specific service client is required. Use the Vault
session established by the console, or an existing registered confidential HTTP
integration whose verified external subject maps to a current customer member.
[Authentication and scope](/authentication) explains both paths.

For a signed-in HTTP caller, send the existing session cookie with the request.
For an existing confidential integration, keep its credentials server-side:

```bash
curl --user "$CLIENT_ID:$CLIENT_SECRET" \
  "$VAULT_BASE_URL/v1/organizations/$ORG_ID/openings?limit=50"
```

An organization API key with either Read-only or Read/write permission can also
read this feed. Send its server-side `vak1...` credential as
`Authorization: Bearer $VAULT_ORGANIZATION_API_KEY`. The key must be bound to
the organization in the path; a Test key is refused while ordinary Test
business storage remains unavailable.

The organization ID selects the customer; it does not grant access. Vault
rechecks current membership and, for an integration, its current subject binding
and organization allowance on every read. Foreign organizations are denied.
Removing membership denies later reads, including requests with a saved cursor.

## Ordinary customer MCP access

Use an existing person-delegated MCP connection with a current customer Viewer
or above and consent for the selected organization. Call `opening_revisions_list`
with that organization's ID and the same pagination inputs:

```json title="example:opening-feed-mcp-call"
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "opening_revisions_list",
    "arguments": { "organizationId": "org_customer_demo", "limit": 50 }
  }
}
```

Send the person-delegated access token or an organization API key to
`$VAULT_BASE_URL/mcp` as a bearer token. A confidential HTTP client's Basic
credentials do not authenticate MCP. Consent limits which current memberships
the person-delegated connection can use; later membership does not widen
consent. Revoking consent or removing membership denies a person-delegated
caller's next read, including one with a saved checkpoint. An organization API
key is organization-owned: the creator's later departure does not revoke it,
while revoking the current key denies its next read. See [Authentication and
scope](/authentication) for OAuth discovery, PKCE, consent and organization-key
scope.

HTTP returns `data` and `meta.nextCursor`; the MCP tool's structured result
returns `items` and `nextCursor`. Both expose the same immutable revisions.
Keep a separate checkpoint for each caller and channel.

For MCP continuation, copy the tool's `nextCursor` into
`params.arguments.cursor` on the next `opening_revisions_list` call, retaining
the same `organizationId`. Read `items` for the page contents and continue until
`items` is empty. Persist that checkpoint after ingesting the page; an empty
page retains it for a later poll. The HTTP `data`, `meta.nextCursor`, and query
parameter instructions below apply to HTTP callers; the same persistence and
exhaustion rules apply to MCP's `items`, `nextCursor`, and tool arguments.

## Optional machine-service access

A separately registered nonhuman service client with an explicit customer-scoped
grant is an optional authentication path. Arrange that client and grant with
Stashtab only when a machine service is needed. Use the HTTP `client_credentials`
resource described in [Authentication and scope](/authentication), then send
its bearer token to the same openings endpoint.

A live inbound grant permits only `listOpeningFeed`; grants containing any
other operation are denied. The isolated HTTP proof exercises this live grant
policy without creating a Production client. Production client provisioning and
an external consumer's use of the response contract require separate
verification. The service receives only its organization's opening contents.
Its grant does not permit staff operations or mutations. Every request rechecks current
client and grant authority, including revocation of an unexpired token.

## Persist contents and the checkpoint

The response uses `data` and `meta.nextCursor`. Each item contains a stable
`openingRef`, its original `createdAt`, a positive `revision`, that revision's
`recordedAt`, and the `supplyPurchaseOrderId`. Its `rows` preserve the exact
within-pack order, duplicate occurrences, assessed conditions, catalog and
binding identities, SKU snapshots, and printed serial number and run. Count
every row: repeated cards are repeated copies. A null SKU or serial is an
explicit absent value; do not replace a captured SKU with today's catalog.

Ingest and deduplicate by **organization + openingRef + revision**. Persist
the returned opaque checkpoint only after your ingestion of that page has
succeeded. On failure, retain the previous checkpoint and request the same
page again. Vault retains earlier versions when staff correct an opening.

Pass `meta.nextCursor` unchanged as the next request's `cursor` query
parameter. `limit` defaults to 50 and accepts 1 through 100. A checkpoint is
bound to its customer, caller, and operation; it cannot be transferred to a
different principal or customer. Records published while polling appear
after the prior checkpoint, including a later correction to an older opening.

## Exhausted and empty pages

A short page can still have a checkpoint. Continue until `data` is empty.
After emitting any revision, an exhausted or empty page retains the last
checkpoint; a non-null cursor is not a promise that more rows are currently
available. Save it and use it on the next poll. An initially empty feed has a
null checkpoint; poll again without a cursor until an item appears.

Polling performs no stock write, acceptance, deletion, or ingestion marker.
There is no ingestion acknowledgement endpoint or background push worker.
Actual external-consumer authentication, catch-up, restart from a saved
checkpoint, and correction ingestion must be verified before calling the
handoff operational.

The [generated API reference](/reference) owns the response schema and the
[MCP tool catalog](/warehouse-mcp-tools.json) describes `opening_revisions_list`.

## Staff deletion revisions

Staff can delete an erroneous opening with a reason. Vault appends a revision
with `deleted: true` and empty `rows`; earlier revisions remain immutable.
Apply this tombstone to that opening when polling rather than treating it as
an empty physical pack. All ordinary revisions have `deleted: false`. The
feed does not expose the staff reason or inventory journal. Staff inventory
undo is separate; the deletion revision does not acknowledge external-consumer
ingestion.
