focalboard/server/swagger/swagger.yml

basePath: /api/v2
consumes:
    - application/json
definitions:
    Block:
        description: Block is the basic data unit
        x-go-package: github.com/mattermost/focalboard/server/model
    BlockPatch:
        description: BlockPatch is a patch for modify blocks
        x-go-package: github.com/mattermost/focalboard/server/model
    BlockPatchBatch:
        description: BlockPatchBatch is a batch of IDs and patches for modify blocks
        x-go-package: github.com/mattermost/focalboard/server/model
    Board:
        description: Board groups a set of blocks and its layout
        x-go-package: github.com/mattermost/focalboard/server/model
    BoardInsight:
        description: BoardInsight gives insight into activities in a Board
        x-go-package: github.com/mattermost/focalboard/server/model
    BoardMember:
        description: BoardMember stores the information of the membership of a user on a board
        x-go-package: github.com/mattermost/focalboard/server/model
    BoardMemberHistoryEntry:
        description: BoardMemberHistoryEntry stores the information of the membership of a user on a board
        x-go-package: github.com/mattermost/focalboard/server/model
    BoardMetadata:
        description: BoardMetadata contains metadata for a Board
        x-go-package: github.com/mattermost/focalboard/server/model
    BoardPatch:
        description: BoardPatch is a patch for modify boards
        x-go-package: github.com/mattermost/focalboard/server/model
    BoardsAndBlocks:
        description: |-
            BoardsAndBlocks is used to operate over boards and blocks at the
            same time
        x-go-package: github.com/mattermost/focalboard/server/model
    BoardsCloudLimits:
        description: |-
            BoardsCloudLimits is the representation of the limits for the
            Boards server
        x-go-package: github.com/mattermost/focalboard/server/model
    BoardsStatistics:
        description: BoardsStatistics is the representation of the statistics for the Boards server
        x-go-package: github.com/mattermost/focalboard/server/model
    Card:
        title: Card represents a group of content blocks and properties.
        x-go-package: github.com/mattermost/focalboard/server/model
    CardPatch:
        description: CardPatch is a patch for modifying cards
        x-go-package: github.com/mattermost/focalboard/server/model
    Category:
        description: Category is a board category
        x-go-package: github.com/mattermost/focalboard/server/model
    CategoryBoards:
        description: CategoryBoards is a board category and associated boards
        x-go-package: github.com/mattermost/focalboard/server/model
    ChangePasswordRequest:
        description: ChangePasswordRequest is a user password change request
        x-go-package: github.com/mattermost/focalboard/server/model
    ClientConfig:
        description: ClientConfig is the client configuration
        x-go-package: github.com/mattermost/focalboard/server/model
    DeleteBoardsAndBlocks:
        description: |-
            DeleteBoardsAndBlocks is used to list the boards and blocks to
            delete on a request
        x-go-package: github.com/mattermost/focalboard/server/model
    ErrorResponse:
        description: ErrorResponse is an error response
        x-go-package: github.com/mattermost/focalboard/server/model
    FileUploadResponse:
        description: FileUploadResponse is the response to a file upload
        x-go-package: github.com/mattermost/focalboard/server/api
    LoginRequest:
        description: LoginRequest is a login request
        x-go-package: github.com/mattermost/focalboard/server/model
    LoginResponse:
        description: LoginResponse is a login response
        x-go-package: github.com/mattermost/focalboard/server/model
    NotificationHint:
        description: |-
            NotificationHint provides a hint that a block has been modified and has subscribers that
            should be notified.
        x-go-package: github.com/mattermost/focalboard/server/model
    PatchBoardsAndBlocks:
        description: |-
            PatchBoardsAndBlocks is used to patch multiple boards and blocks on
            a single request
        x-go-package: github.com/mattermost/focalboard/server/model
    RegisterRequest:
        description: RegisterRequest is a user registration request
        x-go-package: github.com/mattermost/focalboard/server/model
    Sharing:
        description: Sharing is sharing information for a root block
        x-go-package: github.com/mattermost/focalboard/server/model
    Subscriber:
        description: Subscriber is an entity (e.g. user, channel) that can subscribe to events from boards, cards, etc
        x-go-package: github.com/mattermost/focalboard/server/model
    Subscription:
        title: Subscription is a subscription to a board, card, etc, for a user or channel.
        x-go-package: github.com/mattermost/focalboard/server/model
    Team:
        description: Team is information global to a team
        x-go-package: github.com/mattermost/focalboard/server/model
    User:
        description: User is a user
        x-go-package: github.com/mattermost/focalboard/server/model
    UserPreferencesPatch:
        description: UserPreferencesPatch is a user property patch
        x-go-package: github.com/mattermost/focalboard/server/model
host: localhost
info:
    contact:
        email: api@focalboard.com
        name: Focalboard
        url: https://www.focalboard.com
    description: Focalboard Server
    license:
        name: Custom
        url: https://github.com/mattermost/focalboard/blob/main/LICENSE.txt
    title: Focalboard Server
    version: 2.0.0
paths:
    /api/v2/teams/{teamID}/notifyadminupgrade:
        get:
            operationId: handleNotifyAdminUpgrade
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Notifies admins for upgrade request.
    /boards:
        post:
            description: Creates a new board
            operationId: createBoard
            parameters:
                - description: the board to create
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/Board'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Board'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards-and-blocks:
        delete:
            description: Deletes boards and blocks
            operationId: deleteBoardsAndBlocks
            parameters:
                - description: the boards and blocks to delete
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/DeleteBoardsAndBlocks'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        patch:
            description: Patches a set of related boards and blocks
            operationId: patchBoardsAndBlocks
            parameters:
                - description: the patches for the boards and blocks
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/PatchBoardsAndBlocks'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardsAndBlocks'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        post:
            description: Creates new boards and blocks
            operationId: insertBoardsAndBlocks
            parameters:
                - description: the boards and blocks to create
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/BoardsAndBlocks'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardsAndBlocks'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}:
        delete:
            description: Removes a board
            operationId: deleteBoard
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        get:
            description: Returns a board
            operationId: getBoard
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Board'
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        patch:
            description: Partially updates a board
            operationId: patchBoard
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: board patch to apply
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/BoardPatch'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Board'
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/archive/export:
        get:
            operationId: archiveExportBoard
            parameters:
                - description: Id of board to export
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Exports an archive of all blocks for one boards.
    /boards/{boardID}/blocks:
        get:
            description: Returns blocks
            operationId: getBlocks
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: ID of parent block, omit to specify all blocks
                  in: query
                  name: parent_id
                  type: string
                - description: Type of blocks to return, omit to specify all types
                  in: query
                  name: type
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Block'
                        type: array
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        post:
            description: |-
                Insert blocks. The specified IDs will only be used to link
                blocks with existing ones, the rest will be replaced by server
                generated IDs
            operationId: updateBlocks
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: Disables notifications (for bulk inserting)
                  in: query
                  name: disable_notify
                  type: bool
                - description: array of blocks to insert or update
                  in: body
                  name: Body
                  required: true
                  schema:
                    items:
                        $ref: '#/definitions/Block'
                    type: array
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Block'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/blocks/:
        patch:
            description: Partially updates batch of blocks
            operationId: patchBlocks
            parameters:
                - description: Workspace ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: Disables notifications (for bulk patching)
                  in: query
                  name: disable_notify
                  type: bool
                - description: block Ids and block patches to apply
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/BlockPatchBatch'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/blocks/{blockID}:
        delete:
            description: Deletes a block
            operationId: deleteBlock
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: ID of block to delete
                  in: path
                  name: blockID
                  required: true
                  type: string
                - description: Disables notifications (for bulk deletion)
                  in: query
                  name: disable_notify
                  type: bool
            produces:
                - application/json
            responses:
                "200":
                    description: success
                "404":
                    description: block not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        patch:
            description: Partially updates a block
            operationId: patchBlock
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: ID of block to patch
                  in: path
                  name: blockID
                  required: true
                  type: string
                - description: Disables notifications (for bulk patching)
                  in: query
                  name: disable_notify
                  type: bool
                - description: block patch to apply
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/BlockPatch'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                "404":
                    description: block not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/blocks/{blockID}/duplicate:
        post:
            description: Returns the new created blocks
            operationId: duplicateBlock
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: Block ID
                  in: path
                  name: blockID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Block'
                        type: array
                "404":
                    description: board or block not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/blocks/{blockID}/undelete:
        post:
            description: Undeletes a block
            operationId: undeleteBlock
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: ID of block to undelete
                  in: path
                  name: blockID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BlockPatch'
                "404":
                    description: block not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/cards:
        get:
            operationId: getCards
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: The page to select (default=0)
                  in: query
                  name: page
                  type: integer
                - description: Number of cards to return per page(default=100)
                  in: query
                  name: per_page
                  type: integer
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Card'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Fetches cards for the specified board.
        post:
            operationId: createCard
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: the card to create
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/Card'
                - description: Disables notifications (for bulk data inserting)
                  in: query
                  name: disable_notify
                  type: bool
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Card'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Creates a new card for the specified board.
    /boards/{boardID}/duplicate:
        post:
            description: Returns the new created board and all the blocks
            operationId: duplicateBoard
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardsAndBlocks'
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/join:
        post:
            description: Become a member of a board
            operationId: joinBoard
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardMember'
                "403":
                    description: access denied
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/leave:
        post:
            description: Remove your own membership from a board
            operationId: leaveBoard
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                "403":
                    description: access denied
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/members:
        get:
            description: Returns the members of the board
            operationId: getMembersForBoard
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/BoardMember'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        post:
            description: Adds a new member to a board
            operationId: addMember
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: membership to replace the current one with
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/BoardMember'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardMember'
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/members/{userID}:
        delete:
            description: Deletes a member from a board
            operationId: deleteMember
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: User ID
                  in: path
                  name: userID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        put:
            description: Updates a board member
            operationId: updateMember
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: User ID
                  in: path
                  name: userID
                  required: true
                  type: string
                - description: membership to replace the current one with
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/BoardMember'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardMember'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/metadata:
        get:
            description: Returns a board's metadata
            operationId: getBoardMetadata
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardMetadata'
                "404":
                    description: board not found
                "501":
                    description: required license not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/sharing:
        get:
            description: Returns sharing information for a board
            operationId: getSharing
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Sharing'
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        post:
            description: Sets sharing information for a board
            operationId: postSharing
            parameters:
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: sharing information for a root block
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/Sharing'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/{boardID}/undelete:
        post:
            description: Undeletes a board
            operationId: undeleteBoard
            parameters:
                - description: ID of board to undelete
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /boards/search:
        get:
            description: Returns the boards that match with a search term
            operationId: searchAllBoards
            parameters:
                - description: The search term. Must have at least one character
                  in: query
                  name: q
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Board'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /cards/{cardID}:
        get:
            operationId: getCard
            parameters:
                - description: Card ID
                  in: path
                  name: cardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Card'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Fetches the specified card.
    /cards/{cardID}/cards:
        patch:
            operationId: patchCard
            parameters:
                - description: Card ID
                  in: path
                  name: cardID
                  required: true
                  type: string
                - description: the card patch
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/CardPatch'
                - description: Disables notifications (for bulk data patching)
                  in: query
                  name: disable_notify
                  type: bool
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Card'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Patches the specified card.
    /clientConfig:
        get:
            description: Returns the client configuration
            operationId: getClientConfig
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/ClientConfig'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
    /files/teams/{teamID}/{boardID}/{filename}:
        get:
            description: Returns the contents of an uploaded file
            operationId: getFile
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: name of the file
                  in: path
                  name: filename
                  required: true
                  type: string
            produces:
                - application/json
                - image/jpg
                - image/png
                - image/gif
            responses:
                "200":
                    description: success
                "404":
                    description: file not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /hello:
        get:
            operationId: hello
            produces:
                - text/plain
            responses:
                "200":
                    description: success
            summary: Responds with `Hello` if the web service is running.
    /limits:
        get:
            operationId: cloudLimits
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardsCloudLimits'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Fetches the cloud limits of the server.
    /login:
        post:
            description: Login user
            operationId: login
            parameters:
                - description: Login request
                  in: body
                  name: body
                  required: true
                  schema:
                    $ref: '#/definitions/LoginRequest'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/LoginResponse'
                "401":
                    description: invalid login
                    schema:
                        $ref: '#/definitions/ErrorResponse'
                "500":
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
    /logout:
        post:
            description: Logout user
            operationId: logout
            produces:
                - application/json
            responses:
                "200":
                    description: success
                "500":
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /ping:
        get:
            operationId: ping
            produces:
                - application/json
            responses:
                "200":
                    description: success
            summary: Responds with server metadata if the web service is running.
    /register:
        post:
            description: Register new user
            operationId: register
            parameters:
                - description: Register request
                  in: body
                  name: body
                  required: true
                  schema:
                    $ref: '#/definitions/RegisterRequest'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                "401":
                    description: invalid registration token
                "500":
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
    /statistics:
        get:
            operationId: handleStatistics
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/BoardStatistics'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Fetches the statistic  of the server.
    /subscriptions:
        post:
            operationId: createSubscription
            parameters:
                - description: subscription definition
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/Subscription'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/User'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Creates a subscription to a block for a user. The user will receive change notifications for the block.
    /subscriptions/{blockID}/{subscriberID}:
        delete:
            operationId: deleteSubscription
            parameters:
                - description: Block ID
                  in: path
                  name: blockID
                  required: true
                  type: string
                - description: Subscriber ID
                  in: path
                  name: subscriberID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Deletes a subscription a user has for a a block. The user will no longer receive change notifications for the block.
    /subscriptions/{subscriberID}:
        get:
            operationId: getSubscriptions
            parameters:
                - description: Subscriber ID
                  in: path
                  name: subscriberID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/User'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Gets subscriptions for a user.
    /team/{teamID}/onboard:
        post:
            operationId: onboard
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        properties:
                            boardID:
                                description: Board ID
                                type: string
                            teamID:
                                description: Team ID
                                type: string
                        type: object
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Onboards a user on Boards.
    /teams:
        get:
            description: Returns information of all the teams
            operationId: getTeams
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Team'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}:
        get:
            description: Returns information of the root team
            operationId: getTeam
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Team'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/archive/export:
        get:
            operationId: archiveExportTeam
            parameters:
                - description: Id of team
                  in: path
                  name: teamID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Exports an archive of all blocks for all the boards in a team.
    /teams/{teamID}/archive/import:
        post:
            consumes:
                - multipart/form-data
            operationId: archiveImport
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: archive file to import
                  in: formData
                  name: file
                  required: true
                  type: file
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
            summary: Import an archive of boards.
    /teams/{teamID}/boards:
        get:
            description: Returns team boards
            operationId: getBoards
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Board'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/boards/{boardID}/files:
        post:
            consumes:
                - multipart/form-data
            description: Upload a binary file, attached to a root block
            operationId: uploadFile
            parameters:
                - description: ID of the team
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
                - description: The file to upload
                  in: formData
                  name: uploaded file
                  type: file
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/FileUploadResponse'
                "404":
                    description: board not found
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/boards/insights:
        get:
            description: Returns team boards insights
            operationId: handleTeamBoardsInsights
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: duration of data to calculate insights for
                  in: query
                  name: time_range
                  required: true
                  type: string
                - description: page offset for top boards
                  in: query
                  name: page
                  required: true
                  type: string
                - description: limit for boards in a page.
                  in: query
                  name: per_page
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/BoardInsight'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/boards/search:
        get:
            description: Returns the boards that match with a search term in the team
            operationId: searchBoards
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: The search term. Must have at least one character
                  in: query
                  name: q
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Board'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/boards/search/linkable:
        get:
            description: |-
                Returns the boards that match with a search term in the team and the
                user has permission to manage members
            operationId: searchLinkableBoards
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: The search term. Must have at least one character
                  in: query
                  name: q
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Board'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/categories:
        get:
            description: Gets the user's board categories
            operationId: getUserCategoryBoards
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/CategoryBoards'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        post:
            description: Create a category for boards
            operationId: createCategory
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: category to create
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/Category'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Category'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/categories/{categoryID}:
        delete:
            description: Delete a category
            operationId: deleteCategory
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: Category ID
                  in: path
                  name: categoryID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
        put:
            description: Create a category for boards
            operationId: updateCategory
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: Category ID
                  in: path
                  name: categoryID
                  required: true
                  type: string
                - description: category to update
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/Category'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Category'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/categories/{categoryID}/boards/{boardID}:
        post:
            description: Set the category of a board
            operationId: updateCategoryBoard
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: Category ID
                  in: path
                  name: categoryID
                  required: true
                  type: string
                - description: Board ID
                  in: path
                  name: boardID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/channels:
        get:
            description: Returns the user available channels
            operationId: searchMyChannels
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: string to filter channels list
                  in: query
                  name: search
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Channel'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/channels/{channelID}:
        get:
            description: Returns the requested channel
            operationId: getChannel
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: Channel ID
                  in: path
                  name: channelID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Channel'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/regenerate_signup_token:
        post:
            description: Regenerates the signup token for the root team
            operationId: regenerateSignupToken
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/templates:
        get:
            description: Returns team templates
            operationId: getTemplates
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/Board'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /teams/{teamID}/users:
        get:
            description: Returns team users
            operationId: getTeamUsers
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: string to filter users list
                  in: query
                  name: search
                  type: string
                - description: exclude bot users
                  in: query
                  name: exclude_bots
                  type: boolean
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/User'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /users:
        post:
            description: Returns a user[]
            operationId: getUsersList
            parameters:
                - description: User ID
                  in: path
                  name: userID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/User'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /users/{userID}:
        get:
            description: Returns a user
            operationId: getUser
            parameters:
                - description: User ID
                  in: path
                  name: userID
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/User'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /users/{userID}/changepassword:
        post:
            description: Change a user's password
            operationId: changePassword
            parameters:
                - description: User ID
                  in: path
                  name: userID
                  required: true
                  type: string
                - description: Change password request
                  in: body
                  name: body
                  required: true
                  schema:
                    $ref: '#/definitions/ChangePasswordRequest'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                "400":
                    description: invalid request
                    schema:
                        $ref: '#/definitions/ErrorResponse'
                "500":
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /users/{userID}/config:
        patch:
            description: Updates user config
            operationId: updateUserConfig
            parameters:
                - description: User ID
                  in: path
                  name: userID
                  required: true
                  type: string
                - description: User config patch to apply
                  in: body
                  name: Body
                  required: true
                  schema:
                    $ref: '#/definitions/UserPreferencesPatch'
            produces:
                - application/json
            responses:
                "200":
                    description: success
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /users/me:
        get:
            description: Returns the currently logged-in user
            operationId: getMe
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/User'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /users/me/boards/insights:
        get:
            description: Returns user boards insights
            operationId: getUserBoardsInsights
            parameters:
                - description: Team ID
                  in: path
                  name: teamID
                  required: true
                  type: string
                - description: duration of data to calculate insights for
                  in: query
                  name: time_range
                  required: true
                  type: string
                - description: page offset for top boards
                  in: query
                  name: page
                  required: true
                  type: string
                - description: limit for boards in a page.
                  in: query
                  name: per_page
                  required: true
                  type: string
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/BoardInsight'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /users/me/config:
        get:
            description: Returns an array of user preferences
            operationId: getUserConfig
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        $ref: '#/definitions/Preferences'
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
    /users/me/memberships:
        get:
            description: Returns the currently users board memberships
            operationId: getMyMemberships
            produces:
                - application/json
            responses:
                "200":
                    description: success
                    schema:
                        items:
                            $ref: '#/definitions/BoardMember'
                        type: array
                default:
                    description: internal error
                    schema:
                        $ref: '#/definitions/ErrorResponse'
            security:
                - BearerAuth: []
produces:
    - application/json
schemes:
    - http
    - https
securityDefinitions:
    BearerAuth:
        description: 'Pass session token using Bearer authentication, e.g. set header "Authorization: Bearer <session token>"'
        in: header
        name: Authorization
        type: apiKey
swagger: "2.0"