openapi: 3.1.0
info:
  title: Sisense REST API
  description: >-
    The Sisense REST API provides programmatic access to the Sisense business
    intelligence platform, enabling management of dashboards, data models
    (Elasticubes and live models), users, groups, data security rules, and builds.
    The API uses Bearer token authentication obtained via the login endpoint or
    User Profiles settings. Endpoints follow RESTful conventions with standard
    HTTP methods for CRUD operations.
  version: v1
  contact:
    name: Sisense Support
    url: https://support.sisense.com/
  termsOfService: https://www.sisense.com/legal/terms-of-service/
  license:
    name: Commercial
    url: https://www.sisense.com/legal/terms-of-service/
externalDocs:
  description: Sisense REST API Documentation
  url: https://developer.sisense.com/guides/restApi/
servers:
  - url: https://{host}/api/v1
    description: Sisense Instance REST API v1
    variables:
      host:
        description: Your Sisense instance hostname
        default: your-instance.sisense.com
tags:
  - name: Authentication
    description: Login and token management
  - name: Dashboards
    description: Create, read, update, and manage dashboards
  - name: Users
    description: Manage Sisense users and user settings
  - name: Groups
    description: Manage user groups for access control
  - name: Elasticubes
    description: Manage Elasticube data models and builds
  - name: Data Security
    description: Configure row-level data security rules
  - name: Builds
    description: Manage Elasticube build operations
security:
  - bearerAuth: []
paths:
  /authentication/login:
    post:
      operationId: login
      summary: Login and Get Token
      description: >-
        Authenticates a user with username and password, returning a Bearer token
        for use in subsequent API requests.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: Sisense user email or username
                password:
                  type: string
                  description: Sisense user password
      responses:
        '200':
          description: Authentication successful, token returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid credentials
  /dashboards:
    get:
      operationId: listDashboards
      summary: List Dashboards
      description: >-
        Returns a list of dashboards accessible to the authenticated user.
        Supports filtering by various attributes.
      tags:
        - Dashboards
      parameters:
        - name: fields
          in: query
          description: Comma-separated list of fields to include in response
          required: false
          schema:
            type: string
        - name: sort
          in: query
          description: Field to sort by (prefix with - for descending)
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return
          required: false
          schema:
            type: integer
        - name: skip
          in: query
          description: Number of results to skip for pagination
          required: false
          schema:
            type: integer
        - name: expand
          in: query
          description: Replace foreign key IDs with full entity objects
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Dashboards retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dashboard'
        '401':
          description: Unauthorized - invalid or missing token
    post:
      operationId: createDashboard
      summary: Create Dashboard
      description: Creates a new dashboard in Sisense.
      tags:
        - Dashboards
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDashboardRequest'
      responses:
        '200':
          description: Dashboard created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
        '401':
          description: Unauthorized
  /dashboards/{id}:
    get:
      operationId: getDashboard
      summary: Get Dashboard
      description: Returns a specific dashboard by ID.
      tags:
        - Dashboards
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard identifier
          schema:
            type: string
        - name: fields
          in: query
          description: Fields to include in response
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Dashboard retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
        '404':
          description: Dashboard not found
    delete:
      operationId: deleteDashboard
      summary: Delete Dashboard
      description: Deletes a dashboard by ID.
      tags:
        - Dashboards
      parameters:
        - name: id
          in: path
          required: true
          description: Dashboard identifier
          schema:
            type: string
      responses:
        '200':
          description: Dashboard deleted successfully
        '404':
          description: Dashboard not found
  /dashboards/admin:
    get:
      operationId: listAllDashboards
      summary: List All Dashboards (Admin)
      description: >-
        Admin endpoint that returns all dashboards across all users.
        Requires admin privileges.
      tags:
        - Dashboards
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: skip
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: All dashboards retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dashboard'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - admin privileges required
  /users:
    get:
      operationId: listUsers
      summary: List Users
      description: Returns a list of users in the Sisense system.
      tags:
        - Users
      parameters:
        - name: fields
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: skip
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
    post:
      operationId: createUser
      summary: Create User
      description: Creates a new user in Sisense.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
  /users/{id}:
    get:
      operationId: getUser
      summary: Get User
      description: Returns a specific user by ID.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: User identifier
          schema:
            type: string
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
    patch:
      operationId: updateUser
      summary: Update User
      description: Updates specific fields of a user.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: User identifier
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: User updated successfully
        '404':
          description: User not found
    delete:
      operationId: deleteUser
      summary: Delete User
      description: Deletes a user from Sisense.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: User identifier
          schema:
            type: string
      responses:
        '200':
          description: User deleted successfully
        '404':
          description: User not found
  /groups:
    get:
      operationId: listGroups
      summary: List Groups
      description: Returns a list of user groups.
      tags:
        - Groups
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: skip
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Groups retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized
    post:
      operationId: createGroup
      summary: Create Group
      description: Creates a new user group.
      tags:
        - Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '200':
          description: Group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized
  /groups/{id}:
    delete:
      operationId: deleteGroup
      summary: Delete Group
      description: Deletes a user group.
      tags:
        - Groups
      parameters:
        - name: id
          in: path
          required: true
          description: Group identifier
          schema:
            type: string
      responses:
        '200':
          description: Group deleted successfully
        '404':
          description: Group not found
  /elasticubes/getElasticubes:
    get:
      operationId: listElasticubes
      summary: List Elasticubes
      description: Returns a list of all Elasticube data models.
      tags:
        - Elasticubes
      responses:
        '200':
          description: Elasticubes retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Elasticube'
        '401':
          description: Unauthorized
  /elasticubes/{server}/{elasticube}/datasecurity:
    get:
      operationId: getDataSecurityRules
      summary: Get Data Security Rules
      description: Returns all data security rules for a specific Elasticube.
      tags:
        - Data Security
      parameters:
        - name: server
          in: path
          required: true
          description: Server name (use 'LocalHost' for single-node)
          schema:
            type: string
        - name: elasticube
          in: path
          required: true
          description: Elasticube title
          schema:
            type: string
      responses:
        '200':
          description: Data security rules retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataSecurityRule'
        '401':
          description: Unauthorized
    post:
      operationId: createDataSecurityRule
      summary: Create Data Security Rule
      description: Creates a data security rule for an Elasticube.
      tags:
        - Data Security
      parameters:
        - name: server
          in: path
          required: true
          description: Server name
          schema:
            type: string
        - name: elasticube
          in: path
          required: true
          description: Elasticube title
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSecurityRule'
      responses:
        '200':
          description: Data security rule created successfully
        '401':
          description: Unauthorized
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from POST /api/v1/authentication/login
  schemas:
    AuthResponse:
      type: object
      properties:
        token:
          type: string
          description: Bearer authentication token
        success:
          type: boolean
        id:
          type: string
          description: Authenticated user ID
    Dashboard:
      type: object
      properties:
        oid:
          type: string
          description: Dashboard unique identifier
        title:
          type: string
          description: Dashboard display title
        desc:
          type: string
          description: Dashboard description
        owner:
          type: string
          description: Dashboard owner user ID
        folder:
          type: string
          description: Parent folder ID
        shares:
          type: array
          description: List of share permissions
          items:
            type: object
        created:
          type: string
          format: date-time
          description: Dashboard creation timestamp
        lastUpdated:
          type: string
          format: date-time
          description: Last update timestamp
        type:
          type: string
          description: Dashboard type identifier
    CreateDashboardRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          description: Dashboard title
        desc:
          type: string
          description: Dashboard description
    User:
      type: object
      properties:
        _id:
          type: string
          description: User unique identifier
        email:
          type: string
          description: User email address
        firstName:
          type: string
          description: User first name
        lastName:
          type: string
          description: User last name
        userName:
          type: string
          description: Username for login
        role:
          type: string
          description: User role (viewer, designer, analyst, dataDesigner, admin)
        groups:
          type: array
          description: Groups the user belongs to
          items:
            type: string
        active:
          type: boolean
          description: Whether the user account is active
        created:
          type: string
          format: date-time
        lastLogin:
          type: string
          format: date-time
    CreateUserRequest:
      type: object
      required:
        - email
        - role
      properties:
        email:
          type: string
          description: User email address
        firstName:
          type: string
          description: User first name
        lastName:
          type: string
          description: User last name
        role:
          type: string
          description: User role assignment
        groups:
          type: array
          items:
            type: string
          description: Groups to assign the user to
    Group:
      type: object
      properties:
        _id:
          type: string
          description: Group unique identifier
        name:
          type: string
          description: Group display name
        description:
          type: string
          description: Group description
        created:
          type: string
          format: date-time
    CreateGroupRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Group name
        description:
          type: string
          description: Group description
    Elasticube:
      type: object
      properties:
        title:
          type: string
          description: Elasticube name
        status:
          type: string
          description: Current build status
        server:
          type: string
          description: Host server name
        address:
          type: string
          description: Server address
    DataSecurityRule:
      type: object
      properties:
        column:
          type: string
          description: Column to apply the security rule to
        table:
          type: string
          description: Table containing the column
        datatype:
          type: string
          description: Data type of the column
        members:
          type: array
          description: Users and groups this rule applies to
          items:
            type: object
        exclusionary:
          type: boolean
          description: Whether the rule is exclusionary