Vault by Stashtab API

The Vault by Stashtab API lets partner applications declare expected arrivals, observe every physical item held in custody, request parcel fulfillment or withdrawal, transfer items through supported exit paths, and receive signed event notifications. Responses are suitable for mirroring into partner systems.

Authentication

Every request is authenticated with an API key in the X-API-Key header. Keys are managed in the partner console, are named, may carry an expiry, and can be deactivated at any time. Keys must only be used server-side.

Idempotency

Every POST accepts an Idempotency-Key header. Reusing the same key on the same endpoint returns the original result instead of repeating the action. Keys are retained long enough for any reasonable retry policy.

Forward compatibility

Within v1, new fields, enum values, error codes, item types, and endpoints are non-breaking additions. Clients must tolerate values they do not yet know. Breaking changes use a new version prefix and are announced in advance.

Environments & data partitioning

Production and sandbox use separate hosts and fully partitioned data. sk_live_* keys work only on production and sk_test_* keys work only on sandbox. Using a key on the wrong host returns 401 environment_mismatch. A QID from the other environment returns a plain 404 so existence is not disclosed.

Error codes

Errors use a stable machine-readable vocabulary: validation_error, state_conflict, environment_mismatch, unsupported_destination, invalid_api_key, not_found, and rate_limited. Each operation lists its possible HTTP error codes in x-error-codes; partial-success batch responses carry row-result codes in their result body.