-
Notifications
You must be signed in to change notification settings - Fork 3
API Reference
The State API ships with an interactive Swagger UI for exploring and testing endpoints:
https://state.sdkman.io/swagger
From Swagger UI you can:
- Browse all available endpoints and their request/response schemas
- Try out API calls directly from the browser (you'll need a valid JWT token for authenticated endpoints)
- View example request and response bodies
The raw OpenAPI 3.1 spec is available at:
https://state.sdkman.io/openapi/documentation.yaml
You can use this with any OpenAPI-compatible tooling (Postman, Insomnia, code generators, etc.).
The spec is also available in the repository at src/main/resources/openapi/documentation.yaml.
| Method | Path | Description |
|---|---|---|
POST |
/login |
Authenticate and obtain a JWT token |
GET |
/versions/{candidate} |
List versions for a candidate |
GET |
/versions/{candidate}/{version} |
Get a specific version |
GET |
/meta/health |
Health check |
| Method | Path | Description |
|---|---|---|
POST |
/versions |
Publish a new version |
DELETE |
/versions |
Delete a version |
DELETE |
/versions/tags |
Delete a tag |
| Method | Path | Description |
|---|---|---|
GET |
/admin/vendors |
List all vendors |
POST |
/admin/vendors |
Create or update a vendor |
DELETE |
/admin/vendors/{id} |
Soft-delete a vendor |
All authenticated endpoints require a Bearer token in the Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Tokens are obtained via POST /login and are valid for 10 minutes. See the Vendor API Integration Guide for full details.
Vendor tokens include a candidates claim listing which candidates the vendor is authorised to manage. Attempting to operate on an unauthorised candidate returns 403 Forbidden.
Admin tokens bypass candidate restrictions and can operate on any candidate.