openapi: 3.0.3
info:
  title: Knowi Management API
  summary: Manage Knowi users, groups, and dashboards programmatically.
  description: >-
    The Knowi Management API enables programmatic administration of a Knowi
    workspace including users, groups, and dashboards. It uses OAuth 2.0 bearer
    tokens for authentication and supports automation of provisioning,
    permission management, and embedded analytics workflows.
  version: '1.0'
  contact:
    name: Knowi Support
    url: https://www.knowi.com/support
    email: support@knowi.com
servers:
  - url: https://knowi.com/api/1.0
    description: Knowi Management API production server
tags:
  - name: Authentication
    description: Obtain and revoke bearer tokens.
  - name: Users
    description: Manage workspace users.
  - name: Groups
    description: Manage user groups.
  - name: Dashboards
    description: Manage dashboards and shared URLs.
paths:
  /login:
    post:
      tags:
        - Authentication
      summary: Obtain access token
      description: Exchange credentials for a bearer token used to authorize Management API calls.
      operationId: login
      responses:
        '200':
          description: Authenticated, token returned.
        '401':
          description: Invalid credentials.
  /logout:
    delete:
      tags:
        - Authentication
      summary: Revoke access token
      description: Destroy the current bearer token, ending the session.
      operationId: logout
      responses:
        '200':
          description: Token revoked.
        '401':
          description: Token already invalid or expired.
  /users:
    get:
      tags:
        - Users
      summary: List users
      description: List all users in the workspace.
      operationId: listUsers
      responses:
        '200':
          description: A list of users.
    post:
      tags:
        - Users
      summary: Create user
      description: Create a new workspace user.
      operationId: createUser
      responses:
        '200':
          description: User created.
        '409':
          description: User already exists.
  /users/search:
    get:
      tags:
        - Users
      summary: Search user
      description: Search for a user by username.
      operationId: searchUser
      parameters:
        - name: username
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Matching user.
  /users/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Users
      summary: Get user
      description: Retrieve a specific user by ID.
      operationId: getUser
      responses:
        '200':
          description: User details.
    put:
      tags:
        - Users
      summary: Update user
      description: Update an existing user's information.
      operationId: updateUser
      responses:
        '200':
          description: User updated.
    delete:
      tags:
        - Users
      summary: Delete user
      description: Delete a user from the workspace.
      operationId: deleteUser
      responses:
        '200':
          description: User deleted.
  /users/{userId}/moveAssets:
    put:
      tags:
        - Users
      summary: Move user assets
      description: Transfer ownership of a user's assets to another user.
      operationId: moveUserAssets
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Assets transferred.
  /users/shareableEntities:
    get:
      tags:
        - Users
      summary: List shareable entities
      description: List users and groups available for sharing dashboards and widgets with.
      operationId: listShareableEntities
      responses:
        '200':
          description: Shareable entities.
  /groups:
    get:
      tags:
        - Groups
      summary: List groups
      description: List all groups in the workspace.
      operationId: listGroups
      responses:
        '200':
          description: A list of groups.
    post:
      tags:
        - Groups
      summary: Create group
      description: Create a new group.
      operationId: createGroup
      responses:
        '200':
          description: Group created.
  /groups/{groupId}:
    parameters:
      - name: groupId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Groups
      summary: Get group
      description: Retrieve a group by ID.
      operationId: getGroup
      responses:
        '200':
          description: Group details.
    put:
      tags:
        - Groups
      summary: Update group
      description: Update a group.
      operationId: updateGroup
      responses:
        '200':
          description: Group updated.
    delete:
      tags:
        - Groups
      summary: Delete group
      description: Delete a group.
      operationId: deleteGroup
      responses:
        '200':
          description: Group deleted.
  /users/{userId}/groups:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Groups
      summary: List user groups
      description: List groups associated with a specific user.
      operationId: listUserGroups
      responses:
        '200':
          description: A list of user groups.
    post:
      tags:
        - Groups
      summary: Create group for user
      description: Create a group associated with the specified user.
      operationId: createUserGroup
      responses:
        '200':
          description: Group created for user.
  /users/{userId}/groups/{groupId}:
    delete:
      tags:
        - Groups
      summary: Remove group from user
      description: Remove a group association from a user.
      operationId: removeUserGroup
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: groupId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Group association removed.
  /dashboards:
    get:
      tags:
        - Dashboards
      summary: List dashboards
      description: List all dashboards in the workspace.
      operationId: listDashboards
      responses:
        '200':
          description: A list of dashboards.
  /dashboards/{objectId}:
    get:
      tags:
        - Dashboards
      summary: Get dashboard
      description: Retrieve a dashboard by object ID.
      operationId: getDashboard
      parameters:
        - name: objectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dashboard details.
  /dashboards/{objectId}/share:
    get:
      tags:
        - Dashboards
      summary: Get dashboard share info
      description: Retrieve sharing information for a dashboard.
      operationId: getDashboardShare
      parameters:
        - name: objectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Share information.
  /dashboards/{objectId}/share/url:
    post:
      tags:
        - Dashboards
      summary: Generate share URL
      description: Generate a public share URL for the dashboard.
      operationId: generateShareUrl
      parameters:
        - name: objectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Share URL generated.
  /dashboards/{objectId}/share/url/secure:
    post:
      tags:
        - Dashboards
      summary: Generate secure share URL
      description: Generate a secure share URL with token-based access for the dashboard.
      operationId: generateSecureShareUrl
      parameters:
        - name: objectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Secure share URL generated.
  /dashboards/{objectId}/share/url/secure/hash:
    post:
      tags:
        - Dashboards
      summary: Generate secure share hash
      description: Generate a secure hash for embedding the dashboard with row-level filters.
      operationId: generateSecureShareHash
      parameters:
        - name: objectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Secure hash generated.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuth: []