API Reference
System Endpoints
Reference for all administrative and organizational API endpoints under /api/system/ and /api/auth/.
System Endpoints
System endpoints handle cross-workspace, organizational, and administrative operations. All system endpoints live under the /api/system/ base path. Authentication endpoints live under /api/auth/.
Warning
We recommend not directly manipulating the system schema or structure.
Check Process Health
The health endpoints do not require authentication and work with or without clustered mode. See Horizontal Scaling for deployment guidance.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/live | Returns 200 while the process is running. |
GET | /api/system/ready | Returns 200 while the instance accepts traffic, including when it is degraded, or 503 otherwise. |
The readiness response always includes ready, degraded, replica, and checks.
| Check outcomes | HTTP status | ready | degraded |
|---|---|---|---|
| All checks pass | 200 | true | false |
| One or more checks warn, with no failures | 200 | true | true |
| One or more checks fail | 503 | false | true |
Each check contains a name and a status of pass, warn, or fail. A warning means service is degraded. Check names may change in minor versions.
This response shows an instance accepting traffic while its configured Redis-compatible storage is unavailable:
response.json
{
"ready": true,
"degraded": true,
"replica": {
"startup_id": "019c12f1-3e48-7c61-bb15-14d810adc399"
},
"checks": [
{ "name": "accepting_traffic", "status": "pass" },
{ "name": "startup", "status": "pass" },
{ "name": "system_db", "status": "pass" },
{ "name": "redis", "status": "warn" }
]
}
Note
New replicas fail to start altogether if configured Redis-compatible storage is unavailable during startup.
Instance Info
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/info | Returns first-run setup requirements while setup is incomplete. For authenticated callers, adds the engine version and build revision, the maximum file upload size, the current server time, and the license status. See Licensing. |
Authentication
Authentication endpoints are served at /api/auth/. Monospace uses JSON Web Tokens (JWT) and secure cookies for session management. Access tokens are short-lived JWTs passed via the Authorization: Bearer YOUR_ACCESS_TOKEN header (with a cookie fallback). Refresh tokens are long-lived JWTs handled via HttpOnly cookies in session mode, or returned in the JSON response body in JSON mode. See the Authentication guide for usage details.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/auth/providers/local/password/login | Authenticate with email and password. Supports session (cookie) and json (token in body) modes. |
POST | /api/auth/refresh | Obtain a new access token using a refresh token (from cookie or request body). |
POST | /api/auth/logout | Invalidate the refresh token and clear session cookies. |
POST | /api/auth/providers/local/password/signup | Accept an invitation by creating an account with the invite token, full name, and password (no authentication required). |
POST | /api/auth/providers/local/password/change | Change the authenticated user's password. Requires current and new password. |
POST | /api/auth/providers/local/password/reset/request | Request a password reset email for a given email address. |
GET | /api/auth/providers/local/password/reset/verify | Verify a password reset token (via query parameter). |
POST | /api/auth/providers/local/password/reset/confirm | Confirm a password reset with the token and a new password. |
Workspaces
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/workspaces | List all workspaces. |
POST | /api/system/workspaces | Create a new workspace. Requires workspace:create org entitlement. |
GET | /api/system/workspaces/{workspace} | Read a single workspace by name. |
PATCH | /api/system/workspaces/{workspace} | Update a workspace by name. |
DELETE | /api/system/workspaces/{workspace} | Delete a workspace by name. Requires workspace:delete:{id} org entitlement. |
Users
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/users | List all users. Requires orgMembers:read org entitlement. |
GET | /api/system/users/me | Read the currently authenticated user. |
PATCH | /api/system/users/me | Update the currently authenticated user's profile. |
GET | /api/system/users/{user_id} | Read a single user by ID. Requires orgMembers:read org entitlement. |
PATCH | /api/system/users/{user_id} | Update a user by ID. Requires user:update:{id} org entitlement when updating another user. |
PATCH | /api/system/users/{user_id}/status | Suspend or reactivate a user. Requires user:update:{id} org entitlement. |
Org Roles
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/roles | List all organization-level roles. |
POST | /api/system/users/{user_id}/role | Attach an org role to a user. Requires orgRole:assign:{id} org entitlement. |
Invites
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/invites | List all pending invitations. Requires orgMembers:readInvites org entitlement. |
POST | /api/system/invites | Invite one or more users to the organization or a workspace. |
PATCH | /api/system/invites/{invitation_id} | Renew a pending invitation (extend its TTL). |
DELETE | /api/system/invites/{invitation_id} | Revoke a pending invitation. |
API Keys
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/api-keys | List all API keys. Requires apiKey:read org entitlement. |
POST | /api/system/api-keys | Create an API key with a name, required ttl, and optional description. Pass ttl: null for a key that never expires. |
PATCH | /api/system/api-keys/{key_id} | Update an API key by ID. |
DELETE | /api/system/api-keys/{key_id} | Delete an API key by ID. |
Service Accounts
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/service-accounts | List all service accounts. Requires serviceAccount:read org entitlement. |
POST | /api/system/service-accounts | Create a new service account. |
GET | /api/system/service-accounts/{id} | Read a single service account by ID. |
PATCH | /api/system/service-accounts/{id} | Update a service account by ID. |
DELETE | /api/system/service-accounts/{id} | Delete a service account by ID. |
Sign-in Providers
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/auth-providers | List all sign-in providers. Requires authProvider:read org entitlement. |
POST | /api/system/auth-providers | Create a sign-in provider. Requires authProvider:create org entitlement. |
GET | /api/system/auth-providers/{id} | Read a single sign-in provider by ID. Requires authProvider:read org entitlement. |
PATCH | /api/system/auth-providers/{id} | Update a sign-in provider by ID. Requires authProvider:update org entitlement. |
DELETE | /api/system/auth-providers/{id} | Delete a sign-in provider by ID. Requires authProvider:delete org entitlement. |
The client secret is write-only — supply it on create or update, but it is never returned by GET. See Configure SSO for the full setup.
Assets & Files
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/files | List all system-level file metadata records. Requires authentication. |
GET | /api/system/files/{file_id} | Read a single file metadata record by ID. Requires authentication. |
POST | /api/system/assets | Upload a new system-level asset via multipart form. |
GET | /api/system/assets/{file_id} | Download a system-level asset by file ID. |
DELETE | /api/system/assets/{file_id} | Delete a system-level asset by file ID. |
Settings
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/settings | Read the organization settings. Requires authentication. |
PATCH | /api/system/settings | Update organization settings. Requires orgSettings:edit org entitlement. |
Audit Logs
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/audit-logs | List audit log entries. Supports fields, filter, sort, limit, and offset. Requires the auditLog:read org entitlement. See Audit Logs. |
License
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/license | Read license usage and entitlements. Requires authentication. Organization administrators also receive license management details. |
POST | /api/system/license/refresh | Revalidate the license with the licensing service and apply the result. Requires the orgLicense:manage org entitlement. Fails on the Starter license. |
Workspace usage is available at GET /api/{workspace}/license to any member of the workspace. See Licensing for the response shapes.
Entitlements & OpenAPI
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/entitlements | List all available org-level entitlement descriptors. |
GET | /api/system/openapi | Serve the system-level OpenAPI specification. Requires systemOpenApiSchema:read org entitlement. |
Note
For the complete and up-to-date schema, refer to the dynamically generated OpenAPI Specification from your running instance.