REST API reference

Sulu's REST API is documented via OpenAPI. The full reference lives at:

https://your-sulu-instance/swagger-ui.html

Conventions

• Request bodies and responses are JSON.
• Numeric IDs are Longs. UUIDs (V2 ingest) are RFC-4122.
• Timestamps are ISO-8601.
• Pagination on list endpoints uses Spring's Pageable shape: ?page=0&size=20&sort=createdAt,desc.
• Errors return { "status": 4xx, "error": "...", "message": "..." }.

Versioning

Two API surfaces:

• V1 at /api/... — synchronous, returns IDs.
• V2 at /api/v2/... — async ingest used by the legacy reporter adapters (wire contract: ADAPTER_CONTRACT.md).
• Import at /api/import/... — server-side report parsing (see Import test reports).

Both are stable. There's no plan to deprecate V1.

Authentication

Two methods:

• Bearer JWT (web UI) — POST /api/auth/login returns a short-lived in-memory access token and sets a rotating, HttpOnly sulu_refresh cookie (SameSite=Strict, Path=/api/auth). The app sends Authorization: Bearer <token> on every request and calls POST /api/auth/refresh when the token expires. There is no server-side session and no JSESSIONID.
• Bearer token (SDKs / CI) — a user-scoped token sent in the Authorization: Bearer <token> header. One token works across every project the user can access. Generated in Profile → API keys.

See Authentication for full details.