> ## Documentation Index > Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # Reveal card details > Required API-key scope: `cards:read_vault`. Returns a short-lived vault handoff. The PAN/CVV never transit this API; resolve them directly against the vault `url`. ## OpenAPI ````yaml /openapi/2026-07-13.json post /2026-07-13/cards/{cardId}/reveal openapi: 3.1.0 info: title: Reap Direct API description: > # Introduction The Reap Direct API gives you programmatic access to Reap Direct: issue and manage cards, control spend and resolve team members from your own systems. ## Quickstart 1. Ask a team administrator to create an API key from the Reap dashboard. 2. Make your first request: ```bash curl https://api.global.direct.reap.global/2026-07-13/cards \ -H "x-api-key: " ``` ## Authentication Every request is authenticated with an API key sent in the `x-api-key` header. Keys are issued per business and carry scopes that limit which endpoints they can call: requests without a valid key receive `401`; requests with a valid key but insufficient scope receive `403`. ## Response schemas A response property marked `required` is always present in that response. This is separate from nullability: a required property may still contain `null` when its schema is nullable. ## Versioning The API is versioned with dates in the URL: `/2026-07-13/cards`. Pin one version in your integration and every endpoint keeps its behavior on that date while it is supported. - New dates are published only when breaking changes ship; additive changes (new optional fields, new endpoints) appear on all supported dates. - Each date remains supported for at least 12 months after its successor is published; deprecation and sunset dates are announced before retirement. - Supported versions: 2026-07-13. Requests to an unknown version return `404` with an error listing the supported versions. ## Errors All errors share a single JSON envelope: ```json { "statusCode": 400, "type": "INVALID_REQUEST_ERROR", "code": "SPEND_CAP_TOO_LOW", "message": "Spend cap cannot be lower than the amount already spent on this card.", "param": "spendCap", "requestId": "01H..." } ``` - `statusCode` — HTTP status, duplicated in the body. - `type` — coarse category, **always present**. Branch on this for retry/re-auth decisions. - `code` — stable, machine-readable identifier. Present only for programmatically-actionable errors. - `message` — human-readable explanation, safe to surface to users. - `param` — offending field for validation errors (optional). - `details` — structured extra context such as validation issues (optional). - `requestId` — correlation id; include it when contacting support (optional). The specific error codes each endpoint can return are documented on that endpoint's responses below. ### Error types | Type | Description | | --- | --- | | `INVALID_REQUEST_ERROR` | The request was rejected due to invalid input, a missing resource, or a business-rule violation (HTTP 400/404/409/422). | | `AUTHENTICATION_ERROR` | Authentication is missing or invalid (HTTP 401). | | `PERMISSION_ERROR` | The caller is authenticated but not permitted to perform the action (HTTP 403). | | `RATE_LIMIT_ERROR` | Too many requests; retry after a delay (HTTP 429). | | `API_ERROR` | An unexpected error occurred on our side (HTTP 5xx). | | `UPSTREAM_ERROR` | An upstream service returned an error (HTTP 502/503). | version: '2026-07-13' contact: {} servers: - url: https://api.global.direct.reap.global security: [] tags: [] paths: /2026-07-13/cards/{cardId}/reveal: post: tags: - Cards summary: Reveal card details description: >- Required API-key scope: `cards:read_vault`. Returns a short-lived vault handoff. The PAN/CVV never transit this API; resolve them directly against the vault `url`. operationId: revealCard parameters: - name: cardId required: true in: path schema: format: uuid type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RevealedCardDetails' examples: vaultHandoff: summary: Vault handoff value: url: >- https://vault.example.com/cards/card_01JZ2Q4T4J7QF2G6Z3X9A1B5CD authorization: encrypted-authorization iv: initialization-vector '400': description: '`BAD_REQUEST`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: BAD_REQUEST: summary: BAD_REQUEST value: statusCode: 400 type: INVALID_REQUEST_ERROR message: Bad request. '401': description: '`UNAUTHORIZED`, `AUTH_CREDENTIAL_MISSING`, `API_KEY_INVALID`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: UNAUTHORIZED: summary: UNAUTHORIZED value: statusCode: 401 type: AUTHENTICATION_ERROR message: Authentication required. AUTH_CREDENTIAL_MISSING: summary: AUTH_CREDENTIAL_MISSING value: statusCode: 401 type: AUTHENTICATION_ERROR code: AUTH_CREDENTIAL_MISSING message: Authentication is required. API_KEY_INVALID: summary: API_KEY_INVALID value: statusCode: 401 type: AUTHENTICATION_ERROR code: API_KEY_INVALID message: API key is invalid. '403': description: >- `FORBIDDEN`, `API_KEY_IP_NOT_ALLOWED`, `AUTH_INSUFFICIENT_PERMISSIONS`, `AUTH_METHOD_NOT_ALLOWED` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: FORBIDDEN: summary: FORBIDDEN value: statusCode: 403 type: PERMISSION_ERROR message: You do not have permission to perform this action. API_KEY_IP_NOT_ALLOWED: summary: API_KEY_IP_NOT_ALLOWED value: statusCode: 403 type: PERMISSION_ERROR code: API_KEY_IP_NOT_ALLOWED message: Request IP is not allowed for this API key. AUTH_INSUFFICIENT_PERMISSIONS: summary: AUTH_INSUFFICIENT_PERMISSIONS value: statusCode: 403 type: PERMISSION_ERROR code: AUTH_INSUFFICIENT_PERMISSIONS message: Insufficient permissions. AUTH_METHOD_NOT_ALLOWED: summary: AUTH_METHOD_NOT_ALLOWED value: statusCode: 403 type: PERMISSION_ERROR code: AUTH_METHOD_NOT_ALLOWED message: >- This endpoint does not accept the credential type provided. '404': description: '`NOT_FOUND`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: NOT_FOUND: summary: NOT_FOUND value: statusCode: 404 type: INVALID_REQUEST_ERROR message: The requested resource was not found. '429': description: '`API_KEY_RATE_LIMITED`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: API_KEY_RATE_LIMITED: summary: API_KEY_RATE_LIMITED value: statusCode: 429 type: RATE_LIMIT_ERROR code: API_KEY_RATE_LIMITED message: API key rate limit exceeded. '500': description: '`INTERNAL_ERROR`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: INTERNAL_ERROR: summary: INTERNAL_ERROR value: statusCode: 500 type: API_ERROR message: An unexpected error occurred. security: - apiKey: [] components: schemas: RevealedCardDetails: type: object properties: url: type: string description: Base URL for retrieving details from the vault. authorization: type: string description: Short-lived encrypted authorization value for vault requests. iv: type: string description: Initialization vector paired with the encrypted vault authorization. required: - url - authorization - iv ErrorResponse: type: object properties: statusCode: type: integer minimum: 100 maximum: 599 description: HTTP status code. type: type: string enum: - INVALID_REQUEST_ERROR - AUTHENTICATION_ERROR - PERMISSION_ERROR - RATE_LIMIT_ERROR - API_ERROR - UPSTREAM_ERROR description: Coarse error category; always present. code: description: Stable machine code; present for actionable errors. type: string message: type: string description: Human-readable explanation. param: description: Offending field for validation errors. type: string details: description: Structured extra context (e.g. validation issues). requestId: description: Correlation id for support. type: string required: - statusCode - type - message securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Enter your API key ````