openapi: 3.0.1
info:
  title: Admin
  description: <h2>An API Administering the Blackbird AI Platform.</h2>
servers:
  - url: https://api.blackbird.ai/admin
x-hideTryItPanel: false
x-codeSamples: true
paths:
  /admin/users:
    get:
      tags:
        - users
      parameters:
        - name: email
          in: query
          description: The email of the user to filter the list
          required: false
          schema:
            type: string
            format: email
      summary: List all users in the organization
      description: >-
        Retrieves all users in the organization (Reconciliation endpoint). This
        endpoint allows organization administrators to reconcile their user list
        with internal identity management systems.
      operationId: getUsers
      responses:
        '200':
          description: List of users with their ID, email, active status, and relationships
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - users
      summary: Creates a user
      description: Creates a user with the given email and in the caller's organization.
      operationId: createUser
      requestBody:
        description: A user to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Invalid request body
          content:
            application/json: {}
  /admin/users/{id}:
    get:
      tags:
        - users
      summary: Get a specific user
      description: Retrieves a specific user by ID within the organization.
      operationId: getUserById
      parameters:
        - name: id
          in: path
          description: The ID of the user to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - users
      summary: Update a user's active status
      description: Updates a user's active status using json-merge-patch format.
      operationId: updateUserStatus
      parameters:
        - name: id
          in: path
          description: The ID of the user to update
          required: true
          schema:
            type: string
      requestBody:
        description: Updating user's active status
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/roles:
    get:
      tags:
        - users
      summary: Get available user roles
      description: Retrieves a list of available user roles that can be assigned to users.
      operationId: getRoles
      responses:
        '200':
          description: List of available roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Role:
      type: string
      description: >-
        The name of a user role. Note that there will be more values in the
        future and you should not consider a value outside the known enumeration
        as a breaking change, but the meaning of existing values will remain
        stable.
      enum:
        - leadAnalyst
    UserResource:
      type: object
      required:
        - id
        - email
        - status
        - roles
      properties:
        id:
          type: string
          description: The resource ID
        email:
          type: string
          format: email
          description: The email address of the user
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
          description: The roles the user has
        status:
          type: string
          description: Whether the user is active or deactivated
        firstName:
          type: string
          description: The first name of the user
        lastName:
          type: string
          description: The last name of the user
    UsersResponse:
      type: object
      description: Response for collection of users (GET /users)
      required:
        - body
      properties:
        body:
          type: array
          description: Array of user resources
          items:
            $ref: '#/components/schemas/UserResource'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: The error message further explaining the error
    UserCreateRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: The email address of the user
        status:
          type: string
          description: Whether the user is active or deactivated
          default: active
          enum:
            - active
            - deactivated
        lastName:
          type: string
          description: The last name of the user
        firstName:
          type: string
          description: The first names of the user
        suppressWelcomeEmail:
          type: boolean
          description: Prevents welcome email sending
        appRootUrl:
          type: string
          description: >-
            App root url to redirect users too. Not used when
            suppressWelcomeEmail is true.
        pageUrl:
          type: string
          description: >-
            Page url to redirect users too. Not used when suppressWelcomeEmail
            is true.
          default: reset-password
    UserResponse:
      type: object
      description: Response for a single user (GET /users/{id})
      allOf:
        - $ref: '#/components/schemas/UserResource'
    UserUpdateRequest:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          description: The ID of the user to update
        status:
          type: string
          description: Whether the user is active or deactivated
          enum:
            - active
            - deactivated
        lastName:
          type: string
          description: The last name of the user
        firstName:
          type: string
          description: The first name of the user
    RoleResource:
      type: object
      required:
        - roleName
        - displayName
      properties:
        roleName:
          type: string
          description: The unique identifier for the role
        displayName:
          type: string
          description: The human-readable display name for the role
    RolesResponse:
      type: object
      description: Response for collection of available roles (GET /admin/roles)
      required:
        - body
      properties:
        body:
          type: array
          description: Array of role resources
          items:
            $ref: '#/components/schemas/RoleResource'
  securitySchemes:
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.blackbird.ai/auth/oauth2/token
          scopes: {}
security:
  - clientCredentials: []
