openapi: 3.0.3
info:
  title: Kanban API
  version: 1.2.3
  description: |
    The Kanban API provides board management and data query capabilities for epilot's Kanban view feature.

    Kanban boards allow epilot users to visualize and manage workflow tasks, opportunities, and other entities in a column-based layout.

    Key capabilities:
    - Create, read, update, and delete Kanban boards with configurable swimlanes and filters
    - Share boards with individual users or across the entire organization
    - Set and clear the organization-level default board
    - Query and autocomplete Flows data to populate Kanban cards with live entity data
tags:
- name: Kanban
  description: |
    Endpoints for managing Kanban boards. Boards consist of swimlanes, each with configurable filters to display matching workflow tasks or entities.
    Boards can be owned by individual users and optionally shared with other users or the whole organization.
- name: Query
  description: |
    Endpoints for querying and autocompleting Flows data used to populate Kanban cards.
    These endpoints support filtering, sorting, and pagination of the underlying workflow task dataset.
security:
- EpilotAuth: []
- EpilotOrg: []
paths:
  /v1/kanban/board:
    post:
      operationId: createKanbanBoard
      summary: createKanbanBoard
      description: |
        Creates a new Kanban board with the provided configuration.

        A board must have a title and a config containing at least one dataset. Swimlanes and filters can be configured to display specific subsets of workflow tasks or entities.
      tags:
      - Kanban
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Board'
            example:
              title: My Sales Board
              description: Track open opportunities
              config:
                dataset: workflow_tasks_overview
                swimlanes:
                - id: lane-1
                  title: New
                  position: 1
                  filter:
                    items:
                    - key: status
                      operator: EQUALS
                      value: new
                      data_type: string
                    combination: AND
                card_config:
                  fields:
                  - assignee
                  - due_date
      responses:
        '200':
          description: Successfully created board
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Board'
              example:
                id: board-abc123
                title: My Sales Board
                description: Track open opportunities
                org_id: '728224'
                created_by: user-1
                created_at: '2024-01-15T09:00:00.000Z'
                updated_at: '2024-01-15T09:00:00.000Z'
                config:
                  dataset: workflow_tasks_overview
                  swimlanes: []
        '400':
          description: Bad request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/kanban/boards:
    get:
      operationId: getKanbanBoards
      summary: getKanbanBoards
      description: |
        Returns a list of all Kanban boards accessible to the authenticated user.

        Use the `filter` query parameter to narrow results to boards the user owns (`owned`) or boards shared with them (`shared`). When omitted, all accessible boards are returned.
      tags:
      - Kanban
      parameters:
      - name: filter
        in: query
        description: Filter boards by ownership type. If not provided, returns all accessible boards.
        schema:
          type: string
          enum:
          - owned
          - shared
        required: false
      responses:
        '200':
          description: Successfully retrieved boards
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BoardSummary'
              example:
              - id: board-abc123
                title: My Sales Board
                description: Track open opportunities
                org_id: '728224'
                created_by: user-1
                created_at: '2024-01-15T09:00:00.000Z'
                updated_at: '2024-01-15T09:00:00.000Z'
                shared_with_org: false
                owners:
                - user-1
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/kanban/board/{boardId}:
    get:
      operationId: getKanbanBoard
      summary: getKanbanBoard
      description: |
        Retrieves a Kanban board by ID, including its full configuration (swimlanes, filters, sorting, card fields).

        Use `"default"` as the `boardId` to retrieve the organization's currently configured default board.
      tags:
      - Kanban
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: string
        description: |
          The board ID, or "default" to get the organization's default board.
        example: board-123
      responses:
        '200':
          description: Successfully retrieved board
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Board'
              example:
                id: board-abc123
                title: My Sales Board
                description: Track open opportunities
                org_id: '728224'
                created_by: user-1
                created_at: '2024-01-15T09:00:00.000Z'
                updated_at: '2024-01-15T09:00:00.000Z'
                shared_with_org: false
                owners:
                - user-1
                config:
                  dataset: workflow_tasks_overview
                  swimlanes:
                  - id: lane-1
                    title: New
                    position: 1
                    filter:
                      items:
                      - key: status
                        operator: EQUALS
                        value: new
                        data_type: string
                      combination: AND
                  card_config:
                    fields:
                    - assignee
                    - due_date
                  sorting:
                    field: created_at
                    direction: desc
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Board not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateKanbanBoard
      summary: updateKanbanBoard
      description: |
        Fully replaces the configuration of an existing Kanban board by ID.

        All board fields (title, config, swimlanes, filters) must be provided. Use PATCH for partial updates.
      tags:
      - Kanban
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the board to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Board'
      responses:
        '200':
          description: Successfully updated board
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Board'
              example:
                id: board-abc123
                title: Updated Sales Board
                description: Track open opportunities
                org_id: '728224'
                created_by: user-1
                created_at: '2024-01-15T09:00:00.000Z'
                updated_at: '2024-01-16T10:30:00.000Z'
                shared_with_org: false
                owners:
                - user-1
                config:
                  dataset: workflow_tasks_overview
                  swimlanes: []
        '400':
          description: Bad request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Board not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchKanbanBoard
      summary: patchKanbanBoard
      description: |
        Partially updates fields of an existing Kanban board by ID.

        Only the fields provided in the request body will be updated. Useful for updating sharing settings, ownership, or title without replacing the full board configuration.
      tags:
      - Kanban
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the board to patch.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: Board 1
                description:
                  type: string
                  example: Board description
                shared_with:
                  type: array
                  items:
                    type: string
                  description: Array of user IDs to share the board with
                shared_with_org:
                  type: boolean
                  description: Whether the board is shared with the entire organization
                owners:
                  type: array
                  items:
                    type: string
                  description: Array of user IDs who have full ownership rights for this board (view, edit, delete)
            example:
              title: Updated Board Title
              shared_with_org: true
              owners:
              - user-1
              - user-2
      responses:
        '200':
          description: Successfully patched board
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Board'
              example:
                id: board-abc123
                title: Updated Board Title
                org_id: '728224'
                created_by: user-1
                created_at: '2024-01-15T09:00:00.000Z'
                updated_at: '2024-01-16T12:00:00.000Z'
                shared_with_org: true
                owners:
                - user-1
                - user-2
                config:
                  dataset: workflow_tasks_overview
                  swimlanes: []
        '400':
          description: Bad request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Board not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteKanbanBoard
      summary: deleteKanbanBoard
      description: Permanently deletes a Kanban board by ID. This action is irreversible.
      tags:
      - Kanban
      parameters:
      - name: boardId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the board to delete.
      responses:
        '200':
          description: Successfully deleted board
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Board not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/kanban/org/default-board:
    put:
      operationId: setDefaultKanbanBoard
      summary: setDefaultKanbanBoard
      description: |
        Sets a Kanban board as the default board for the organization.

        The default board is shown to users who access the Kanban view without specifying a specific board ID.
        Pass `boardId` as a query parameter to identify the board to set as default.
      tags:
      - Kanban
      parameters:
      - name: boardId
        in: query
        required: true
        schema:
          type: string
        description: The ID of the board to set as default
        example: board-abc123
      responses:
        '200':
          description: Successfully set default board
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  default_board_id:
                    type: string
              example:
                message: Default board set successfully
                default_board_id: board-abc123
        '400':
          description: Bad request - Invalid input data or boardId missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Board not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: clearDefaultKanbanBoard
      summary: clearDefaultKanbanBoard
      description: |
        Removes the default board configuration for the organization.

        After calling this endpoint, `getKanbanBoard` with `boardId=default` will return a 404 until a new default is set.
      tags:
      - Kanban
      responses:
        '200':
          description: Successfully cleared default board
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  default_board_id:
                    type: string
                    nullable: true
              example:
                message: Default board cleared successfully
                default_board_id: null
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/kanban/query/flows:autocomplete:
    get:
      operationId: flowsAutocomplete
      summary: flowsAutocomplete
      description: |
        Returns autocomplete suggestions for a given attribute in the Flows dataset.

        Use this endpoint to power filter dropdowns and search inputs in the Kanban board configuration UI.
        The `attribute` parameter specifies which field to autocomplete (e.g. `name`, `assignee`, `status`).
        The optional `input` parameter filters results to those matching the typed prefix.
      tags:
      - Query
      parameters:
      - name: input
        in: query
        description: Typed input string to filter autocomplete suggestions
        schema:
          type: string
        example: John
      - name: attribute
        in: query
        description: The field name to autocomplete values for
        schema:
          type: string
          example: name
        required: true
      - name: size
        in: query
        description: Maximum number of results to return
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 250
      - name: from
        in: query
        description: Starting offset for pagination
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        '200':
          description: Autocomplete results returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      anyOf:
                      - type: string
                      - type: boolean
                      - type: object
                        additionalProperties: true
                    example:
                    - value
                  hits:
                    type: number
                    description: Total number of matching items available
                    example: 42
                required:
                - results
                - hits
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/kanban/query/flows:execute:
    post:
      operationId: executeFlowsQuery
      summary: executeFlowsQuery
      description: |
        Executes a query against the Flows dataset and returns paginated results for use in Kanban card rendering.

        Supports filtering with complex AND/OR logic, sorting, and offset-based pagination.
        Results are used to populate Kanban swimlane cards with real-time workflow task data.
      tags:
      - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowsQueryRequest'
            example:
              filters:
                items:
                - key: status
                  operator: IS_ONE_OF
                  value:
                  - open
                  - in_progress
                  data_type: string
                combination: AND
              sorting:
                field: created_at
                direction: desc
              from: 0
              size: 10
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowsQueryResult'
              example:
                results:
                - id: flow-001
                  status: open
                  assignee: user-1
                  created_at: '2024-01-10T08:00:00.000Z'
                hits: 42
                page_number: 1
                page_size: 10
                total_pages: 5
        '400':
          description: Bad request - Invalid filter or sort configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    EpilotAuth:
      type: http
      scheme: bearer
      description: Authorization header with epilot OAuth2 bearer token
      bearerFormat: JWT
    EpilotOrg:
      description: Overrides the target organization to allow shared tenant access
      name: x-epilot-org-id
      in: header
      type: apiKey
  schemas:
    Error:
      type: object
      description: Standard error response
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Board not found
        status:
          type: integer
          description: HTTP status code
          example: 404
    BoardSummary:
      type: object
      description: Summary representation of a Kanban board, returned in list responses. Does not include swimlane and filter configuration details.
      properties:
        id:
          type: string
        title:
          type: string
          example: Board 1
        description:
          type: string
          example: Board description
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          type: string
        org_id:
          type: string
        updated_by:
          type: string
        shared_with:
          type: array
          items:
            type: string
        shared_with_org:
          type: boolean
        owners:
          type: array
          items:
            type: string
          description: Array of user IDs who have full ownership rights for this board (view, edit, delete)
    Board:
      description: Full representation of a Kanban board, including swimlane layout, filter configuration, card display fields, and sorting options.
      allOf:
      - $ref: '#/components/schemas/BoardSummary'
      - type: object
        properties:
          config:
            type: object
            properties:
              dataset:
                type: string
                example: workflow_tasks_overview
              swimlanes:
                type: array
                items:
                  $ref: '#/components/schemas/Swimlane'
              card_config:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      type: string
                      example: assignee
              board_filter:
                $ref: '#/components/schemas/BoardFilter'
              sorting:
                $ref: '#/components/schemas/Sorting'
              group_by:
                $ref: '#/components/schemas/GroupBy'
              search_query:
                type: string
                example: task 1
        required:
        - title
        - config
    Swimlane:
      type: object
      description: A vertical column in a Kanban board that groups workflow tasks or entities matching its filter criteria. Each swimlane has an independent filter and a display position.
      properties:
        id:
          type: string
        title:
          type: string
          example: Swimlane 1
        position:
          type: number
          example: 1
        filter:
          $ref: '#/components/schemas/BoardFilter'
        title_chip_variant:
          type: string
          example: success
    Sorting:
      type: object
      description: Defines how query results should be sorted. Specify a field name and sort direction.
      properties:
        field:
          type: string
          example: created_at
        direction:
          type: string
          enum:
          - asc
          - desc
          default: asc
      required:
      - field
    GroupBy:
      type: object
      description: Defines how tasks should be grouped within each swimlane. Tasks with the same group value are returned adjacently in the result set.
      required:
      - field
      properties:
        field:
          type: string
          enum:
          - context_entity
          - phase
          - task
          description: Property to group tasks by within each swimlane
    BoardFilter:
      type: object
      description: A filter group containing one or more filter items or nested filter groups. Items are combined using the specified logical operator (AND/OR).
      properties:
        items:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/FilterItem'
            - $ref: '#/components/schemas/FilterGroup'
        combination:
          type: string
          enum:
          - AND
          - OR
          example: OR
      required:
      - items
      - combination
    FilterGroup:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FilterItem'
        combination:
          type: string
          enum:
          - AND
          - OR
          example: AND
      required:
      - items
      - combination
    FilterOperator:
      type: string
      enum:
      - EQUALS
      - NOT_EQUALS
      - EMPTY
      - NOT_EMPTY
      - CONTAINS
      - NOT_CONTAINS
      - IS_ONE_OF
      - IS_NONE_OF
      - GREATER_THAN
      - LESS_THAN
      - GREATER_THAN_OR_EQUAL
      - LESS_THAN_OR_EQUAL
      example: EQUALS
      description: The comparison operator for filtering
    DynamicDateValue:
      type: string
      enum:
      - TODAY
      - TOMORROW
      - YESTERDAY
      - IN_THE_FUTURE
      - IN_THE_PAST
      - THIS_WEEK
      - NEXT_WEEK
      - LAST_WEEK
      - THIS_MONTH
      - NEXT_MONTH
      - LAST_MONTH
      - TODAY_OR_EARLIER
      description: Dynamic date keywords that resolve to actual dates at runtime
    ValueType:
      anyOf:
      - type: string
        example: '100020'
      - $ref: '#/components/schemas/DynamicDateValue'
      - type: number
        example: 42
      - type: boolean
        example: true
      - type: array
        items:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/DynamicDateValue'
          - type: number
          - type: boolean
        example:
        - value1
        - value2
        - 123
        - true
      description: The value to compare against - can be a single value (string, number, boolean, or dynamic date) or an array of values
    FlowsQueryRequest:
      type: object
      description: Request payload for executing a query against the Flows dataset. Supports filter conditions, sorting, grouping, and offset-based pagination.
      properties:
        filters:
          $ref: '#/components/schemas/BoardFilter'
          description: Optional filter conditions to narrow the result set using AND/OR logic.
        sorting:
          $ref: '#/components/schemas/Sorting'
          description: Sort the results by a specific field and direction.
        group_by:
          $ref: '#/components/schemas/GroupBy'
          description: Group tasks by a shared property within each swimlane. Grouped tasks are returned adjacently in the result set.
        from:
          type: number
          default: 0
          description: Zero-based offset for pagination. Use with `size` to paginate through results.
          example: 0
        size:
          type: number
          default: 10
          description: Number of results to return per page.
          example: 10
    FlowsQueryResult:
      type: object
      description: Paginated result set returned from a Flows query. Each item in `results` is a workflow task record with dynamic fields depending on the dataset configuration.
      properties:
        results:
          type: array
          description: Array of matching workflow task records. Fields vary based on the dataset and card configuration.
          items:
            type: object
            additionalProperties: true
        hits:
          type: number
          description: Total number of records matching the query (across all pages).
          example: 42
        page_number:
          type: number
          description: Current page number (1-based).
          example: 1
        page_size:
          type: number
          description: Number of results per page (matches the `size` request parameter).
          example: 10
        total_pages:
          type: number
          description: Total number of available pages based on `hits` and `page_size`.
          example: 5
      additionalProperties: true
    FilterItem:
      type: object
      properties:
        key:
          type: string
          example: assignee
          description: The field key to filter on
        operator:
          $ref: '#/components/schemas/FilterOperator'
        value:
          $ref: '#/components/schemas/ValueType'
        data_type:
          type: string
          enum:
          - string
          - number
          - boolean
          - date
          example: string
          description: The data type of the field
      required:
      - key
      - operator
servers:
- url: https://kanban.sls.epilot.io

