openapi: 3.1.0
info:
  title: Split Admin Users API
  description: The Split Admin API is a REST API that enables programmatic management of workspaces (projects), environments, traffic types, attributes, users, groups, API keys, and change requests within the Split platform (now Harness Feature Management and Experimentation). The API uses resource-oriented URLs, returns JSON responses, and requires Admin API keys for authentication. All endpoints are prefixed with /internal/api/v2 on the api.split.io host.
  version: '2.0'
  contact:
    name: Split Support
    url: https://help.split.io
  termsOfService: https://www.split.io/terms-of-service/
servers:
- url: https://api.split.io/internal/api/v2
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Users
  description: Manage users within the Split account, including inviting new users and updating user roles.
paths:
  /users:
    get:
      operationId: listUsers
      summary: List users
      description: Retrieves all users that the Admin API key has access to within the account. Returns user details including status, email, and group memberships.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: status
        in: query
        description: Filter users by status
        schema:
          type: string
          enum:
          - ACTIVE
          - DEACTIVATED
          - PENDING
      responses:
        '200':
          description: Successful response containing list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          description: Unauthorized - invalid or missing API key
  /users/{userId}:
    get:
      operationId: getUser
      summary: Get user
      description: Retrieves a single user by their unique identifier.
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        description: The unique identifier of the user
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: User not found
    put:
      operationId: updateUser
      summary: Update user
      description: Updates a user's profile, including their role and group memberships.
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        description: The unique identifier of the user
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: User not found
    delete:
      operationId: deleteUser
      summary: Deactivate user
      description: Deactivates a user within the account.
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        description: The unique identifier of the user
        schema:
          type: string
      responses:
        '200':
          description: User deactivated successfully
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: User not found
  /users/invite:
    post:
      operationId: inviteUser
      summary: Invite user
      description: Invites a new user to the account by sending an invitation email.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInvite'
      responses:
        '200':
          description: User invited successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized - invalid or missing API key
components:
  schemas:
    User:
      type: object
      description: A user within the Split account
      properties:
        id:
          type: string
          description: Unique identifier for the user
        email:
          type: string
          format: email
          description: Email address of the user
        name:
          type: string
          description: Full name of the user
        status:
          type: string
          description: Current status of the user
          enum:
          - ACTIVE
          - DEACTIVATED
          - PENDING
        type:
          type: string
          description: User type or role
        groups:
          type: array
          description: Groups the user belongs to
          items:
            $ref: '#/components/schemas/GroupRef'
    UserList:
      type: object
      description: Paginated list of users
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/User'
        offset:
          type: integer
          description: Current offset in the result set
        limit:
          type: integer
          description: Maximum number of results returned
        totalCount:
          type: integer
          description: Total number of users available
    UserUpdate:
      type: object
      description: Request body for updating a user
      properties:
        name:
          type: string
          description: Updated name for the user
        status:
          type: string
          description: Updated status for the user
          enum:
          - ACTIVE
          - DEACTIVATED
        groups:
          type: array
          description: Updated list of group references
          items:
            $ref: '#/components/schemas/GroupRef'
    GroupRef:
      type: object
      description: A reference to a group
      properties:
        id:
          type: string
          description: Unique identifier of the referenced group
        type:
          type: string
          description: Type of the group reference
    UserInvite:
      type: object
      description: Request body for inviting a new user
      required:
      - email
      properties:
        email:
          type: string
          format: email
          description: Email address to send the invitation to
        groups:
          type: array
          description: Groups to add the invited user to
          items:
            $ref: '#/components/schemas/GroupRef'
  parameters:
    limitParam:
      name: limit
      in: query
      description: Maximum number of results to return per page
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20
    offsetParam:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        minimum: 0
        default: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Admin API key passed as a Bearer token in the Authorization header.
externalDocs:
  description: Split Admin API Documentation
  url: https://docs.split.io/reference/introduction