> ## 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. # List cards > Required API-key scope: `cards:read`. ## OpenAPI ````yaml /openapi/2026-07-13.json get /2026-07-13/cards 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: get: tags: - Cards summary: List cards description: 'Required API-key scope: `cards:read`.' operationId: listCards parameters: - name: page required: false in: query schema: minimum: 1 maximum: 9007199254740991 type: integer - name: limit required: false in: query schema: minimum: 1 maximum: 100 type: integer - name: type required: false in: query schema: type: string enum: - virtual - physical - name: name required: false in: query description: Case-insensitive cardholder name fragment. schema: minLength: 1 maxLength: 255 type: string - name: email required: false in: query description: Case-insensitive cardholder email address fragment. schema: minLength: 1 maxLength: 255 type: string - name: title required: false in: query description: Case-insensitive card nickname fragment. schema: minLength: 1 maxLength: 255 type: string - name: last4 required: false in: query schema: minLength: 4 maxLength: 4 type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CardList' examples: cards: summary: Cards value: items: - id: card_01JZ2Q4T4J7QF2G6Z3X9A1B5CD type: virtual status: active title: Travel card last4: '4242' expiresAt: '2028-08-31' isRevolving: false planType: topUp category: travel cardholder: userId: user_01JZ2Q1J4Y8P7M6N5K3H2G1F0E name: Ada Lovelace email: ada@example.com spendCap: amount: '5000.00' currency: USD spentAmount: amount: '0.00' currency: USD spendControl: limits: transaction: amount: '1000.00' currency: USD monthly: amount: '5000.00' currency: USD spent: monthly: amount: '0.00' currency: USD atm: dailyWithdrawal: amount: '500.00' currency: USD dailyFrequency: 3 restriction: time: start: '09:00' end: '18:00' category: allow: true ids: - travel createdAt: '2026-07-13T08:00:00.000Z' updatedAt: '2026-07-13T08:00:00.000Z' meta: totalItems: 1 itemCount: 1 itemsPerPage: 20 totalPages: 1 currentPage: 1 '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. '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: CardList: type: object properties: items: type: array items: type: object properties: id: type: string description: Unique card ID. type: type: string enum: - virtual - physical description: Card form factor. status: type: string enum: - pending - active - frozen - inactive - expiring - expired - terminated description: >- Derived card lifecycle status. Pending physical cards await activation; expiring physical cards are within 90 days of expiry. title: anyOf: - type: string - type: 'null' description: Card nickname. last4: anyOf: - type: string - type: 'null' description: Last four digits of the card number. expiresAt: anyOf: - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ - type: 'null' description: >- Card expiration date in YYYY-MM-DD format. Time is unsupported. isRevolving: type: boolean description: Whether the card draws funds from the revolving budget. planType: anyOf: - type: string enum: - physical - subscription - topUp - type: 'null' description: >- Funding plan: physical identifies physical-card plans, subscription cards can share the revolving budget, and top-up cards use fixed reserved credit. category: anyOf: - type: string - type: 'null' description: ID of the card category assigned to the card. cardholder: type: object properties: userId: anyOf: - type: string - type: 'null' description: User ID of the team member assigned to the card. name: anyOf: - type: string - type: 'null' description: Full name of the team member assigned to the card. email: anyOf: - type: string - type: 'null' description: Email address of the team member assigned to the card. required: - userId - name - email description: Team member assigned to the card. spendCap: anyOf: - type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency - type: 'null' description: >- Fixed credit reserved for the card; used as the funding amount for top-up cards. spentAmount: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Total amount spent on the card. spendControl: type: object properties: limits: type: object properties: transaction: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount allowed for a single transaction. daily: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend per day. weekly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend per week. monthly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend per month. yearly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend per year. allTime: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend over its lifetime. description: Configured card-spending limits. spent: type: object properties: daily: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent during the current day. weekly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent during the current week. monthly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent during the current month. yearly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent during the current year. allTime: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent over the lifetime of the card. description: Spend accumulated against each configured period. atm: type: object properties: dailyWithdrawal: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum ATM withdrawal amount allowed per day. monthlyWithdrawal: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum ATM withdrawal amount allowed per month. yearlyWithdrawal: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum ATM withdrawal amount allowed per year. dailyFrequency: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Maximum number of ATM withdrawals allowed per day. monthlyFrequency: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Maximum number of ATM withdrawals allowed per month. yearlyFrequency: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Maximum number of ATM withdrawals allowed per year. description: ATM withdrawal amount and frequency limits. description: Card-spending and ATM controls with current period usage. restriction: type: object properties: time: anyOf: - type: object properties: start: anyOf: - type: string - type: 'null' description: >- Start of the allowed daily card-usage window in UTC, in HH:mm format. end: anyOf: - type: string - type: 'null' description: >- End of the allowed daily card-usage window in UTC, in HH:mm format. required: - start - end - type: 'null' description: Daily UTC window during which the card can be used. category: anyOf: - type: object properties: allow: type: boolean description: >- When true, only the listed categories are allowed; when false, the listed categories are blocked. ids: type: array items: type: string description: Card category IDs to allow or block. required: - allow - ids - type: 'null' description: Rules that allow or block transaction categories. description: >- Time and transaction-category restrictions applied to the card. createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Date and time the card was created, in ISO 8601 format. updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Date and time the card was last updated, in ISO 8601 format. required: - id - type - status - title - last4 - expiresAt - isRevolving - planType - category - cardholder - spendCap - spentAmount - spendControl - restriction - createdAt - updatedAt description: Cards returned on this page. meta: type: object properties: totalItems: type: number description: Total number of items matching the request. itemCount: type: number description: Number of items returned on this page. itemsPerPage: type: number description: Maximum number of items requested per page. totalPages: type: number description: Total number of available pages. currentPage: type: number description: One-based index of the returned page. required: - totalItems - itemCount - itemsPerPage - totalPages - currentPage description: Pagination details for the result. required: - items - meta 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 ````