API Overview

Everything in Versus is driven by a REST API — the same API the web UI uses. It's a standard JSON API: predictable resource URLs, JSON request/response bodies, JWT bearer auth, and consistent pagination, filtering, and error shapes across every feature.

The API is large (1,400+ endpoints), so the reference is split one page per feature — see the list at the bottom. This page documents the contract those pages share, so each feature page only has to cover its own resources.

Interactive docs. A live Swagger UI and Redoc are served at /api/schema/swagger/ and /api/schema/redoc/ on your Versus host (admin sign-in required), backed by the OpenAPI 3 schema at /api/schema/. Every feature page also links a downloadable OpenAPI spec you can import into Postman, Insomnia, or your own codegen.

---

Base URL

All endpoints live under /api on your Versus host:

https://<your-versus-host>/api

Paths in the reference are written from that root — e.g. GET /api/workflows/.

Authentication

Versus uses JWT bearer tokens. Exchange credentials for a token, then send it on every request.

# 1) Obtain a token
curl -X POST https://<host>/api/auth/token/ \
  -H 'Content-Type: application/json' \
  -d '{"username": "[email protected]", "password": "••••••"}'
# → { "access": "<jwt>", "refresh": "<jwt>" }

# 2) Call the API with it
curl https://<host>/api/workflows/ \
  -H 'Authorization: Bearer <access-jwt>'

• Refresh — POST /api/auth/token/refresh/ with {"refresh": "<jwt>"} returns a new access token. Access tokens last 8 hours; refresh tokens 7 days (rotated on use).
• MFA — when TOTP is enforced, POST /api/auth/token/ returns a challenge; complete it via POST /api/auth/totp/verify/. See the auth endpoints for enrollment/confirmation.
• SSO — OIDC and SAML sign-in are available (/api/auth/oidc/*, /api/auth/saml/*) where configured.

Unauthenticated requests return 401. A valid token without sufficient role/permission returns 403.

Pagination

List endpoints are page-numbered and return an envelope:

{ "count": 137, "next": "https://…/api/workflows/?page=2", "previous": null, "results": [ … ] }

• ?page=<n> — page number (default 1)
• ?page_size=<n> — items per page (default 50, max 500)

Filtering, search & ordering

Most list endpoints accept:

• Field filters — exact-match query params for a resource's fields (e.g. ?status=online). The available filters are listed per endpoint on each feature page.
• ?search=<text> — full-text search across a resource's searchable fields.
• ?ordering=<field> — sort ascending, or -<field> for descending (e.g. ?ordering=-created_at).

Errors

Errors use standard HTTP status codes with a JSON body describing the problem:

// 400 example
{ "name": ["This field is required."] }

Rate limits

Sensitive endpoints are throttled (for example, machine secret-fetch and the public tenant-intake). When throttled you'll get 429 Too Many Requests with a Retry-After header — back off and retry.

---

Feature references

One page per feature, each auto-generated from the live OpenAPI schema so it always matches the running API: