GitBucket
API Reference: Users
GET /users/login
Summary: Initiate OIDC Login Flow
Description: Initiates the OIDC authentication flow.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
frontend_callback_uri |
query | No | anyOf | The frontend URI to redirect back to after OIDC provider. |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/login?frontend_callback_uri=<frontend_callback_uri>' \ -H 'accept: application/json'
GET /users/login/callback
Summary: Handle OIDC Login Callback
Description: Handles the callback from the OIDC provider.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
code |
query | Yes | string | Authorization code from OIDC provider |
state |
query | Yes | string | The original frontend redirect URI |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/login/callback?code=<code>&state=<state>' \ -H 'accept: application/json'
GET /users/me
Summary: Get Current User Status
Description: Checks the login status of the current user. Requires a valid user_id to be present in the request header.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/me' \ -H 'accept: application/json' \ -H 'X-User-ID: <your_user_id>'
POST /users/login/local
Summary: Local Authentication Fallback
Description: Day 1: Local Username/Password Login.
Request Body
Required: Yes
- Media Type:
application/json - Schema:
LocalLoginRequest(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'POST' \
'http://localhost:8000/api/v1/users/login/local' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{}'
PUT /users/password
Summary: Update User Password
Description: Update User Password
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
PasswordUpdateRequest(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'PUT' \
'http://localhost:8000/api/v1/users/password' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
GET /users/me/profile
Summary: Get Current User Profile
Description: Retrieves profile information for the current user.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/me/profile' \ -H 'accept: application/json' \ -H 'X-User-ID: <your_user_id>'
PUT /users/me/profile
Summary: Update User Profile
Description: Updates profile details for the current user.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
UserProfileUpdate(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'PUT' \
'http://localhost:8000/api/v1/users/me/profile' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
GET /users/me/config
Summary: Get Current User Preferences
Description: Gets user specific preferences (LLM, TTS, STT config overrides).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/me/config' \ -H 'accept: application/json' \ -H 'X-User-ID: <your_user_id>'
PUT /users/me/config
Summary: Update Current User Preferences
Description: Updates user specific preferences.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
UserPreferences(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'PUT' \
'http://localhost:8000/api/v1/users/me/config' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
GET /users/me/config/models
Summary: Get Models for Provider
Description: Get Models for Provider
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
provider_name |
query | Yes | string | |
section |
query | No | string |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/me/config/models?provider_name=<provider_name>§ion=<section>' \ -H 'accept: application/json'
GET /users/me/config/providers
Summary: Get All Valid Providers per Section
Description: Get All Valid Providers per Section
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
section |
query | No | string | |
configured_only |
query | No | boolean | If true, only returns providers currently configured in preferences or system defaults |
x-user-id |
header | No | anyOf |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/me/config/providers?section=<section>&configured_only=<configured_only>' \ -H 'accept: application/json' \ -H 'X-User-ID: <your_user_id>'
POST /users/me/config/verify_llm
Summary: Verify Llm
Description: Verify Llm
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
VerifyProviderRequest(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'POST' \
'http://localhost:8000/api/v1/users/me/config/verify_llm' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
POST /users/me/config/verify_tts
Summary: Verify Tts
Description: Verify Tts
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
VerifyProviderRequest(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'POST' \
'http://localhost:8000/api/v1/users/me/config/verify_tts' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
POST /users/me/config/verify_stt
Summary: Verify Stt
Description: Verify Stt
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
VerifyProviderRequest(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'POST' \
'http://localhost:8000/api/v1/users/me/config/verify_stt' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
POST /users/logout
Summary: Log Out the Current User
Description: Simulates a user logout. In a real application, this would clear the session token or cookie.
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
Example Usage
curl -X 'POST' \ 'http://localhost:8000/api/v1/users/logout' \ -H 'accept: application/json'
GET /users/me/config/export
Summary: Export Configurations to YAML
Description: Exports the effective user configuration as a YAML file (Admin only).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/me/config/export' \ -H 'accept: application/json' \ -H 'X-User-ID: <your_user_id>'
POST /users/me/config/import
Summary: Import Configurations from YAML
Description: Imports user configuration from a YAML file.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
multipart/form-data - Schema:
Body_import_user_config_yaml_users_me_config_import_post(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'POST' \ 'http://localhost:8000/api/v1/users/me/config/import' \ -H 'accept: application/json' \ -H 'X-User-ID: <your_user_id>' \ -H 'Content-Type: multipart/form-data' \ -F 'file=@/path/to/file'
GET /users/admin/users
Summary: List All Users (Admin Only)
Description: Returns a list of all registered users in the system.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/admin/users' \ -H 'accept: application/json' \ -H 'X-User-ID: <your_user_id>'
PUT /users/admin/users/{uid}/role
Summary: Update User Role (Admin Only)
Description: Updates a user's role. Prevents demoting the last administrator.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uid |
path | Yes | string | |
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
UserRoleUpdate(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'PUT' \
'http://localhost:8000/api/v1/users/admin/users/{uid}/role' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
PUT /users/admin/users/{uid}/group
Summary: Update User Group (Admin Only)
Description: Assigns a user to a group.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uid |
path | Yes | string | |
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
UserGroupUpdate(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'PUT' \
'http://localhost:8000/api/v1/users/admin/users/{uid}/group' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
GET /users/admin/groups
Summary: List All Groups (Admin Only)
Description: Returns all existing groups.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'GET' \ 'http://localhost:8000/api/v1/users/admin/groups' \ -H 'accept: application/json' \ -H 'X-User-ID: <your_user_id>'
POST /users/admin/groups
Summary: Create Group (Admin Only)
Description: Creates a new group.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
GroupCreate(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'POST' \
'http://localhost:8000/api/v1/users/admin/groups' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
PUT /users/admin/groups/{gid}
Summary: Update Group (Admin Only)
Description: Updates a group's metadata or policy.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
gid |
path | Yes | string | |
x-user-id |
header | No | anyOf |
Request Body
Required: Yes
- Media Type:
application/json - Schema:
GroupUpdate(Define in Models)
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'PUT' \
'http://localhost:8000/api/v1/users/admin/groups/{gid}' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>' \
-H 'Content-Type: application/json' \
-d '{}'
DELETE /users/admin/groups/{gid}
Summary: Delete Group (Admin Only)
Description: Deletes a group. Users are moved back to 'ungrouped'.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
gid |
path | Yes | string | |
x-user-id |
header | No | anyOf |
Responses
| Status Code | Description |
|---|---|
200 |
Successful Response |
422 |
Validation Error |
Example Usage
curl -X 'DELETE' \
'http://localhost:8000/api/v1/users/admin/groups/{gid}' \
-H 'accept: application/json' \
-H 'X-User-ID: <your_user_id>'