basePath: /api/v1 consumes: - application/json definitions: Block: description: Block is the basic data unit properties: createAt: description: The creation time format: int64 type: integer x-go-name: CreateAt createdBy: description: The id for user who created this block type: string x-go-name: CreatedBy deleteAt: description: The deleted time. Set to indicate this block is deleted format: int64 type: integer x-go-name: DeleteAt fields: additionalProperties: type: object description: The block fields type: object x-go-name: Fields id: description: The id for this block type: string x-go-name: ID modifiedBy: description: The id for user who last modified this block type: string x-go-name: ModifiedBy parentId: description: The id for this block's parent block. Empty for root blocks type: string x-go-name: ParentID rootId: description: The id for this block's root block type: string x-go-name: RootID schema: description: The schema version of this block format: int64 type: integer x-go-name: Schema title: description: The display title type: string x-go-name: Title type: $ref: '#/definitions/BlockType' updateAt: description: The last modified time format: int64 type: integer x-go-name: UpdateAt workspaceId: description: The workspace id that the block belongs to type: string x-go-name: WorkspaceID required: - id - rootId - createdBy - modifiedBy - schema - type - createAt - updateAt - workspaceId type: object x-go-package: github.com/mattermost/focalboard/server/model BlockPatch: description: BlockPatch is a patch for modify blocks properties: deletedFields: description: The block removed fields items: type: string type: array x-go-name: DeletedFields parentId: description: The id for this block's parent block. Empty for root blocks type: string x-go-name: ParentID rootId: description: The id for this block's root block type: string x-go-name: RootID schema: description: The schema version of this block format: int64 type: integer x-go-name: Schema title: description: The display title type: string x-go-name: Title type: $ref: '#/definitions/BlockType' updatedFields: additionalProperties: type: object description: The block updated fields type: object x-go-name: UpdatedFields type: object x-go-package: github.com/mattermost/focalboard/server/model UserPropPatch: description: UserConfigPatch is a patch for user config properties: deletedFields: description: The config fields removed items: type: string type: array x-go-name: DeletedFields updatedFields: additionalProperties: type: object description: The updated config type: object x-go-name: UpdatedFields type: object x-go-package: github.com/mattermost/focalboard/server/model BlockPatchBatch: description: BlockPatchBatch is a batch of IDs and patches for modify blocks properties: block_ids: description: The id's for of the blocks to patch items: type: string type: array x-go-name: BlockIDs block_patches: description: The BlockPatches to be applied items: $ref: '#/definitions/BlockPatch' type: array x-go-name: BlockPatches type: object x-go-package: github.com/mattermost/focalboard/server/model BlockType: title: BlockType represents a block type. type: string x-go-package: github.com/mattermost/focalboard/server/model ChangePasswordRequest: description: ChangePasswordRequest is a user password change request properties: newPassword: description: New password type: string x-go-name: NewPassword oldPassword: description: Old password type: string x-go-name: OldPassword required: - oldPassword - newPassword type: object x-go-package: github.com/mattermost/focalboard/server/api ErrorResponse: description: ErrorResponse is an error response properties: error: description: The error message type: string x-go-name: Error errorCode: description: The error code format: int64 type: integer x-go-name: ErrorCode type: object x-go-package: github.com/mattermost/focalboard/server/model FileUploadResponse: description: FileUploadResponse is the response to a file upload properties: fileId: description: The FileID to retrieve the uploaded file type: string x-go-name: FileID required: - fileId type: object x-go-package: github.com/mattermost/focalboard/server/api LoginRequest: description: LoginRequest is a login request properties: email: description: If specified, login using email type: string x-go-name: Email password: description: Password type: string x-go-name: Password type: description: Type of login, currently must be set to "normal" type: string x-go-name: Type username: description: If specified, login using username type: string x-go-name: Username required: - type - password type: object x-go-package: github.com/mattermost/focalboard/server/api LoginResponse: description: LoginResponse is a login response properties: token: description: Session token type: string x-go-name: Token required: - token type: object x-go-package: github.com/mattermost/focalboard/server/api NotificationHint: description: |- NotificationHint provides a hint that a block has been modified and has subscribers that should be notified. properties: block_id: description: BlockID is id of the entity that was updated type: string x-go-name: BlockID block_type: $ref: '#/definitions/BlockType' create_at: description: CreatedAt is the timestamp this notification hint was created format: int64 type: integer x-go-name: CreateAt modified_by_id: description: ModifiedByID is the id of the user who made the block change type: string x-go-name: ModifiedByID notify_at: description: NotifyAt is the timestamp this notification should be scheduled format: int64 type: integer x-go-name: NotifyAt workspace_id: description: WorkspaceID is id of workspace the block belongs to type: string x-go-name: WorkspaceID required: - block_type - block_id - workspace_id - create_at - notify_at type: object x-go-package: github.com/mattermost/focalboard/server/model RegisterRequest: description: RegisterRequest is a user registration request properties: email: description: User's email type: string x-go-name: Email password: description: Password type: string x-go-name: Password token: description: Registration authorization token type: string x-go-name: Token username: description: User name type: string x-go-name: Username required: - username - email - password - token type: object x-go-package: github.com/mattermost/focalboard/server/api Sharing: description: Sharing is sharing information for a root block properties: enabled: description: Is sharing enabled type: boolean x-go-name: Enabled id: description: ID of the root block type: string x-go-name: ID modifiedBy: description: ID of the user who last modified this type: string x-go-name: ModifiedBy token: description: Access token type: string x-go-name: Token update_at: description: Updated time format: int64 type: integer x-go-name: UpdateAt required: - id - enabled - token - modifiedBy - update_at type: object 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 properties: notified_at: description: NotifiedAt is the timestamp this subscriber was last notified format: int64 type: integer x-go-name: NotifiedAt subscriber_id: description: SubscriberID is the id of the entity that is subscribing type: string x-go-name: SubscriberID subscriber_type: $ref: '#/definitions/SubscriberType' required: - subscriber_type - subscriber_id type: object x-go-package: github.com/mattermost/focalboard/server/model SubscriberType: type: string x-go-package: github.com/mattermost/focalboard/server/model Subscription: properties: blockId: description: BlockID is id of the entity being subscribed to type: string x-go-name: BlockID blockType: $ref: '#/definitions/BlockType' createAt: description: CreatedAt is the timestamp this subscription was created format: int64 type: integer x-go-name: CreateAt deleteAt: description: DeleteAt is the timestamp this subscription was deleted, or zero if not deleted format: int64 type: integer x-go-name: DeleteAt notifiedAt: description: NotifiedAt is the timestamp of the last notification sent for this subscription format: int64 type: integer x-go-name: NotifiedAt subscriberId: description: SubscriberID is the id of the entity that is subscribing type: string x-go-name: SubscriberID subscriberType: $ref: '#/definitions/SubscriberType' workspaceId: description: WorkspaceID is id of the workspace the block belongs to type: string x-go-name: WorkspaceID required: - blockType - blockId - workspaceId - subscriberType - subscriberId - notifiedAt - createAt - deleteAt title: Subscription is a subscription to a board, card, etc, for a user or channel. type: object x-go-package: github.com/mattermost/focalboard/server/model User: description: User is a user properties: create_at: description: Created time format: int64 type: integer x-go-name: CreateAt delete_at: description: Deleted time, set to indicate user is deleted format: int64 type: integer x-go-name: DeleteAt id: description: The user ID type: string x-go-name: ID is_bot: description: If the user is a bot or not type: boolean x-go-name: IsBot props: additionalProperties: type: object description: User settings type: object x-go-name: Props update_at: description: Updated time format: int64 type: integer x-go-name: UpdateAt username: description: The user name type: string x-go-name: Username required: - id - username - props - create_at - update_at - delete_at - is_bot type: object x-go-package: github.com/mattermost/focalboard/server/model UserWorkspace: description: |- UserWorkspace is a summary of a single association between a user and a workspace properties: boardCount: description: Number of boards in the workspace format: int64 type: integer x-go-name: BoardCount id: description: ID of the workspace type: string x-go-name: ID title: description: Title of the workspace type: string x-go-name: Title required: - id type: object x-go-package: github.com/mattermost/focalboard/server/model Workspace: description: Workspace is information global to a workspace properties: id: description: ID of the workspace type: string x-go-name: ID modifiedBy: description: ID of user who last modified this type: string x-go-name: ModifiedBy settings: additionalProperties: type: object description: Workspace settings type: object x-go-name: Settings signupToken: description: Token required to register new users type: string x-go-name: SignupToken title: description: Title of the workspace type: string x-go-name: Title updateAt: description: Updated time format: int64 type: integer x-go-name: UpdateAt required: - id - signupToken - modifiedBy - updateAt type: object x-go-package: github.com/mattermost/focalboard/server/model OnboardingResponse: description: OnboardResponse contains basic data required by the client to complete the onboarding properties: workspaceID: description: the workspace to send to user to, to start the onboarding tour type: string boardID: description: the board to send to user to, to start the onboarding tour type: string 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: 1.0.0 paths: /api/v1/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' /api/v1/logout: post: description: Logout user operationId: logout produces: - application/json responses: "200": description: success "500": description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] /api/v1/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' /api/v1/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: [] /api/v1/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: [] /api/v1/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: [] /api/v1/workspaces/{workspaceID}: get: description: Returns information of the root workspace operationId: getWorkspace parameters: - description: Workspace ID in: path name: workspaceID required: true type: string produces: - application/json responses: "200": description: success schema: $ref: '#/definitions/Workspace' default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] /api/v1/workspaces/{workspaceID}/{rootID}/files: post: consumes: - multipart/form-data description: Upload a binary file, attached to a root block operationId: uploadFile parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - description: ID of the root block in: path name: rootID 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' default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] /api/v1/workspaces/{workspaceID}/blocks: get: description: Returns blocks operationId: getBlocks parameters: - description: Workspace ID in: path name: workspaceID 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 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: Workspace ID in: path name: workspaceID required: true type: string - 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: [] /api/v1/workspaces/{workspaceID}/blocks/: patch: description: Partially updates batch of blocks operationId: patchBlocks parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - 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: [] /api/v1/workspaces/{workspaceID}/blocks/{blockID}: delete: description: Deletes a block operationId: deleteBlock parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - description: ID of block to delete in: path name: blockID required: true type: string produces: - application/json responses: "200": description: success default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] patch: description: Partially updates a block operationId: patchBlock parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - description: ID of block to patch in: path name: blockID required: true type: string - description: block patch to apply in: body name: Body required: true schema: $ref: '#/definitions/BlockPatch' produces: - application/json responses: "200": description: success default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] /api/v1/workspaces/{workspaceID}/blocks/{blockID}/subtree: get: description: Returns the blocks of a subtree operationId: getSubTree parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - description: The ID of the root block of the subtree in: path name: blockID required: true type: string - description: The number of levels to return. 2 or 3. Defaults to 2. in: query maximum: 3 minimum: 2 name: l type: integer produces: - application/json responses: "200": description: success schema: items: $ref: '#/definitions/Block' type: array default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] /api/v1/workspaces/{workspaceID}/blocks/export: get: description: Returns all blocks operationId: exportBlocks parameters: - description: Workspace ID in: path name: workspaceID required: true type: string produces: - application/json responses: "200": description: success schema: items: $ref: '#/definitions/Block' type: array default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] /api/v1/workspaces/{workspaceID}/blocks/import: post: description: Import blocks operationId: importBlocks parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - description: array of blocks to import in: body name: Body required: true schema: items: $ref: '#/definitions/Block' type: array produces: - application/json responses: "200": description: success default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] /api/v1/workspaces/{workspaceID}/regenerate_signup_token: post: description: Regenerates the signup token for the root workspace operationId: regenerateSignupToken parameters: - description: Workspace ID in: path name: workspaceID required: true type: string produces: - application/json responses: "200": description: success default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] /api/v1/workspaces/{workspaceID}/sharing/{rootID}: get: description: Returns sharing information for a root block operationId: getSharing parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - description: ID of the root block in: path name: rootID required: true type: string produces: - application/json responses: "200": description: success schema: $ref: '#/definitions/Sharing' default: description: internal error schema: $ref: '#/definitions/ErrorResponse' security: - BearerAuth: [] post: description: Sets sharing information for a root block operationId: postSharing parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - description: ID of the root block in: path name: rootID 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: [] /api/v1/workspaces/{workspaceID}/subscriptions: post: operationId: createSubscription parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - 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. /api/v1/workspaces/{workspaceID}/subscriptions/{blockID}/{subscriberID}: delete: operationId: deleteSubscription parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - 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. /api/v1/workspaces/{workspaceID}/subscriptions/{subscriberID}: get: operationId: getSubscriptions parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - 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. /api/v1/workspaces/{workspaceID}/users: get: description: Returns workspace users operationId: getWorkspaceUsers parameters: - description: Workspace ID in: path name: workspaceID 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: [] /workspaces/{workspaceID}/{rootID}/{fileID}: get: description: Returns the contents of an uploaded file operationId: getFile parameters: - description: Workspace ID in: path name: workspaceID required: true type: string - description: ID of the root block in: path name: rootID required: true type: string - description: ID of the file in: path name: fileID required: true type: string produces: - application/json - image/jpg - image/png responses: "200": description: success 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 "' in: header name: Authorization type: apiKey swagger: "2.0"