> For the complete documentation index, see [llms.txt](https://docs.veilio.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veilio.xyz/api-mcp/readme.md).

# Developer Platform API

***

#### Quick reference

**Base URL**

| Environment       | URL                          |
| ----------------- | ---------------------------- |
| Production (SaaS) | `https://app.veilio.xyz/api` |
| On-premise        | `https://<your-domain>/api`  |
| Local / dev       | `http://localhost:3000/api`  |

> Use `https://app.veilio.xyz/api`, not `api.veilio.com`.

**Authentication**

| Method                | Header                                                      |
| --------------------- | ----------------------------------------------------------- |
| API key (recommended) | `Authorization: Bearer <API_KEY>` or `X-API-Key: <API_KEY>` |
| Dashboard session     | Cookie `veilio_session`                                     |
| Dataset download      | `x-veilio-dataset-access-token: dsat_...`                   |
| Public dataset link   | Query `?public_token=...` (one-time)                        |

**API key purposes**

| Purpose     | Use                                                          |
| ----------- | ------------------------------------------------------------ |
| `STANDARD`  | Production tokenize / detokenize (monthly quota)             |
| `MIGRATION` | Historical import only (migration budget, not monthly quota) |

***

#### Plan quotas (SaaS)

| Plan       | Tokens / month | Requests / month | API keys | Datasets  | Members   | Bulk | Multi-format |
| ---------- | -------------- | ---------------- | -------- | --------- | --------- | ---- | ------------ |
| Freemium   | 500            | 1 000            | 1        | 1         | 1         | No   | No           |
| Starter    | 2 000          | 10 000           | 2        | 4         | 1         | Yes  | Yes          |
| Pro        | 10 000         | 100 000          | 5        | 10        | 2         | Yes  | Yes          |
| Enterprise | Custom         | Custom           | Custom   | Unlimited | Unlimited | Yes  | Yes          |

A **request** counts successful `TOKENIZE`, `DETOKENIZE`, `SHRED`, and `DATASET_UPLOAD` operations. **Tokens** count new tokens created in the clients database.

On-premise limits are defined in your signed `license.jwt`.

***

#### Core endpoints (API key)

| Method | Path                 | Description                |
| ------ | -------------------- | -------------------------- |
| POST   | `/tokenize`          | Single field               |
| POST   | `/tokenize/bulk`     | Batch fields               |
| POST   | `/tokenize/format`   | JSON / CSV / SQL in-place  |
| POST   | `/detokenize`        | Reveal one token           |
| POST   | `/detokenize/bulk`   | Reveal many                |
| POST   | `/detokenize/format` | Multi-format reveal        |
| POST   | `/tokens/shred`      | Crypto-shred one token     |
| POST   | `/flows/ingest`      | Form / lead JSON ingestion |

Detailed curl examples: HTTP Integration.

**POST `/tokenize`**

```json
// Request
{
  "data": "john@example.com",
  "type": "email",
  "metadata": { "entityId": "customer_42" },
  "retention": { "ttlDays": 365 }
}

// Response 200
{
  "token": "tok_...",
  "createdAt": "2026-03-26T10:00:00.000Z",
  "retentionUntil": "2027-03-26T10:00:00.000Z"
}
```

**POST `/tokenize/bulk`**

```json
// Request
{
  "fields": [
    { "data": "a@example.com", "type": "email" },
    { "data": "+336...", "type": "phone", "retention": { "ttlDays": 30 } }
  ]
}

// Response 200
{
  "tokens": [{ "token": "tok_...", "type": "email", "createdAt": "...", "retentionUntil": null }],
  "summary": { "total": 2, "success": 2, "failed": 0 },
  "errors": [{ "field": 1, "error": "..." }],
  "createdAt": "..."
}
```

**POST `/flows/ingest`**

```json
// Request
{
  "flowId": "signup-v1",
  "source": "website",
  "entityId": "lead_42",
  "data": { "email": "john@example.com", "phone": "+336..." },
  "metadata": {}
}

// Response 201
{
  "flowId": "signup-v1",
  "protectedData": { "email": "tok_...", "phone": "tok_...", "company": "Acme" },
  "tokens": [{ "path": "email", "token": "tok_...", "type": "email" }],
  "lookup": { "email_hash": "...", "phone_hash": "..." },
  "policyApplied": "api_key_schema",
  "metadata": {}
}
```

***

#### Dashboard / session endpoints

Require an authenticated dashboard session (not an API key unless noted).

| Method | Path                              | Description                                                |
| ------ | --------------------------------- | ---------------------------------------------------------- |
| GET    | `/tokens`                         | Paginated token list (RBAC)                                |
| POST   | `/tokens/lookup`                  | Search by plaintext value or `entityId` (**session only**) |
| POST   | `/tokens/reveal-bulk`             | Reveal up to 100 tokens                                    |
| POST   | `/tokens/shred-bulk`              | Shred by `ids[]` or `entityId`                             |
| POST   | `/compliance/export`              | Start GDPR export (2FA)                                    |
| GET    | `/compliance/logs-export`         | Download audit logs                                        |
| GET    | `/compliance/offboarding/summary` | Offboarding inventory                                      |
| DELETE | `/compliance/delete-account`      | Delete account                                             |
| POST   | `/onboarding/migration`           | Activate migration mode                                    |
| GET    | `/onboarding/migration`           | Migration budget status                                    |

> **Note:** `POST /tokens/lookup` is not available with an API key. For backend integrations, store `entityId` in token `metadata` at tokenization time and query your own database by token ID.

***

#### Datasets (hybrid auth)

| Method | Path                          | Auth                           | Description                     |
| ------ | ----------------------------- | ------------------------------ | ------------------------------- |
| GET    | `/datasets`                   | API key or session             | List datasets                   |
| POST   | `/datasets`                   | API key or session (Owner/DPO) | Upload CSV or JSON              |
| GET    | `/datasets/[id]`              | API key or session             | Dataset metadata                |
| GET    | `/datasets/[id]/download`     | API key + dataset access token | Filtered detokenized export     |
| POST   | `/datasets/[id]/access-token` | Session                        | Issue short-lived `dsat_` token |
| POST   | `/datasets/[id]/public-share` | Session                        | One-time public link            |

Upload details: Datasets Upload.

**Default limits**

| Variable                   | Default                    |
| -------------------------- | -------------------------- |
| `VEILIO_DATASET_MAX_BYTES` | 320 MB (335 544 320 bytes) |
| `VEILIO_DATASET_MAX_CELLS` | 200 000 cells              |

***

#### Common errors

| HTTP | Code                | Meaning                           |
| ---- | ------------------- | --------------------------------- |
| 401  | `AUTH_ERROR`        | Missing / invalid key or session  |
| 400  | `VALIDATION_ERROR`  | Bad payload                       |
| 403  | `PLAN_LIMIT`        | Quota exceeded                    |
| 403  | `FORBIDDEN`         | RBAC (e.g. VIEWER write)          |
| 408  | `TIMEOUT_ERROR`     | Request timeout                   |
| 410  | `TOKEN_SHREDDED`    | Token cryptographically destroyed |
| 413  | `PAYLOAD_TOO_LARGE` | Dataset file too large            |
| 429  | `RATE_LIMIT_ERROR`  | Rate limit exceeded               |
| 500  | `INTERNAL_ERROR`    | Server error                      |

Full troubleshooting: Troubleshooting.

***

#### OpenAPI specification

A machine-readable OpenAPI 3.0 file is available in the Veilio documentation repository:

`docs/gitbook/openapi.yaml`

Import it into Postman, Insomnia, or your API gateway for interactive testing.

***

#### SDKs

| Language                | Package                                                           |
| ----------------------- | ----------------------------------------------------------------- |
| JavaScript / TypeScript | `@veilio/sdk` on [npm](https://www.npmjs.com/package/@veilio/sdk) |
| Python                  | `veilio-sdk` on [PyPI](https://pypi.org/project/veilio-sdk/)      |

Docs: SDK JS · SDK Python


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.veilio.xyz/api-mcp/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.