openapi: 3.0.3
info:
  title: Paradigm API
  version: xenial-xerus (v3-instance)
  description: A versatile and adaptable tool designed to integrate Generative AI
    into your applications
paths:
  /api/v3/instance/workspaces:
    get:
      operationId: api_v3_instance_workspaces_list
      description: |-
        ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

        Get the list of every existing workspaces on the instance.
      summary: List instance workspaces
      parameters:
      - in: query
        name: company_id
        schema:
          type: integer
      - in: query
        name: company_name
        schema:
          type: string
      - in: query
        name: document_upload_method
        schema:
          type: string
          enum:
          - manual
          - synced
        description: |-
          Method for adding documents to this workspace: manual uploads or synced from datasources

          * `manual` - Manual
          * `synced` - Synced
      - in: query
        name: group_id
        schema:
          type: integer
      - in: query
        name: group_name
        schema:
          type: string
      - in: query
        name: name
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: workspace_type
        schema:
          type: string
          enum:
          - company
          - custom
          - personal
        description: |-
          * `company` - Company
          * `personal` - Personal
          * `custom` - Custom
      tags:
      - Workspaces
      security:
      - bearerAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInstanceWorkspaceV3ListResponseList'
          description: List of workspaces
        '400':
          description: Invalid input
        '401':
          description: Authentication failed - missing or invalid API key
        '403':
          description: Permission denied - insufficient rights to access instance
            workspaces
    post:
      operationId: api_v3_instance_workspaces_create
      description: Create a new instance workspace.
      summary: Create a new instance workspace
      tags:
      - Workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceCreateV3Request'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceCreateV3Request'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceCreateV3Request'
        required: true
      security:
      - bearerAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceWorkspaceV3DetailsResponse'
          description: Instance workspace created successfully
        '400':
          description: Invalid input
        '401':
          description: Authentication failed - missing or invalid API key
        '403':
          description: Permission denied - insufficient rights to create instance
            workspace
  /api/v3/instance/workspaces/{id}:
    get:
      operationId: api_v3_instance_workspaces_retrieve
      description: |-
        ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

        Retrieve the information of a given workspace. This endpoint can only be used by instance level admins.
        To retrieve one of your workspaces, please use the GET /api/v3/workspaces/{id} endpoint.
      summary: Retrieve instance workspace
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: The unique identifier of the workspace.
        required: true
      tags:
      - Workspaces
      security:
      - bearerAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceWorkspaceV3DetailsResponse'
          description: Workspace updated successfully
        '400':
          description: Bad Request - Invalid input parameters (empty name, name too
            long, unsupported fields, etc.)
        '401':
          description: Unauthenticated - Missing or invalid API key/session cookie
        '403':
          description: Unauthorized - User does not have instance-level permissions
        '404':
          description: Not Found - Workspace does not exist
    patch:
      operationId: api_v3_instance_workspaces_partial_update
      description: |-
        ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

        Partially update a given workspace. The authenticated user must be an instance-level administrator.

        **Fields:**
        - **name** (string, optional): Desired workspace name
        - **description** (string, optional): Desired workspace description. Send empty string or null to clear.

        **Permissions:**
        - Instance-level administrators (Sys Admin, Admin, Account Manager) can update any workspace across all companies
      summary: Partially update a workspace
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedInstanceWorkspaceUpdateV3Request'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedInstanceWorkspaceUpdateV3Request'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedInstanceWorkspaceUpdateV3Request'
      security:
      - bearerAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceWorkspaceV3DetailsResponse'
          description: Workspace updated successfully
        '400':
          description: Bad Request - Invalid input parameters (empty name, name too
            long, unsupported fields, etc.)
        '401':
          description: Unauthenticated - Missing or invalid API key/session cookie
        '403':
          description: Unauthorized - User does not have instance-level permissions
        '404':
          description: Not Found - Workspace does not exist
  /api/v3/instance/workspaces/{id}/members:
    get:
      operationId: api_v3_instance_workspaces_members_retrieve
      description: |-
        ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

        Returns the list of members linked to a workspace in the authenticated user's company. This endpoint can only be used by company-level admins or higher.
      summary: Get the list of members for any workspace. This endpoint can only be
        used by instance level admins.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Workspaces
      security:
      - bearerAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceMembersV3Response'
          description: ''
        '401':
          content:
            application/json:
              schema:
                description: Unauthenticated
          description: ''
        '403':
          content:
            application/json:
              schema:
                description: Unauthorized
          description: ''
        '404':
          content:
            application/json:
              schema:
                description: Not Found
          description: ''
    post:
      operationId: api_v3_instance_workspaces_members_create
      description: |-
        ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

        Add a new member (user or group) to a custom workspace. This endpoint can only be used by instance level admins.
      summary: Add a member to a workspace
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceAddMemberV3Request'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceAddMemberV3Request'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceAddMemberV3Request'
        required: true
      security:
      - bearerAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceMembersV3Response'
          description: Member added successfully
        '400':
          description: Invalid input
        '401':
          description: Authentication failed - missing or invalid API key
        '403':
          description: Permission denied - insufficient rights to modify
        '404':
          description: Workspace, user, or group not found
        '409':
          description: Member already exists in workspace
    put:
      operationId: api_v3_instance_workspaces_members_update
      description: |-
        ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

        Bulk replace the entire list of members for a custom workspace. This endpoint can only be used by instance level admins.
      summary: Replace all workspace members
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceSetMembersV3Request'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceSetMembersV3Request'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InstanceWorkspaceSetMembersV3Request'
      security:
      - bearerAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceMembersV3Response'
          description: Members replaced successfully
        '400':
          description: Invalid input
        '401':
          description: Authentication failed - missing or invalid API key
        '403':
          description: Permission denied - insufficient rights to modify
        '404':
          description: Workspace, user, or group not found
  /api/v3/instance/workspaces/{id}/members/groups/{group_id}:
    delete:
      operationId: api_v3_instance_workspaces_members_groups_destroy
      description: |-
        ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

        Remove a group from a workspace. This endpoint can only be used by instance level admins.
      summary: Remove a group from a workspace
      parameters:
      - in: path
        name: group_id
        schema:
          type: integer
        required: true
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Workspaces
      security:
      - bearerAuth: []
      responses:
        '204':
          description: Group removed from workspace successfully
        '401':
          description: Authentication failed - missing or invalid API key
        '403':
          description: Permission denied - insufficient rights to modify
        '404':
          description: Workspace or group not found
  /api/v3/instance/workspaces/{id}/members/users/{user_id}:
    delete:
      operationId: api_v3_instance_workspaces_members_users_destroy
      description: Remove a user from a custom workspace. This endpoint can only be
        used by instance level admins.
      summary: Delete a user from a workspace
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: The unique identifier of the workspace.
        required: true
      - in: path
        name: user_id
        schema:
          type: integer
        description: The unique identifier of the user to remove from the workspace.
        required: true
      tags:
      - Workspaces
      security:
      - bearerAuth: []
      responses:
        '204':
          description: User removed from workspace successfully
        '401':
          description: Authentication failed - missing or invalid API key
        '403':
          description: Permission denied - insufficient rights to remove user from
            workspace
        '404':
          description: Workspace or user not found
components:
  schemas:
    DocumentUploadMethodEnum:
      enum:
      - manual
      - synced
      type: string
      description: |-
        * `manual` - Manual
        * `synced` - Synced
    GroupMember:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        role:
          type: string
      required:
      - id
      - name
      - role
    InstanceWorkspaceAddMemberV3Request:
      type: object
      description: 'V3 API: Request serializer for adding a member to a workspace
        (admin-only endpoint)'
      properties:
        user_id:
          type: integer
        group_id:
          type: integer
        role:
          $ref: '#/components/schemas/RoleEnum'
      required:
      - role
    InstanceWorkspaceCreateV3Request:
      type: object
      description: Serializer for creating an instance workspace (custom only).
      properties:
        name:
          type: string
          maxLength: 100
        description:
          type: string
          default: ''
        workspace_type:
          $ref: '#/components/schemas/WorkspaceTypeEnum'
        document_upload_method:
          $ref: '#/components/schemas/DocumentUploadMethodEnum'
        company_id:
          type: integer
      required:
      - company_id
      - name
    InstanceWorkspaceSetMembersV3Request:
      type: object
      description: 'V3 API: Request serializer for bulk replacing workspace members
        (admin-only endpoint)'
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserMember'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/GroupMember'
    InstanceWorkspaceV3DetailsResponse:
      type: object
      description: V3 Response serializer for instance-level workspace operations.
      properties:
        id:
          type: integer
        name:
          type: string
        workspace_type:
          type: string
        document_upload_method:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        user_role:
          type: string
          readOnly: true
        used_storage:
          type: number
          format: double
        files_count:
          type: integer
        company:
          $ref: '#/components/schemas/WorkspaceCompany'
      required:
      - company
      - created_at
      - description
      - document_upload_method
      - files_count
      - id
      - name
      - updated_at
      - used_storage
      - user_role
      - workspace_type
    InstanceWorkspaceV3ListResponse:
      type: object
      description: V3 Response serializer for instance-level workspaces endpoint.
      properties:
        id:
          type: integer
        name:
          type: string
        workspace_type:
          type: string
        document_upload_method:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        user_role:
          type: string
          readOnly: true
        company:
          $ref: '#/components/schemas/WorkspaceCompany'
      required:
      - company
      - created_at
      - description
      - document_upload_method
      - id
      - name
      - updated_at
      - user_role
      - workspace_type
    PaginatedInstanceWorkspaceV3ListResponseList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/InstanceWorkspaceV3ListResponse'
    PatchedInstanceWorkspaceUpdateV3Request:
      type: object
      description: 'V3 API: Request serializer for instance-level workspace updates
        (admin-only endpoint)'
      properties:
        name:
          type: string
          maxLength: 100
        description:
          type: string
    RoleEnum:
      enum:
      - owner
      - editor
      - viewer
      type: string
      description: |-
        * `owner` - Owner
        * `editor` - Editor
        * `viewer` - Viewer
    UserMember:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
        role:
          type: string
      required:
      - email
      - id
      - role
    WorkspaceCompany:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
      required:
      - id
      - name
    WorkspaceMembersV3Response:
      type: object
      description: V3 Response serializer for workspace members.
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserMember'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/GroupMember'
      required:
      - groups
      - users
    WorkspaceTypeEnum:
      enum:
      - custom
      type: string
      description: '* `custom` - custom'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.
servers:
- url: https://paradigm.lighton.ai
tags:
- name: Workspaces
  description: Operations about workspaces