REST API

Open API documentation for SwanLab, covering OAuth2 authorization and self-hosted administration. If you plan to integrate SwanLab into a third-party application, this section will help.

Basics

API category	Base URL	Availability
OAuth2 authorization	https://api.swanlab.cn/api	Public Cloud only
Self-hosted administration	https://your-swanlab-domain.com/api	Self-Hosted Commercial Edition only (not supported in Personal Edition, App ≥ 3.6.0)

• Content type: application/json for requests and responses
• Domain substitution: for self-hosted administration, replace your-swanlab-domain.com with your self-hosted SwanLab instance host domain

Authentication

Endpoint	Authentication
POST /auth/oauth2/token	Authorization: Basic base64(app_id:app_secret)
GET /auth/oauth2/user/*	Authorization: Bearer <access_token>
POST /self_hosted/root	No authentication
Other /self_hosted/* endpoints	Authorization: ApiKey <root user's API Key>

⚠️ Warning

/self_hosted/* requests must include the ApiKey prefix (case-sensitive, followed by a single space and the key). A bare key is treated as no credentials and returns 401; a non-root user's key returns 403.

OAuth2 Authorization

For third-party applications integrated with SwanLab, using the public cloud at https://api.swanlab.cn/api:

Integration inquiry

OAuth2 authorization is available on Public Cloud only. To integrate, contact us at contact@swanlab.cn.

• exchange app_id & app_secret for an Access Token;
• while the token is valid, fetch the current user's profile or that user's API Key, which authorizes further calls to the open API.

Endpoint	What it does	Docs
POST /auth/oauth2/token	Exchange a code or refresh token for an Access Token	View
GET /auth/oauth2/user/info	Fetch the current user's public profile with an Access Token	View
GET /auth/oauth2/user/api_key	Fetch the user's latest API Key with an Access Token	View

Self-Hosted Administration

Account and collaboration operations for Self-Hosted Commercial Edition instances, called through your instance domain (https://your-swanlab-domain.com/api).

User Management

The first deployment creates the single root user (requires a License); afterwards, create users in bulk, reset passwords, deactivate/restore/delete users, and retrieve any user's latest API Key.

Endpoint	What it does	Docs
POST /self_hosted/root	Create the single root user on first deployment (License required)	View
POST /self_hosted/users	Create users in bulk	View
POST /self_hosted/user/password	Change a password (the root user can change any user's)	View
POST /self_hosted/user/pause	Deactivate a user and clear their API Key and sessions	View
POST /self_hosted/user/unpause	Restore a deactivated user	View
POST /self_hosted/user/del	Soft-delete a user and purge sessions and cache	View
GET /self_hosted/user/key/{username}	Get a user's latest API Key, creating one when none exists	View

Organization Management

Create organization spaces with a designated owner and adjust member roles.

Endpoint	What it does	Docs
POST /self_hosted/team	Create an organization space with a designated owner	View
POST /self_hosted/team/member	Invite a member to an organization or change their role	View
POST /self_hosted/team/member/del	Remove a member from an organization	View

Project Collaboration

Add project collaborators with read/write permissions.

Endpoint	What it does	Docs
POST /self_hosted/project/collaborator	Invite a project collaborator or change their permission	View
POST /self_hosted/project/collaborator/del	Remove a project collaborator	View

SSO Binding

Administrators bind existing users to third-party accounts directly; unbinding and rebinding are supported, and leftovers under deactivated users or Providers can be cleaned up.

Endpoint	What it does	Docs
POST /self_hosted/sso/bind	Bind a user to a third-party account (duplicate returns 409)	View
POST /self_hosted/sso/bind/del	Unbind an account, including leftovers under a disabled Provider	View