Superb AI Users API

openapi: 3.2.0
info:
  title: MLOps Platform Users API
  description: Multi-tenant labeling-platform backend.
  version: 0.1.0
tags:
- name: Users
paths:
  /tenants/{slug}/users:
    post:
      tags:
      - Users
      summary: Create User Seeded
      description: 'Programmatic seeding (ADR-0113): create a ready-to-login member directly —

        WorkOS account with a password, org membership mirror, membership row. No

        email is sent. Humans join via invitations + in-app accept (routes/me.py,

        routes/invitations.py).'
      operationId: users-create_user_seeded
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSeedCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Users
      summary: List Users
      description: 'List workspace users. `?q=` matches (case-insensitively) against email,

        first_name, and last_name.'
      operationId: users-list_users
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max rows per page.
          default: 50
          title: Limit
        description: Max rows per page.
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque pagination cursor from a previous response's `next_cursor`; omit for the first page.
          title: Cursor
        description: Opaque pagination cursor from a previous response's `next_cursor`; omit for the first page.
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 255
          - type: 'null'
          description: Case-insensitive substring search (min 1 char). Wildcards are matched literally.
          title: Q
        description: Case-insensitive substring search (min 1 char). Wildcards are matched literally.
      - name: role
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/WorkspaceRole'
          - type: 'null'
          description: '`admin` or `member`. Filters to that workspace role.'
          title: Role
        description: '`admin` or `member`. Filters to that workspace role.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tenants/{slug}/users/me:
    delete:
      tags:
      - Users
      summary: Leave Workspace
      description: 'Leave this workspace (ADR-0113). The account survives; only the

        membership goes. The last admin can''t leave — hand off first.'
      operationId: users-leave_workspace
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Users
      summary: Get Me
      operationId: users-get_me
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - Users
      summary: Update Me
      description: Edit your own first/last name. Email + password have dedicated flows.
      operationId: users-update_me
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSelfUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tenants/{slug}/users/me/password:
    post:
      tags:
      - Users
      summary: Change My Password
      description: 'Change your own password. Verifies `previous_password` against the identity

        provider (WorkOS), then sets `new_password` (subject to the provider''s strength

        policy). 401 if the current password is wrong; 422 if the new one is rejected

        (too short / common). No response body on success (204).'
      operationId: users-change_my_password
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tenants/{slug}/users/{user_id}:
    patch:
      tags:
      - Users
      summary: Update User Role
      description: 'Change a workspace user''s role. Admin-only.


        Last-admin guard: demoting the only remaining admin (whether yourself

        or someone else) is blocked with 400 — otherwise the workspace could

        be left with no one able to invite users, create datasets/projects, or

        delete exports. Promote a new admin first.'
      operationId: users-update_user_role
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRoleUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Users
      summary: Remove Member
      description: 'Remove a member from this workspace (admin; ADR-0113). Their account is

        untouched — only the membership (and its API keys, via cascade) goes.

        Removing yourself is `DELETE /users/me` (leave); the last admin is guarded

        either way.'
      operationId: users-remove_member
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable; free to evolve. Don't pattern-match on this.
            hint:
              type: string
              nullable: true
              description: When present, a concrete next step (often references a CLI command).
            details:
              type: object
              nullable: true
              description: Per-`code` structured payload; schema documented per code.
            request_id:
              type: string
              nullable: true
              description: Correlation id for support / log lookups.
    UserResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        email:
          type: string
          title: Email
        first_name:
          type: string
          title: First Name
        last_name:
          type: string
          title: Last Name
        role:
          $ref: '#/components/schemas/WorkspaceRole'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - email
      - first_name
      - last_name
      - role
      - created_at
      - updated_at
      title: UserResponse
    UserRoleUpdate:
      properties:
        role:
          $ref: '#/components/schemas/WorkspaceRole'
      type: object
      required:
      - role
      title: UserRoleUpdate
      description: 'Body for PATCH /users/{user_id}. Admin-only — changes the target

        user''s workspace role. Blocked by last-admin guard when demoting.'
    UserPage:
      properties:
        items:
          items:
            $ref: '#/components/schemas/UserResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - items
      title: UserPage
    UserSeedCreate:
      properties:
        email:
          type: string
          maxLength: 254
          format: email
          title: Email
          description: Email address of the account to create.
        first_name:
          type: string
          maxLength: 100
          minLength: 1
          title: First Name
          description: Given name (no sign-up form runs on this path).
        last_name:
          type: string
          maxLength: 100
          minLength: 1
          title: Last Name
          description: Family name.
        password:
          type: string
          maxLength: 128
          minLength: 10
          title: Password
          description: Initial password (WorkOS strength rules apply).
        role:
          $ref: '#/components/schemas/WorkspaceRole'
          description: Workspace role to grant.
          default: member
      type: object
      required:
      - email
      - first_name
      - last_name
      - password
      title: UserSeedCreate
      description: 'Body for `POST /users` — programmatic seeding ONLY (ADR-0113): create a

        ready-to-login member directly (WorkOS account with password + membership,

        no email). Humans join via `/tenants/{slug}/invitations` + in-app accept.'
    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
    WorkspaceRole:
      type: string
      enum:
      - admin
      - member
      title: WorkspaceRole
    ChangePasswordRequest:
      properties:
        previous_password:
          type: string
          minLength: 1
          title: Previous Password
          description: Your current password (re-verified).
        new_password:
          type: string
          maxLength: 256
          minLength: 10
          title: New Password
          description: The new password (10+ characters, not a common one).
      type: object
      required:
      - previous_password
      - new_password
      title: ChangePasswordRequest
      description: 'Change your own password. `previous_password` is re-verified against the

        identity provider before the new one is set; `new_password` must satisfy the

        provider''s strength policy (10+ chars, not a common password).'
    UserSelfUpdate:
      properties:
        first_name:
          anyOf:
          - type: string
            maxLength: 100
            minLength: 1
          - type: 'null'
          title: First Name
          description: Updated given name. Omit to leave unchanged.
        last_name:
          anyOf:
          - type: string
            maxLength: 100
            minLength: 1
          - type: 'null'
          title: Last Name
          description: Updated family name. Omit to leave unchanged.
      type: object
      title: UserSelfUpdate
      description: 'Edit your own profile (first/last name only). Email + password have their

        own dedicated endpoints.'
    ErrorCode:
      type: string
      enum:
      - UNCATEGORIZED
      - AUTH_MISSING
      - AUTH_INVALID_CREDENTIAL
      - AUTH_TOKEN_EXPIRED
      - AUTH_FORBIDDEN
      - AUTH_TENANT_MISMATCH
      - VALIDATION_ERROR
      - VALIDATION_REQUIRED_CLASSIFICATION_MISSING
      - BAD_REQUEST
      - INVALID_CURSOR
      - INVALID_FILTER
      - UNSUPPORTED_OPERATION
      - PAYLOAD_TOO_LARGE
      - TENANT_NOT_FOUND
      - TENANT_SLUG_TAKEN
      - USER_NOT_FOUND
      - USER_EMAIL_TAKEN
      - INVITATION_NOT_FOUND
      - INVITATION_PENDING
      - INVITATION_NOT_PENDING
      - INVITATION_EXPIRED
      - LAST_ADMIN
      - DATASET_NOT_FOUND
      - DATASET_NAME_TAKEN
      - DATASET_DELETED
      - DATASET_ASSET_CAP_EXCEEDED
      - ASSET_NOT_FOUND
      - ASSET_DELETED
      - ASSET_NOT_EMBEDDED
      - ASSET_FORMAT_UNSUPPORTED
      - ASSET_TOO_LARGE
      - PROJECT_NOT_FOUND
      - PROJECT_ARCHIVED
      - PROJECT_MEMBER_NOT_FOUND
      - PROJECT_CLASS_NOT_FOUND
      - VERSION_NOT_FOUND
      - MODEL_NOT_FOUND
      - RESOURCE_NOT_READY
      - PROJECT_STATE_FORBIDDEN
      - CLASS_LOCKED
      - CLASS_IN_USE
      - DEPLOYMENT_NOT_FOUND
      - DEPLOYMENT_STATE_FORBIDDEN
      - EXPORT_EXPIRED
      - EXPORT_FAILED
      - ANNOTATION_NOT_FOUND
      - JOB_NOT_FOUND
      - JOB_ALREADY_RUNNING
      - JOB_PER_TENANT_CAP
      - JOB_TERMINAL
      - EMBEDDER_UNAVAILABLE
      - EMBEDDER_INVOCATION_FAILED
      - NAME_TAKEN
      - IDEMPOTENCY_REPLAY
      - CONCURRENT_MODIFICATION
      - RATE_LIMITED
      - RESOURCE_LIMIT_EXCEEDED
      - INTERNAL_ERROR
      - DEPENDENCY_UNAVAILABLE
      - MODEL_LOADING
      - MODEL_STARTING
      description: Stable error code enum. Pattern-match here, never on `message`. Adding values is non-breaking; renaming/removing is a major bump.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      description: Cognito access token
      scheme: bearer