Skip to content
Stashtab Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

Was this page helpful?