API Reference
System Endpoints
Reference for all administrative and organizational API endpoints under /api/system/ and /api/auth/.
System Endpoints
System endpoints handle cross-project, organizational, and administrative operations. All system endpoints live under the /api/system/ base path. Authentication endpoints live under /api/auth/.
We recommend not directly manipulating the system schema or structure.
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 <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/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/password-change | Change the authenticated user's password. Requires current and new password. |
POST | /api/auth/password-reset/request | Request a password reset email for a given email address. |
GET | /api/auth/password-reset/verify | Verify a password reset token (via query parameter). |
POST | /api/auth/password-reset/confirm | Confirm a password reset with the token and a new password. |
Projects
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/projects | List all projects. |
POST | /api/system/projects | Create a new project. Requires project:create org entitlement. |
GET | /api/system/projects/{project} | Read a single project by name. |
PATCH | /api/system/projects/{project} | Update a project by name. |
DELETE | /api/system/projects/{project} | Delete a project by name. Requires project:delete:{id} org entitlement. |
Users
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/users | List all users. Requires authentication. |
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 authentication. |
PATCH | /api/system/users/{user_id} | Update a user by ID. Requires user:update:{id} org entitlement when updating another user. |
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 authentication. |
POST | /api/system/invites | Invite one or more users to the organization or a project. |
PATCH | /api/system/invites/{invitation_id} | Renew a pending invitation (extend its TTL). |
DELETE | /api/system/invites/{invitation_id} | Revoke a pending invitation. |
POST | /api/system/invites/accept | Accept an invitation using the invite token (no authentication required). |
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 a new API key. Accepts name, TTL, and optional description. |
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. |
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. |
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. |
For the complete and up-to-date schema, refer to the dynamically generated OpenAPI Specification from your running instance.