Poll opening revisions
Read exact captured openings, resume a checkpoint, and discover later corrections.
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 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:
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:
{
"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 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, 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 owns the response schema and the
MCP tool catalog 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.