API¶
Vesana has a REST API under /api/v1/. Almost all endpoints require authentication (bearer token or browser cookie); which tenants a request sees follows from the role and tenant assignment of the signed-in account.
-
Auth flow — login, tokens, 2FA, renewal, step-up, collector/agent keys vs. user auth
-
API reference — OpenAPI schema and endpoint overview
-
Cookbook — common workflows, code snippets
General properties¶
| Property | Value |
|---|---|
| Base URL | https://your-domain.tld/api/v1 |
| Auth | Authorization: Bearer <access_token> |
| Content-Type | application/json |
| Rate limit | Login, 2FA and step-up: 10 requests/minute per client IP. No general limit on the other endpoints. |
| Pagination | List endpoints take limit and offset; the total count is in the X-Total-Count response header. The response stays a JSON array. |
| Filtering / sorting | endpoint-specific (e.g. tenant_id, q, enabled) — see the OpenAPI schema. There are no generic filter or sort parameters. |
Compatibility¶
What counts as a breaking change:
- Required fields in request body
- Removed endpoints
- Changed response schemas (fields renamed, type changed)
What doesn't count as a breaking change:
- New optional fields in request/response
- New endpoints
- More detail in error messages
Clients should ignore unknown fields in responses. API changes are listed in the release notes.
OpenAPI¶
The API generates its own schema (/openapi.json, plus Swagger UI at /docs and Redoc at /redoc). These paths live inside the API container — the nginx in front only forwards /api/…, so https://your-domain.tld/docs opens the web app, not Swagger.
Export the schema on the Vesana server:
cd /opt/vesana
docker compose exec -T api python -c \
"import urllib.request; print(urllib.request.urlopen('http://localhost:8000/openapi.json').read().decode())" \
> openapi.json
Load the file into any OpenAPI viewer or client generator. Endpoints of preview features (see Preview features) are in the schema but answer 404 until the feature is enabled.