Skip to content

API

Vesana has a REST API under /api/v1/. All endpoints JWT-protected, tenant scope is implicit from the token.

  • Auth flow — login, JWT, 2FA, refresh, personal access tokens

  • API reference — interactive OpenAPI docs

  • Cookbook — common workflows, code snippets

General properties

Property Value
Base URL https://your-domain.tld/api/v1
Auth Authorization: Bearer <jwt>
Content-Type application/json
Rate limit login/2FA: 10 req/min/IP, others: 600 req/min/user
Pagination ?limit=50&offset=0 or ?cursor=...
Filter ?<field>=<value> and ?q=<fulltext>
Sort ?sort=<field> and ?order=asc|desc

Stability guarantees

/api/v1/ is stable — breaking changes only on major release with migration plan and deprecation phase.

/api/v2/ (future) would run in parallel — v1 stays at least two majors.

What counts as breaking:

  • New required fields in request body
  • Removed endpoints
  • Changed response schemas (renamed fields, type change)

What's not breaking:

  • New optional fields in request/response
  • New endpoints
  • More detail in error messages

Versioning header

Response header X-Vesana-Version: 0.19.0 shows server version. No version info in body — when testing against various server versions, read header.

OpenAPI

API is FastAPI-based, schema at:

GET /openapi.json

Swagger UI:

GET /docs

Redoc:

GET /redoc

In the docs site you see the reference at API reference (embedded).

Next