focalboard/server/swagger/swagger.yml

876 lines
22 KiB
YAML
Raw Normal View History

2021-02-17 20:29:20 +01:00
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
2021-02-17 20:29:20 +01:00
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:
description: The block type
type: string
x-go-name: Type
updateAt:
description: The last modified time
format: int64
type: integer
x-go-name: UpdateAt
required:
- id
- rootId
- createdBy
2021-02-17 20:29:20 +01:00
- modifiedBy
- schema
- type
- createAt
- updateAt
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:
description: The block type
type: string
x-go-name: Type
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
2021-02-17 20:29:20 +01:00
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
2021-03-26 19:01:54 +01:00
errorCode:
description: The error code
format: int64
type: integer
x-go-name: ErrorCode
2021-02-17 20:29:20 +01:00
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
2021-02-17 20:29:20 +01:00
type: string
x-go-name: FileID
2021-02-17 20:29:20 +01:00
required:
- fileId
2021-02-17 20:29:20 +01:00
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
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
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
email:
description: The user's email
type: string
x-go-name: Email
id:
description: The user ID
type: string
x-go-name: ID
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
- email
- props
- create_at
- update_at
- delete_at
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
2021-02-17 20:29:20 +01:00
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
host: localhost
info:
contact:
email: api@focalboard.com
name: Focalboard
url: https://www.focalboard.com
description: Server for Focalboard
license:
name: Custom
url: https://github.com/mattermost/focalboard/blob/main/LICENSE.txt
title: Focalboard Server
2021-03-08 18:36:14 +01:00
version: 1.0.0
2021-02-17 20:29:20 +01:00
paths:
2021-03-26 19:01:54 +01:00
/api/v1/login:
2021-02-17 20:29:20 +01:00
post:
2021-03-26 19:01:54 +01:00
description: Login user
operationId: login
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Login request
2021-02-17 20:29:20 +01:00
in: body
2021-03-26 19:01:54 +01:00
name: body
2021-02-17 20:29:20 +01:00
required: true
schema:
2021-03-26 19:01:54 +01:00
$ref: '#/definitions/LoginRequest'
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
2021-03-26 19:01:54 +01:00
schema:
$ref: '#/definitions/LoginResponse'
"401":
description: invalid login
schema:
$ref: '#/definitions/ErrorResponse'
"500":
2021-02-17 20:29:20 +01:00
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
2021-03-26 19:01:54 +01:00
/api/v1/register:
post:
description: Register new user
operationId: register
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Register request
in: body
name: body
2021-02-17 20:29:20 +01:00
required: true
2021-03-26 19:01:54 +01:00
schema:
$ref: '#/definitions/RegisterRequest'
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
2021-03-26 19:01:54 +01:00
"401":
description: invalid registration token
"500":
2021-02-17 20:29:20 +01:00
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
2021-03-26 19:01:54 +01:00
/api/v1/users/{userID}:
2021-02-17 20:29:20 +01:00
get:
2021-03-26 19:01:54 +01:00
description: Returns a user
operationId: getUser
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: User ID
2021-02-17 20:29:20 +01:00
in: path
2021-03-26 19:01:54 +01:00
name: userID
2021-02-17 20:29:20 +01:00
required: true
type: string
produces:
- application/json
responses:
"200":
description: success
schema:
2021-03-26 19:01:54 +01:00
$ref: '#/definitions/User'
2021-02-17 20:29:20 +01:00
default:
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
2021-03-26 19:01:54 +01:00
/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'
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
2021-03-26 19:01:54 +01:00
"400":
description: invalid request
2021-02-17 20:29:20 +01:00
schema:
2021-03-26 19:01:54 +01:00
$ref: '#/definitions/ErrorResponse'
"500":
2021-02-17 20:29:20 +01:00
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
2021-03-26 19:01:54 +01:00
/api/v1/users/me:
get:
description: Returns the currently logged-in user
operationId: getMe
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
2021-03-26 19:01:54 +01:00
schema:
$ref: '#/definitions/User'
2021-02-17 20:29:20 +01:00
default:
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
2021-03-26 19:01:54 +01:00
/api/v1/workspaces/{workspaceID}:
get:
description: Returns information of the root workspace
operationId: getWorkspace
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Workspace ID
in: path
name: workspaceID
required: true
type: string
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
schema:
2021-03-26 19:01:54 +01:00
$ref: '#/definitions/Workspace'
2021-02-17 20:29:20 +01:00
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: []
2021-03-26 19:01:54 +01:00
/api/v1/workspaces/{workspaceID}/blocks:
get:
description: Returns blocks
operationId: getBlocks
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Workspace ID
in: path
name: workspaceID
2021-02-17 20:29:20 +01:00
required: true
2021-03-26 19:01:54 +01:00
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
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
schema:
2021-03-26 19:01:54 +01:00
items:
$ref: '#/definitions/Block'
type: array
default:
2021-02-17 20:29:20 +01:00
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
2021-03-26 19:01:54 +01:00
security:
- BearerAuth: []
2021-02-17 20:29:20 +01:00
post:
2021-03-26 19:01:54 +01:00
description: Insert or update blocks
operationId: updateBlocks
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Workspace ID
in: path
name: workspaceID
required: true
type: string
- description: array of blocks to insert or update
2021-02-17 20:29:20 +01:00
in: body
2021-03-26 19:01:54 +01:00
name: Body
2021-02-17 20:29:20 +01:00
required: true
schema:
2021-03-26 19:01:54 +01:00
items:
$ref: '#/definitions/Block'
type: array
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
2021-03-26 19:01:54 +01:00
default:
2021-02-17 20:29:20 +01:00
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
2021-03-26 19:01:54 +01:00
security:
- BearerAuth: []
/api/v1/workspaces/{workspaceID}/blocks/{blockID}:
delete:
description: Deletes a block
operationId: deleteBlock
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Workspace ID
2021-02-17 20:29:20 +01:00
in: path
2021-03-26 19:01:54 +01:00
name: workspaceID
required: true
type: string
- description: ID of block to delete
in: path
name: blockID
2021-02-17 20:29:20 +01:00
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: []
2021-03-26 19:01:54 +01:00
/api/v1/workspaces/{workspaceID}/blocks/{blockID}/subtree:
get:
description: Returns the blocks of a subtree
operationId: getSubTree
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Workspace ID
2021-02-17 20:29:20 +01:00
in: path
2021-03-26 19:01:54 +01:00
name: workspaceID
2021-02-17 20:29:20 +01:00
required: true
type: string
2021-03-26 19:01:54 +01:00
- description: The ID of the root block of the subtree
in: path
name: blockID
2021-02-17 20:29:20 +01:00
required: true
2021-03-26 19:01:54 +01:00
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
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
2021-03-26 19:01:54 +01:00
schema:
items:
$ref: '#/definitions/Block'
type: array
2021-02-17 20:29:20 +01:00
default:
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
2021-03-26 19:01:54 +01:00
/api/v1/workspaces/{workspaceID}/blocks/export:
2021-02-17 20:29:20 +01:00
get:
2021-03-26 19:01:54 +01:00
description: Returns all blocks
operationId: exportBlocks
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Workspace ID
2021-02-17 20:29:20 +01:00
in: path
2021-03-26 19:01:54 +01:00
name: workspaceID
2021-02-17 20:29:20 +01:00
required: true
type: string
produces:
- application/json
responses:
"200":
description: success
schema:
2021-03-26 19:01:54 +01:00
items:
$ref: '#/definitions/Block'
type: array
2021-02-17 20:29:20 +01:00
default:
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
2021-03-26 19:01:54 +01:00
/api/v1/workspaces/{workspaceID}/blocks/import:
2021-02-17 20:29:20 +01:00
post:
2021-03-26 19:01:54 +01:00
description: Import blocks
operationId: importBlocks
2021-02-17 20:29:20 +01:00
parameters:
2021-03-26 19:01:54 +01:00
- description: Workspace ID
2021-02-17 20:29:20 +01:00
in: path
2021-03-26 19:01:54 +01:00
name: workspaceID
2021-02-17 20:29:20 +01:00
required: true
type: string
2021-03-26 19:01:54 +01:00
- description: array of blocks to import
2021-02-17 20:29:20 +01:00
in: body
2021-03-26 19:01:54 +01:00
name: Body
2021-02-17 20:29:20 +01:00
required: true
schema:
2021-03-26 19:01:54 +01:00
items:
$ref: '#/definitions/Block'
type: array
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
2021-03-26 19:01:54 +01:00
default:
2021-02-17 20:29:20 +01:00
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
2021-03-26 19:01:54 +01:00
/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
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
default:
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
2021-03-26 19:01:54 +01:00
/api/v1/workspaces/{workspaceID}/sharing/{rootID}:
2021-02-17 20:29:20 +01:00
get:
2021-03-26 19:01:54 +01:00
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
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
schema:
2021-03-26 19:01:54 +01:00
$ref: '#/definitions/Sharing'
2021-02-17 20:29:20 +01:00
default:
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
post:
2021-03-26 19:01:54 +01:00
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'
2021-02-17 20:29:20 +01:00
produces:
- application/json
responses:
"200":
description: success
default:
description: internal error
schema:
$ref: '#/definitions/ErrorResponse'
security:
- BearerAuth: []
/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}:
2021-02-17 20:29:20 +01:00
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
2021-02-17 20:29:20 +01:00
- 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 <session token>"'
2021-02-17 20:29:20 +01:00
in: header
name: Authorization
type: apiKey
swagger: "2.0"