Kagura AI System Admins API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud System Admins API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: system-admins
  description: 'Admin: system administrator management'
paths:
  /api/v1/admin/system-admins:
    get:
      tags:
      - system-admins
      summary: List System Admins
      description: 'List all system administrators.


        Requires: System Admin role


        Returns:

        List of system admins with is_initial_admin flags and statistics


        Example response:

        {

        "admins": [

        {

        "email": "admin@example.com",

        "user_id": "google-oauth2|123456",

        "name": "Admin User",

        "role": "admin",

        "is_initial_admin": true,

        "created_at": "2025-01-01T00:00:00Z",

        "last_login_at": "2025-12-06T10:00:00Z",

        "memory_count": 150,

        "is_active": true

        }

        ],

        "total": 1

        }'
      operationId: list_system_admins_api_v1_admin_system_admins_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemAdminListResponse'
    post:
      tags:
      - system-admins
      summary: Promote To System Admin
      description: 'Promote a user to system administrator.


        Requires: System Admin role


        Args:

        request: User ID to promote


        Returns:

        Updated user with success message


        Raises:

        404: User not found

        400: User is already a system admin


        Example request:

        {

        "user_id": "google-oauth2|123456"

        }


        Example response:

        {

        "success": true,

        "user": { ... user details ... },

        "message": "User admin2@example.com promoted to system administrator"

        }'
      operationId: promote_to_system_admin_api_v1_admin_system_admins_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoteToSystemAdminRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoteToSystemAdminResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/system-admins/{user_id}:
    delete:
      tags:
      - system-admins
      summary: Demote System Admin
      description: 'Demote a system administrator to regular user.


        Protection:

        - Cannot demote initial admin (is_initial_admin=True)

        - Cannot demote last remaining admin


        Requires: System Admin role


        Args:

        user_id: User ID to demote


        Returns:

        Success message


        Raises:

        404: User not found

        400: User is not a system admin

        403: Demote operation is protected (initial admin or last admin)


        Example response:

        {

        "success": true,

        "message": "User admin2@example.com demoted to standard user"

        }'
      operationId: demote_system_admin_api_v1_admin_system_admins__user_id__delete
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PromoteToSystemAdminRequest:
      properties:
        user_id:
          type: string
          title: User Id
          description: OAuth2 user_id to promote
      type: object
      required:
      - user_id
      title: PromoteToSystemAdminRequest
      description: 'Request to promote user to system admin.


        Issue #166: System Admin promotion.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UserWithAdminFlag:
      properties:
        email:
          title: Email
        user_id:
          title: User Id
        name:
          title: Name
        picture:
          title: Picture
        role:
          title: Role
        is_initial_admin:
          title: Is Initial Admin
        created_at:
          title: Created At
        last_login_at:
          title: Last Login At
        memory_count:
          title: Memory Count
        is_active:
          title: Is Active
      type: object
      required:
      - email
      - user_id
      - name
      - picture
      - role
      - is_initial_admin
      - created_at
      - last_login_at
      - memory_count
      - is_active
      title: UserWithAdminFlag
      description: 'User model with system admin flags for admin management.


        Issue #166: System Admin vs Workspace Admin RBAC separation.

        Issue #1813: no integer ``id`` — address users by ``user_id``.'
    SystemAdminListResponse:
      properties:
        admins:
          items:
            $ref: '#/components/schemas/UserWithAdminFlag'
          type: array
          title: Admins
        total:
          type: integer
          title: Total
      type: object
      required:
      - admins
      - total
      title: SystemAdminListResponse
      description: 'Response for listing system administrators.


        Issue #166: System Admin management API.

        Issue #1813: ``initial_admin_id`` (integer PK) dropped — each entry''s

        ``is_initial_admin`` flag marks the protected initial admin.'
    PromoteToSystemAdminResponse:
      properties:
        success:
          type: boolean
          title: Success
        user:
          $ref: '#/components/schemas/UserWithAdminFlag'
        message:
          type: string
          title: Message
      type: object
      required:
      - success
      - user
      - message
      title: PromoteToSystemAdminResponse
      description: 'Response for system admin promotion.


        Issue #166: System Admin promotion result.'