> ## Documentation Index
> Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Understand the base URL, authentication, response codes, and headers you'll use everywhere.

The VEXiON cards API is built on **REST** principles. Always call it over **HTTPS**.

## How a request flows

Every call passes a few gates before your endpoint runs. The first gate that fails decides the response, so knowing the order makes every response code on this page predictable.

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E5F6FF','primaryBorderColor':'#36C6FA','primaryTextColor':'#0B3A4A','lineColor':'#2BA8D9','secondaryColor':'#F4FCFF','tertiaryColor':'#FFFFFF','fontFamily':'Manrope, ui-sans-serif, system-ui, sans-serif'}}}%%
flowchart LR
    A[Your app] -->|HTTPS + Bearer key| IP{Too many requests<br/>from your IP?}
    IP -->|yes| X["429<br/>rate limited"]
    IP -->|no| B{Valid key?}
    B -->|no| E["401<br/>unauthorized"]
    B -->|yes| P{Plan and account<br/>allow the API?}
    P -->|no| F1["403<br/>forbidden"]
    P -->|yes| C{Key has scope?}
    C -->|no| F["403<br/>forbidden"]
    C -->|yes| D{Within rate limit?}
    D -->|no| G["429<br/>rate limited"]
    D -->|yes| H[Endpoint runs]
    H --> I["Success<br/>+ Vexion-Request-Id<br/>+ RateLimit headers"]

    classDef accent fill:#36C6FA,stroke:#2BA8D9,color:#ffffff,font-weight:600;
    classDef muted fill:#F1F5F9,stroke:#94A3B8,color:#475569;
    class I accent
    class X,E,F1,F,G muted
```

* **IP throttle.** Floods and repeated failed sign-ins from one IP address get `429` before your key is read. See [Rate Limits](https://vexioncards.mintlify.site/api-reference/rate-limits.md#pre-authentication-ip-throttle).
* **Plan and account state.** API access is included in every plan except VEXiON ONE. An organization that is paused (hibernating), locked, cancelled or not yet active gets `403` on every call. `GET /v1/organization` is the exception: it always answers, so a blocked integration can read `account_state` and find out why.
* **Scope.** Each endpoint needs a scope on the key. A missing scope is a `403`.
* **Rate limit.** Each key has its own budget per endpoint. See [Rate Limits](https://vexioncards.mintlify.site/api-reference/rate-limits.md).

The [Errors](https://vexioncards.mintlify.site/api-reference/errors.md#decision-flow-which-status-code-will-i-get) page lists the full order, including request validation.

Every response carries a `Vexion-Request-Id`. Every error response uses the standard error envelope, so failures are always traceable and machine-readable.

## Base URL

All requests use this base URL:

```
https://api.vexioncards.one
```

## Authentication

Every request requires an `Authorization` header with a Bearer API key:

```http theme={null}
Authorization: Bearer vxn_sk_...
```

Get your API key from [Dashboard → Settings → Developer](https://app.vexioncards.one/settings/developers). Keys are created by organization admins, on every plan except VEXiON ONE, after accepting the API terms. A key that is not used for 90 days is revoked automatically, unless that option is switched off for the key.

**Key format:** a production key looks like `vxn_sk_<suffix>` and a sandbox key looks like `vxn_test_sk_<suffix>`, so you can always tell which environment a key belongs to. Build against the sandbox first; see [Testing and environments](https://vexioncards.mintlify.site/api-reference/test-mode.md).

> [!WARNING]
>
> API keys are secret. Never commit them, log them, or put them in client-side
> code.

## User-Agent

Every request should include a `User-Agent` header identifying your integration:

```http theme={null}
User-Agent: MyCafeApp/1.4.2
```

Requests without a `User-Agent` are still accepted.

## Response codes

The API uses standard HTTP status codes:

| Code | Meaning |
| - | - |
| `200` | Success - every response carries JSON; deletes return `200` with either a `{ id, object, deleted: true }` confirmation or the updated resource |
| `201` | Created - new resource created |
| `400` | Bad Request - malformed or missing required field |
| `401` | Unauthorized - missing or invalid API key |
| `403` | Forbidden - the key lacks a scope, or the organization's plan or account state does not allow the call (see [Errors](https://vexioncards.mintlify.site/api-reference/errors.md)) |
| `404` | Not Found - the resource does not exist in your organization |
| `409` | Conflict - idempotency key reuse or state conflict |
| `422` | Unprocessable - semantically invalid request |
| `429` | Too Many Requests - rate limited |
| `500` | Server Error - retry-safe if request was idempotent |

See the [Errors](https://vexioncards.mintlify.site/api-reference/errors.md) page for the error envelope.

## Response headers

`Vexion-Request-Id` is on every response. The `X-RateLimit-*` headers are on responses to authenticated requests that reach a rate-limited endpoint. They are not on `401`, on `403`, or on a pre-authentication `429`. `Idempotent-Replayed` appears only on a replayed response.

| Header | Purpose |
| - | - |
| `Vexion-Request-Id` | Unique ID for this request - include in support requests |
| `X-RateLimit-Limit` | Your rate limit for this endpoint |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |
| `Idempotent-Replayed` | `true` if the response was replayed from a cached idempotency key |

## Request IDs

If something goes wrong, grab the `Vexion-Request-Id` header from your failed request and include it when contacting [support@vexioncards.one](mailto:support@vexioncards.one). We can trace the exact request across our systems from that ID. The same value is also sent as `x-request-id`, for HTTP clients that read that header by default, but `Vexion-Request-Id` remains the documented, canonical header to use.

## For AI agents and assistants

* **MCP server.** AI assistants such as Claude and ChatGPT can work with your account through the VEXiON MCP server. See [MCP server](https://vexioncards.mintlify.site/ai/mcp-server.md).
* **Machine-readable docs.** These docs serve `/llms.txt` and `/openapi.json` for AI tools and code generators. The API host (`api.vexioncards.one`) does not serve `/openapi.json`.

## Next steps

> [card] [Quickstart](https://vexioncards.mintlify.site/api-reference/quickstart.md)
>
> Make your first authenticated call in a few minutes.

> [card] [Testing and environments](https://vexioncards.mintlify.site/api-reference/test-mode.md)
>
> Build against the sandbox before you touch production data.

> [card] [Errors](https://vexioncards.mintlify.site/api-reference/errors.md)
>
> The error envelope and every code the API can return.

> [card] [Rate limits](https://vexioncards.mintlify.site/api-reference/rate-limits.md)
>
> Limits, headers, and how to back off cleanly.

> [card] [Idempotency](https://vexioncards.mintlify.site/api-reference/idempotency.md)
>
> Retry writes without creating duplicates.

> [card] [Webhooks](https://vexioncards.mintlify.site/api-reference/webhooks.md)
>
> Receive events instead of polling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.