> ## Documentation Index > Fetch the complete documentation index at: https://docs.endstate.io/llms.txt > Use this file to discover all available pages before exploring further. # List a unit's vault requests > Returns the unit's vault requests, oldest first, as a cursor-paginated list. Use it to find the request for an item: at most one of a unit's requests is open at a time, with `status` `pending`, `submitted`, `active`, `unvault_waiting` or `unvaulting`, and the one that reads `active`, `unvault_waiting` or `unvaulting` is the item's current stay in a vault. Takes an API key, which reads any unit in its environment. A tap session token is not accepted: call this from your server. ## OpenAPI ````yaml /openapi.json get /v1/units/{unit_id}/vault-requests openapi: 3.1.0 info: title: Endstate API version: 0.1.0 description: Endstate developer API for chip verification and ownership workflows. servers: - url: https://api2.endstate.io description: Production - url: https://api-staging.endstate.io description: Staging security: [] paths: /v1/units/{unit_id}/vault-requests: get: tags: - Vaults summary: List a unit's vault requests description: >- Returns the unit's vault requests, oldest first, as a cursor-paginated list. Use it to find the request for an item: at most one of a unit's requests is open at a time, with `status` `pending`, `submitted`, `active`, `unvault_waiting` or `unvaulting`, and the one that reads `active`, `unvault_waiting` or `unvaulting` is the item's current stay in a vault. Takes an API key, which reads any unit in its environment. A tap session token is not accepted: call this from your server. operationId: listVaultRequests parameters: - schema: type: string format: uuid description: Unit id. example: 22222222-2222-4222-8222-222222222222 required: true description: Unit id. name: unit_id in: path - schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum number of records to return. Defaults to 50; maximum 100. required: false description: Maximum number of records to return. Defaults to 50; maximum 100. name: limit in: query - schema: type: string minLength: 1 description: Opaque cursor from the previous page. required: false description: Opaque cursor from the previous page. name: cursor in: query - schema: type: string enum: - pending - submitted - active - unvault_waiting - unvaulting - unvaulted - cancelled - expired - rejected - failed description: Filter to requests with this status. required: false description: Filter to requests with this status. name: status in: query responses: '200': description: A page of vault requests. content: application/json: example: vault_requests: - id: 00000000-0000-4000-8000-000000000000 unit_id: 22222222-2222-4222-8222-222222222222 vault: id: 33333333-3333-4333-8333-333333333333 name: Alliance Vault logo_url: https://vault.example/logo.png key_mode: managed status: pending notes: null rejection_reason: null decided_at: null available_at: null hold: null ready_to_ship: false dispatched_at: null expires_at: '2026-07-15T12:00:00.000Z' created_at: '2026-06-15T12:00:00.000Z' pagination: limit: 50 has_more: false next_cursor: null schema: $ref: '#/components/schemas/VaultRequestList' '400': description: >- The request was malformed or failed validation. | Error code | When | | --- | --- | | `validation.failed` | The request failed schema validation. See `error.details` for per-field issues. | x-error-codes: - validation.failed content: application/json: examples: validation.failed: summary: >- The request failed schema validation. See `error.details` for per-field issues. value: error: code: validation.failed message: >- The request failed schema validation. See `error.details` for per-field issues. request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde doc_url: https://docs.endstate.io/errors/validation-failed schema: $ref: '#/components/schemas/ErrorResponse' '401': description: |- Authentication failed. | Error code | When | | --- | --- | | `auth.unauthorized` | Credential is missing or malformed. | x-error-codes: - auth.unauthorized content: application/json: examples: auth.unauthorized: summary: Credential is missing or malformed. value: error: code: auth.unauthorized message: Credential is missing or malformed. request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde doc_url: https://docs.endstate.io/errors/auth-unauthorized schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Authenticated, but not permitted. | Error code | When | | --- | --- | | `auth.forbidden` | Credential is valid but does not have access to the requested resource or action. | x-error-codes: - auth.forbidden content: application/json: examples: auth.forbidden: summary: >- Credential is valid but does not have access to the requested resource or action. value: error: code: auth.forbidden message: >- Credential is valid but does not have access to the requested resource or action. request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde doc_url: https://docs.endstate.io/errors/auth-forbidden schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- The resource does not exist within your organization. | Error code | When | | --- | --- | | `not_found.resource` | The requested resource does not exist within your organization. | | `unit.not_found` | The unit ID does not exist in your organization. | x-error-codes: - not_found.resource - unit.not_found content: application/json: examples: not_found.resource: summary: >- The requested resource does not exist within your organization. value: error: code: not_found.resource message: >- The requested resource does not exist within your organization. request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde doc_url: https://docs.endstate.io/errors/not-found-resource unit.not_found: summary: The unit ID does not exist in your organization. value: error: code: unit.not_found message: The unit ID does not exist in your organization. request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde doc_url: https://docs.endstate.io/errors/unit-not-found schema: $ref: '#/components/schemas/ErrorResponse' '429': description: |- Too many requests. | Error code | When | | --- | --- | | `rate_limit.exceeded` | Per-key rate limit exceeded. | x-error-codes: - rate_limit.exceeded content: application/json: examples: rate_limit.exceeded: summary: Per-key rate limit exceeded. value: error: code: rate_limit.exceeded message: Per-key rate limit exceeded. request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde doc_url: https://docs.endstate.io/errors/rate-limit-exceeded schema: $ref: '#/components/schemas/ErrorResponse' '500': description: >- Something went wrong on our end. | Error code | When | | --- | --- | | `internal.error` | An unexpected server error occurred. Retry with exponential backoff and include `request_id` in any support request. | x-error-codes: - internal.error content: application/json: examples: internal.error: summary: >- An unexpected server error occurred. Retry with exponential backoff and include `request_id` in any support request. value: error: code: internal.error message: >- An unexpected server error occurred. Retry with exponential backoff and include `request_id` in any support request. request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde doc_url: https://docs.endstate.io/errors/internal-error schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyBearer: [] components: schemas: VaultRequestList: type: object properties: vault_requests: type: array items: $ref: '#/components/schemas/VaultRequest' pagination: $ref: '#/components/schemas/CursorPagination' required: - vault_requests - pagination ErrorResponse: type: object properties: error: type: object properties: code: anyOf: - $ref: '#/components/schemas/ErrorCode' - type: string description: >- Stable, namespaced error code. The `ErrorCode` catalogue lists every code defined today; handle an unrecognized value as a generic failure rather than throwing, since codes are added over time. example: chip.not_found message: type: string description: >- Human-readable description, for logs and debugging. Wording may change without notice - never parse or match against it. example: Chip not found request_id: type: string description: >- Identifier for this request, matching the `X-Request-Id` response header. Log it and include it in any support request. example: req_8e1a7f50-90ab-4cde-f012-3456789abcde doc_url: type: string description: Documentation page for this error code. example: https://docs.endstate.io/errors/chip-not-found details: $ref: '#/components/schemas/ValidationErrorDetails' required: - code - message - request_id - doc_url required: - error description: >- Every error response, regardless of endpoint or HTTP status, uses this envelope. VaultRequest: type: object properties: id: type: string format: uuid description: Vault request id. unit_id: type: string format: uuid description: The unit the request is for. vault: type: object properties: id: type: string format: uuid description: Vault id. name: type: string description: The vault's display name. logo_url: type: - string - 'null' description: URL of the vault's logo; null when it has none. key_mode: type: string enum: - managed - external description: >- Who signs the vault's receipts. `managed`: Endstate holds the vault's key and signs each receipt on the vault's behalf when the vault confirms it has an item, so the receipt is not independent of Endstate. `external`: the vault holds its own key and signs its receipts itself. example: managed required: - id - name - logo_url - key_mode description: The vault the request names. status: type: string enum: - pending - submitted - active - unvault_waiting - unvaulting - unvaulted - cancelled - expired - rejected - failed description: >- Where the request is now. `pending`: the owner approved and the vault has not decided. `submitted`: the vault confirmed it has the item and Endstate is recording it. `active`: the item is vaulted. `unvault_waiting`: the owner asked for the item back and the waiting period runs, or the item is ready to ship. `unvaulting`: the vault dispatched the item and Endstate is completing the unvault. `unvaulted`: the unvault is complete. `cancelled`, `expired` and `rejected` end a request that never vaulted the item, and never change again. `failed`: the item was not recorded as vaulted; the request becomes `active` if the item is later recorded as vaulted after all. A status can move back. A cancel of the unvault, once recorded, returns `unvault_waiting` to `active`, and `unvaulting` too in the rare case one is recorded after the dispatch. Rarely, the network revises its latest records, which can return `unvaulted` to `unvaulting` or `active`, `unvault_waiting` or `unvaulting` to `active`, and `active` to `failed`. Read the status as the request's current state, not as a one-way log. notes: type: - string - 'null' description: >- Free text the vault's staff left when they confirmed or rejected the request. Null when they left none. rejection_reason: type: - string - 'null' enum: - wrong_item - chip_unreadable - unacceptable - owner_changed - null description: >- Why the request was rejected: the vault's reason, or `owner_changed` when the unit changed hands after its owner approved. decided_at: type: - string - 'null' format: date-time description: >- When the vault confirmed or rejected the request, or Endstate rejected it; null until then. available_at: type: - string - 'null' format: date-time description: >- When the unvault's waiting period ends. Null until the owner's request to unvault is recorded, and again if the owner cancels it. A hold stops the clock, and lifting it moves this later by the time the hold lasted. hold: type: - object - 'null' properties: by: type: string enum: - vault - brand description: 'Who placed the hold: the vault or the brand.' reason: type: - string - 'null' description: Why, in the words of whoever placed the hold. required: - by - reason description: >- The hold on a waiting unvault, or null. `by` says who placed it, the vault or the brand, and `reason` is their text. While it stands the item is not ready to ship. ready_to_ship: type: boolean description: >- Whether the item is ready to ship: its waiting period has ended and nothing holds it. The vault records dispatch with a tap of the item from then on. dispatched_at: type: - string - 'null' format: date-time description: >- When the vault's tap recorded the item's dispatch. Endstate then completes the unvault; the vault hands the item over once the request reads `unvaulted`. expires_at: type: - string - 'null' format: date-time description: When a pending request expires; null once it has moved on. created_at: type: string format: date-time description: When the owner's approval opened the request. required: - id - unit_id - vault - status - notes - rejection_reason - decided_at - available_at - hold - ready_to_ship - dispatched_at - expires_at - created_at CursorPagination: type: object properties: limit: type: integer exclusiveMinimum: 0 description: Maximum number of records returned. example: 50 has_more: type: boolean description: Whether another page is available. Pass `next_cursor` to fetch it. example: false next_cursor: type: - string - 'null' description: Opaque cursor for the next page. Null when there is no next page. example: >- eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0xNlQxMjowMDowMC4wMDBaIiwiaWQiOiIzMzMzMzMzMy0zMzMzLTMzMzMtMzMzMy0zMzMzMzMzMzMzMzMifQ required: - limit - has_more - next_cursor ErrorCode: type: string enum: - environment.conflict - environment.invalid_configuration - organization.changed - validation.failed - auth.unauthorized - auth.forbidden - session_token.invalid_or_expired - session_token.wrong_chip - wallet_session.invalid_or_expired - not_found.resource - rate_limit.exceeded - chip.not_found - chip.invalid_e_value - chip.already_scanned - quota.exceeded - chip.not_a_test_chip - unit.not_found - unit.already_exists - unit.not_minted - collection.not_found - collection.already_exists - collection.not_active - collection_backfill.blocked - organization.not_found - chip.already_paired - chip.key_unusable - chip.mac_required - chip.bulk_mixed_collections - chip.bulk_pending - unit.issuance_pending - claim.owner_unknown - claim.already_to_recipient - claim.in_progress - claim.locked - claim.unit_vaulted - claim.unit_held - claim.tap_required - claim.not_found - chip_replacement.locked - chip_replacement.in_progress - chip_replacement.not_found - transfer.owner_unknown - transfer.already_to_recipient - transfer.in_progress - transfer.not_found - submission.not_executable - vault.not_found - vault.already_exists - vault.provisioning_failed - vault.not_permitted - vault.unavailable - vault.challenge_invalid - vault.address_in_use - vault.key_conflict - vault.signer_unauthorized - vault_connection.not_found - vault_connection.not_active - vault_connection.already_exists - vault_connection.conflict - vault.in_progress - vault.owner_changed - vault.request_not_found - vault.request_not_pending - vault.consent_invalid - vault.consent_used - vault.consent_outdated - vault.request_rejected - vault.request_expired - vault.reference_taken - tap_intent.not_found - tap_intent.disabled - tap_intent.too_many_open - tap_intent.unit_vaulted - tap_intent.redirect_origin_not_allowed - tap_intent.expired - tap_intent.canceled - tap_intent.already_approved - tap_intent.already_consumed - tap_intent.not_approved - tap_intent.action_mismatch - tap_intent.tap_not_matched - tap_intent.code_required - tap_intent.code_incorrect - tap_intent.code_attempts_exhausted - tap_intent.code_unavailable - tap_intent.busy - unvault.not_found - unvault.in_progress - unvault.waiting - unvault.held - idempotency.key_conflict - idempotency.in_progress - internal.error - webhook_endpoint.not_found - webhook_endpoint.deleted - webhook_endpoint.limit_reached - webhook_endpoint.url_refused - webhook_endpoint.signing_unavailable - webhook_event_type.unknown - webhook_event.not_found - webhook_endpoint.disabled - webhook_delivery.in_progress - webhook_endpoint.not_subscribed description: >- Stable, namespaced error code in `.` form. Branch on this rather than on `message` or the HTTP status. This is the catalogue as of this spec revision, not a closed set - see `ErrorResponse.error.code`. example: chip.not_found ValidationErrorDetails: type: object properties: formErrors: type: array items: type: string description: Issues that apply to the request as a whole rather than one field. example: [] fieldErrors: type: object additionalProperties: type: array items: type: string description: Validation issues keyed by the field that failed. example: name: - 'Invalid input: expected string, received undefined' required: - formErrors - fieldErrors description: Per-field validation detail. Present only on `validation.failed`. securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: end_sk description: >- Use `Authorization: Bearer end_sk_*` for partner API keys (e.g. `end_sk_AbCd_example_api_key`). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.