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

# API overview

> Base URL, conventions, and what the API gives you.

The Vouchmark API is a JSON REST API. Authentication is cookie-based: [`POST /v1/login`](/api-reference/auth/login) sets httpOnly session cookies. For server-to-server calls you can read the access-token cookie and send it as a Bearer credential. See [Authentication](/authentication).

## Base URL

```
https://api.vouchmark.com/v1
```

All paths in this reference are relative to that base. The same host is used for staging and production — sandbox vs live is determined by your API keys and widget environment, not by a different URL. See [SDK environments](/sdks/overview#environments).

## Conventions

* **Content-Type** is `application/json` unless an endpoint takes a file (then it's `multipart/form-data`).
* **Authentication** is cookie-based, or `Authorization: Bearer <token>` using the access-token cookie value. See [Authentication](/authentication).
* **IDs** are opaque strings. Many entities are prefixed by type (`usr_` for users, `cmp_` for companies, `whk_` for webhooks, etc.).
* **Timestamps** are ISO 8601 UTC, e.g. `2026-05-12T09:14:00Z`.
* **Pagination** uses `page` and `limit` query params on list endpoints. Paginated responses return a `pagination` object — `{ page, limit, total, totalPages, hasNext, hasPrev }`. There is no top-level `total` and no `hasMore`.
* **Errors** use HTTP status codes and a consistent body. See [Errors](/errors).

## Successful responses

Most success responses carry `success: true`. The key the payload sits under is **not** uniform — it varies by endpoint. Some endpoints nest data under `data`, others under a resource name such as `wallet`, `rates`, `transactions`, or `chat`. Read each endpoint's reference page for its exact shape; don't assume a single envelope.

```json theme={null}
{
  "success": true,
  "wallet": { ... }
}
```

```json theme={null}
{
  "success": true,
  "data": [ ... ],
  "pagination": { "page": 1, "limit": 20, "total": 134, "totalPages": 7, "hasNext": true, "hasPrev": false }
}
```

## Error responses

Errors use a consistent base shape:

```json theme={null}
{
  "success": false,
  "status": "error",
  "message": "Company not found"
}
```

The `message` is human-readable. See [Errors](/errors) for status codes, validation error details, and the few endpoints that add an `error` code field.

## Rate limits

Limits are applied per IP via `express-rate-limit`, with different windows and ceilings per surface. See [Rate limits](/rate-limits) for the exact numbers and the `RateLimit-*` / `Retry-After` header semantics.

## Webhooks

You can register a webhook endpoint per app, environment, and service type from the developer settings. See [Webhooks](/webhooks) for the registration model and current delivery behaviour.