> 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.fr/api` |
| On-premise        | `https://<your-domain>/api` |
| Local / dev       | `http://localhost:3000/api` |

> Use `https://app.veilio.fr/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