steve/pcli
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 4 Wiki Activity
Files
b07572fed5c79bf0393b0ed18602fd897d588cfa
pcli/reference/planka-api.json
T
Steve Cliff b07572fed5 Released v1
2026-02-12 10:37:19 +00:00

10538 lines
327 KiB
JSON
Raw Blame History

{
"openapi": "3.0.0",
"info": {
"version": "2.0.0",
"title": "PLANKA API",
"description": "API documentation for PLANKA - Real-Time Collaborative Kanban Board Application",
"license": {
"name": "Fair Use License",
"url": "https://github.com/plankanban/planka/blob/master/LICENSE.md"
}
},
"servers": [
{
"url": "/api",
"description": "Base path for API endpoints"
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"schemas": {
"Action": {
"type": "object",
"required": [
"id",
"boardId",
"cardId",
"userId",
"type",
"data",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the action",
"example": "1357158568008091264"
},
"boardId": {
"type": "string",
"nullable": true,
"description": "ID of the board where the action occurred",
"example": "1357158568008091265"
},
"cardId": {
"type": "string",
"description": "ID of the card where the action occurred",
"example": "1357158568008091266"
},
"userId": {
"type": "string",
"nullable": true,
"description": "ID of the user who performed the action",
"example": "1357158568008091267"
},
"type": {
"type": "string",
"enum": [
"createCard",
"moveCard",
"addMemberToCard",
"removeMemberFromCard",
"completeTask",
"uncompleteTask"
],
"description": "Type of the action",
"example": "moveCard"
},
"data": {
"type": "object",
"description": "Action specific data (varies by type)",
"example": {
"card": {
"name": "Implement user authentication"
},
"toList": {
"id": "1357158568008091268",
"name": "To Do",
"type": "active"
},
"fromList": {
"id": "1357158568008091269",
"name": "Done",
"type": "closed"
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the action was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the action was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Attachment": {
"type": "object",
"required": [
"id",
"cardId",
"creatorUserId",
"type",
"data",
"name",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the attachment",
"example": "1357158568008091264"
},
"cardId": {
"type": "string",
"description": "ID of the card the attachment belongs to",
"example": "1357158568008091265"
},
"creatorUserId": {
"type": "string",
"nullable": true,
"description": "ID of the user who created the attachment",
"example": "1357158568008091266"
},
"type": {
"type": "string",
"enum": [
"file",
"link"
],
"description": "Type of the attachment",
"example": "link"
},
"data": {
"type": "object",
"description": "Attachment specific data (varies by type)",
"example": {
"url": "https://google.com/search?q=planka",
"faviconUrl": "https://storage.example.com/favicons/google.com.png"
}
},
"name": {
"type": "string",
"description": "Name/title of the attachment",
"example": "Important Attachment"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the attachment was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the attachment was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"BackgroundImage": {
"type": "object",
"required": [
"id",
"projectId",
"size",
"url",
"thumbnailUrls",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the background image",
"example": "1357158568008091264"
},
"projectId": {
"type": "string",
"description": "ID of the project the background image belongs to",
"example": "1357158568008091265"
},
"size": {
"type": "string",
"description": "File size of the background image in bytes",
"example": 1024576
},
"url": {
"type": "string",
"format": "uri",
"description": "URL to access the full-size background image",
"example": "https://storage.example.com/background-images/1357158568008091264/original.jpg"
},
"thumbnailUrls": {
"type": "object",
"required": [
"outside360"
],
"description": "URLs for different thumbnail sizes of the background image",
"properties": {
"outside360": {
"type": "string",
"format": "uri",
"description": "URL for 360px thumbnail version",
"example": "https://storage.example.com/background-images/1357158568008091264/outside-360.jpg"
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the background image was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the background image was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"BaseCustomFieldGroup": {
"type": "object",
"required": [
"id",
"projectId",
"name",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the base custom field group",
"example": "1357158568008091264"
},
"projectId": {
"type": "string",
"description": "ID of the project the base custom field group belongs to",
"example": "1357158568008091265"
},
"name": {
"type": "string",
"description": "Name/title of the base custom field group",
"example": "Base Properties"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the base custom field group was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the base custom field group was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Board": {
"type": "object",
"required": [
"id",
"projectId",
"position",
"name",
"defaultView",
"defaultCardType",
"limitCardTypesToDefaultOne",
"alwaysDisplayCardCreator",
"expandTaskListsByDefault",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the board",
"example": "1357158568008091264"
},
"projectId": {
"type": "string",
"description": "ID of the project the board belongs to",
"example": "1357158568008091265"
},
"position": {
"type": "number",
"description": "Position of the board within the project",
"example": 65536
},
"name": {
"type": "string",
"description": "Name/title of the board",
"example": "Development Board"
},
"defaultView": {
"type": "string",
"enum": [
"kanban",
"grid",
"list"
],
"default": "kanban",
"description": "Default view for the board",
"example": "kanban"
},
"defaultCardType": {
"type": "string",
"enum": [
"project",
"story"
],
"default": "project",
"description": "Default card type for new cards",
"example": "project"
},
"limitCardTypesToDefaultOne": {
"type": "boolean",
"default": false,
"description": "Whether to limit card types to default one",
"example": false
},
"alwaysDisplayCardCreator": {
"type": "boolean",
"default": false,
"description": "Whether to always display the card creator",
"example": false
},
"expandTaskListsByDefault": {
"type": "boolean",
"default": false,
"description": "Whether to expand task lists by default",
"example": false
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the board was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the board was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"BoardMembership": {
"type": "object",
"required": [
"id",
"projectId",
"boardId",
"userId",
"role",
"canComment",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the board membership",
"example": "1357158568008091264"
},
"projectId": {
"type": "string",
"description": "ID of the project the board membership belongs to (denormalized)",
"example": "1357158568008091265"
},
"boardId": {
"type": "string",
"description": "ID of the board the membership is associated with",
"example": "1357158568008091266"
},
"userId": {
"type": "string",
"description": "ID of the user who is a member of the board",
"example": "1357158568008091267"
},
"role": {
"type": "string",
"enum": [
"editor",
"viewer"
],
"description": "Role of the user in the board",
"example": "editor"
},
"canComment": {
"type": "boolean",
"nullable": true,
"description": "Whether the user can comment on cards (applies only to viewers)",
"example": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the board membership was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the board membership was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Card": {
"type": "object",
"required": [
"id",
"boardId",
"listId",
"creatorUserId",
"prevListId",
"coverAttachmentId",
"type",
"position",
"name",
"description",
"dueDate",
"isDueCompleted",
"stopwatch",
"commentsTotal",
"isClosed",
"listChangedAt",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the card",
"example": "1357158568008091264"
},
"boardId": {
"type": "string",
"description": "ID of the board the card belongs to (denormalized)",
"example": "1357158568008091265"
},
"listId": {
"type": "string",
"description": "ID of the list the card belongs to",
"example": "1357158568008091266"
},
"creatorUserId": {
"type": "string",
"nullable": true,
"description": "ID of the user who created the card",
"example": "1357158568008091267"
},
"prevListId": {
"type": "string",
"nullable": true,
"description": "ID of the previous list the card was in (available when in archive or trash)",
"example": "1357158568008091268"
},
"coverAttachmentId": {
"type": "string",
"nullable": true,
"description": "ID of the attachment used as cover",
"example": "1357158568008091269"
},
"type": {
"type": "string",
"enum": [
"project",
"story"
],
"description": "Type of the card",
"example": "project"
},
"position": {
"type": "number",
"nullable": true,
"description": "Position of the card within the list",
"example": 65536
},
"name": {
"type": "string",
"description": "Name/title of the card",
"example": "Implement user authentication"
},
"description": {
"type": "string",
"nullable": true,
"description": "Detailed description of the card",
"example": "Add JWT-based authentication system..."
},
"dueDate": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Due date for the card",
"example": "2024-01-01T00:00:00.000Z"
},
"isDueCompleted": {
"type": "boolean",
"nullable": true,
"description": "Whether the due date is completed",
"example": false
},
"stopwatch": {
"type": "object",
"required": [
"startedAt",
"total"
],
"nullable": true,
"description": "Stopwatch data for time tracking",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When the stopwatch was started",
"example": "2024-01-01T00:00:00.000Z"
},
"total": {
"type": "number",
"description": "Total time in seconds",
"example": 3600
}
}
},
"commentsTotal": {
"type": "number",
"default": 0,
"description": "Total number of comments on the card",
"example": 100
},
"isClosed": {
"type": "boolean",
"default": false,
"description": "Whether the card is closed",
"example": false
},
"listChangedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the card was last moved between lists",
"example": "2024-01-01T00:00:00.000Z"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the card was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the card was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"CardLabel": {
"type": "object",
"required": [
"id",
"cardId",
"labelId",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the card-label association",
"example": "1357158568008091264"
},
"cardId": {
"type": "string",
"description": "ID of the card the label is associated with",
"example": "1357158568008091265"
},
"labelId": {
"type": "string",
"description": "ID of the label associated with the card",
"example": "1357158568008091266"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the card-label association was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the card-label association was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"CardMembership": {
"type": "object",
"required": [
"id",
"cardId",
"userId",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the card membership",
"example": "1357158568008091264"
},
"cardId": {
"type": "string",
"description": "ID of the card the user is a member of",
"example": "1357158568008091265"
},
"userId": {
"type": "string",
"description": "ID of the user who is a member of the card",
"example": "1357158568008091266"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the card membership was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the card membership was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Comment": {
"type": "object",
"required": [
"id",
"cardId",
"userId",
"text",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the comment",
"example": "1357158568008091264"
},
"cardId": {
"type": "string",
"description": "ID of the card the comment belongs to",
"example": "1357158568008091265"
},
"userId": {
"type": "string",
"nullable": true,
"description": "ID of the user who created the comment",
"example": "1357158568008091266"
},
"text": {
"type": "string",
"description": "Content of the comment",
"example": "This task is almost complete..."
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the comment was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the comment was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Config": {
"type": "object",
"required": [
"version",
"oidc"
],
"properties": {
"version": {
"type": "string",
"description": "Current version of the PLANKA application",
"example": "2.0.0"
},
"activeUsersLimit": {
"type": "number",
"nullable": true,
"description": "Maximum number of active users allowed (conditionally added for admins if configured)",
"example": 100
},
"oidc": {
"type": "object",
"required": [
"authorizationUrl",
"endSessionUrl",
"isEnforced"
],
"nullable": true,
"description": "OpenID Connect configuration (null if not configured)",
"properties": {
"authorizationUrl": {
"type": "string",
"format": "uri",
"description": "OIDC authorization URL for initiating authentication",
"example": "https://oidc.example.com/auth"
},
"endSessionUrl": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "OIDC end session URL for logout (null if not supported by provider)",
"example": "https://oidc.example.com/logout"
},
"isEnforced": {
"type": "boolean",
"description": "Whether OIDC authentication is enforced (users must use OIDC to login)",
"example": false
}
}
}
}
},
"CustomField": {
"type": "object",
"required": [
"id",
"baseCustomFieldGroupId",
"customFieldGroupId",
"position",
"name",
"showOnFrontOfCard",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the custom field",
"example": "1357158568008091264"
},
"baseCustomFieldGroupId": {
"type": "string",
"nullable": true,
"description": "ID of the base custom field group the custom field belongs to",
"example": "1357158568008091265"
},
"customFieldGroupId": {
"type": "string",
"nullable": true,
"description": "ID of the custom field group the custom field belongs to",
"example": "1357158568008091266"
},
"position": {
"type": "number",
"description": "Position of the custom field within the group",
"example": 65536
},
"name": {
"type": "string",
"description": "Name/title of the custom field",
"example": "Priority"
},
"showOnFrontOfCard": {
"type": "boolean",
"description": "Whether to show the field on the front of cards",
"example": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the custom field was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the custom field was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"CustomFieldGroup": {
"type": "object",
"required": [
"id",
"boardId",
"cardId",
"baseCustomFieldGroupId",
"position",
"name",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the custom field group",
"example": "1357158568008091264"
},
"boardId": {
"type": "string",
"nullable": true,
"description": "ID of the board the custom field group belongs to",
"example": "1357158568008091265"
},
"cardId": {
"type": "string",
"nullable": true,
"description": "ID of the card the custom field group belongs to",
"example": "1357158568008091266"
},
"baseCustomFieldGroupId": {
"type": "string",
"nullable": true,
"description": "ID of the base custom field group used as a template",
"example": "1357158568008091267"
},
"position": {
"type": "number",
"description": "Position of the custom field group within the board/card",
"example": 65536
},
"name": {
"type": "string",
"nullable": true,
"description": "Name/title of the custom field group",
"example": "Properties"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the custom field group was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the custom field group was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"CustomFieldValue": {
"type": "object",
"required": [
"id",
"cardId",
"customFieldGroupId",
"customFieldId",
"content",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the custom field value",
"example": "1357158568008091264"
},
"cardId": {
"type": "string",
"description": "ID of the card the value belongs to",
"example": "1357158568008091265"
},
"customFieldGroupId": {
"type": "string",
"description": "ID of the custom field group the value belongs to",
"example": "1357158568008091266"
},
"customFieldId": {
"type": "string",
"description": "ID of the custom field the value belongs to",
"example": "1357158568008091267"
},
"content": {
"type": "string",
"description": "Content/value of the custom field",
"example": "High Priority"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the custom field value was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the custom field value was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Label": {
"type": "object",
"required": [
"id",
"boardId",
"position",
"name",
"color",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the label",
"example": "1357158568008091264"
},
"boardId": {
"type": "string",
"description": "ID of the board the label belongs to",
"example": "1357158568008091265"
},
"position": {
"type": "number",
"description": "Position of the label within the board",
"example": 65536
},
"name": {
"type": "string",
"nullable": true,
"description": "Name/title of the label",
"example": "Bug"
},
"color": {
"type": "string",
"enum": [
"muddy-grey",
"autumn-leafs",
"morning-sky",
"antique-blue",
"egg-yellow",
"desert-sand",
"dark-granite",
"fresh-salad",
"lagoon-blue",
"midnight-blue",
"light-orange",
"pumpkin-orange",
"light-concrete",
"sunny-grass",
"navy-blue",
"lilac-eyes",
"apricot-red",
"orange-peel",
"silver-glint",
"bright-moss",
"deep-ocean",
"summer-sky",
"berry-red",
"light-cocoa",
"grey-stone",
"tank-green",
"coral-green",
"sugar-plum",
"pink-tulip",
"shady-rust",
"wet-rock",
"wet-moss",
"turquoise-sea",
"lavender-fields",
"piggy-red",
"light-mud",
"gun-metal",
"modern-green",
"french-coast",
"sweet-lilac",
"red-burgundy",
"pirate-gold"
],
"description": "Color of the label",
"example": "berry-red"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the label was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the label was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"List": {
"type": "object",
"required": [
"id",
"boardId",
"type",
"position",
"name",
"color",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the list",
"example": "1357158568008091264"
},
"boardId": {
"type": "string",
"description": "ID of the board the list belongs to",
"example": "1357158568008091265"
},
"type": {
"type": "string",
"enum": [
"active",
"closed",
"archive",
"trash"
],
"description": "Type/status of the list",
"example": "active"
},
"position": {
"type": "number",
"nullable": true,
"description": "Position of the list within the board",
"example": 65536
},
"name": {
"type": "string",
"nullable": true,
"description": "Name/title of the list",
"example": "To Do"
},
"color": {
"type": "string",
"enum": [
"berry-red",
"pumpkin-orange",
"lagoon-blue",
"pink-tulip",
"light-mud",
"orange-peel",
"bright-moss",
"antique-blue",
"dark-granite",
"turquoise-sea"
],
"nullable": true,
"description": "Color for the list",
"example": "lagoon-blue"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the list was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the list was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Notification": {
"type": "object",
"required": [
"id",
"userId",
"creatorUserId",
"boardId",
"cardId",
"commentId",
"actionId",
"type",
"data",
"isRead",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the notification",
"example": "1357158568008091264"
},
"userId": {
"type": "string",
"description": "ID of the user who receives the notification",
"example": "1357158568008091265"
},
"creatorUserId": {
"type": "string",
"nullable": true,
"description": "ID of the user who created the notification",
"example": "1357158568008091266"
},
"boardId": {
"type": "string",
"description": "ID of the board associated with the notification (denormalized)",
"example": "1357158568008091267"
},
"cardId": {
"type": "string",
"description": "ID of the card associated with the notification",
"example": "1357158568008091268"
},
"commentId": {
"type": "string",
"nullable": true,
"description": "ID of the comment associated with the notification",
"example": "1357158568008091269"
},
"actionId": {
"type": "string",
"nullable": true,
"description": "ID of the action associated with the notification",
"example": "1357158568008091270"
},
"type": {
"type": "string",
"enum": [
"moveCard",
"commentCard",
"addMemberToCard",
"mentionInComment"
],
"description": "Type of the notification",
"example": "commentCard"
},
"data": {
"type": "object",
"description": "Notification specific data (varies by type)",
"example": {
"card": {
"name": "Implement user authentication"
},
"text": "This task is almost complete..."
}
},
"isRead": {
"type": "boolean",
"default": false,
"description": "Whether the notification has been read",
"example": false
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the notification was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the notification was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"NotificationService": {
"type": "object",
"required": [
"id",
"userId",
"boardId",
"url",
"format",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the notification service",
"example": "1357158568008091264"
},
"userId": {
"type": "string",
"nullable": true,
"description": "ID of the user the service is associated with",
"example": "1357158568008091265"
},
"boardId": {
"type": "string",
"nullable": true,
"description": "ID of the board the service is associated with",
"example": "1357158568008091266"
},
"url": {
"type": "string",
"description": "URL endpoint for notifications",
"example": "https://service.example.com/planka"
},
"format": {
"type": "string",
"enum": [
"text",
"markdown",
"html"
],
"description": "Format for notification messages",
"example": "text"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the notification service was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the notification service was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Project": {
"type": "object",
"required": [
"id",
"ownerProjectManagerId",
"backgroundImageId",
"name",
"description",
"backgroundType",
"backgroundGradient",
"isHidden",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the project",
"example": "1357158568008091264"
},
"ownerProjectManagerId": {
"type": "string",
"nullable": true,
"description": "ID of the project manager who owns the project",
"example": "1357158568008091265"
},
"backgroundImageId": {
"type": "string",
"nullable": true,
"description": "ID of the background image used as background",
"example": "1357158568008091266"
},
"name": {
"type": "string",
"description": "Name/title of the project",
"example": "Development Project"
},
"description": {
"type": "string",
"nullable": true,
"description": "Detailed description of the project",
"example": "A project for developing new features..."
},
"backgroundType": {
"type": "string",
"enum": [
"gradient",
"image"
],
"nullable": true,
"description": "Type of background for the project",
"example": "gradient"
},
"backgroundGradient": {
"type": "string",
"enum": [
"old-lime",
"ocean-dive",
"tzepesch-style",
"jungle-mesh",
"strawberry-dust",
"purple-rose",
"sun-scream",
"warm-rust",
"sky-change",
"green-eyes",
"blue-xchange",
"blood-orange",
"sour-peel",
"green-ninja",
"algae-green",
"coral-reef",
"steel-grey",
"heat-waves",
"velvet-lounge",
"purple-rain",
"blue-steel",
"blueish-curve",
"prism-light",
"green-mist",
"red-curtain"
],
"nullable": true,
"description": "Gradient background for the project",
"example": "ocean-dive"
},
"isHidden": {
"type": "boolean",
"default": false,
"description": "Whether the project is hidden",
"example": false
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the project was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the project was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"ProjectManager": {
"type": "object",
"required": [
"id",
"projectId",
"userId",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the project manager",
"example": "1357158568008091264"
},
"projectId": {
"type": "string",
"description": "ID of the project the manager is associated with",
"example": "1357158568008091265"
},
"userId": {
"type": "string",
"description": "ID of the user who is assigned as project manager",
"example": "1357158568008091266"
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the project manager was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the project manager was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Task": {
"type": "object",
"required": [
"id",
"taskListId",
"linkedCardId",
"assigneeUserId",
"position",
"name",
"isCompleted",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the task",
"example": "1357158568008091264"
},
"taskListId": {
"type": "string",
"description": "ID of the task list the task belongs to",
"example": "1357158568008091265"
},
"linkedCardId": {
"type": "string",
"nullable": true,
"description": "ID of the card linked to the task",
"example": "1357158568008091266"
},
"assigneeUserId": {
"type": "string",
"nullable": true,
"description": "ID of the user assigned to the task",
"example": "1357158568008091267"
},
"position": {
"type": "number",
"description": "Position of the task within the task list",
"example": 65536
},
"name": {
"type": "string",
"description": "Name/title of the task",
"example": "Write unit tests"
},
"isCompleted": {
"type": "boolean",
"default": false,
"description": "Whether the task is completed",
"example": false
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the task was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the task was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"TaskList": {
"type": "object",
"required": [
"id",
"cardId",
"position",
"name",
"showOnFrontOfCard",
"hideCompletedTasks",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the task list",
"example": "1357158568008091264"
},
"cardId": {
"type": "string",
"description": "ID of the card the task list belongs to",
"example": "1357158568008091265"
},
"position": {
"type": "number",
"description": "Position of the task list within the card",
"example": 65536
},
"name": {
"type": "string",
"description": "Name/title of the task list",
"example": "Development Tasks"
},
"showOnFrontOfCard": {
"type": "boolean",
"default": true,
"description": "Whether to show the task list on the front of the card",
"example": true
},
"hideCompletedTasks": {
"type": "boolean",
"default": false,
"description": "Whether to hide completed tasks",
"example": false
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the task list was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the task list was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"User": {
"type": "object",
"required": [
"id",
"role",
"name",
"username",
"avatar",
"phone",
"organization",
"termsType",
"isDeactivated",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the user",
"example": "1357158568008091264"
},
"email": {
"type": "string",
"format": "email",
"description": "Email address for login and notifications (private field)",
"example": "john.doe@example.com"
},
"role": {
"type": "string",
"enum": [
"admin",
"projectOwner",
"boardUser"
],
"description": "User role defining access permissions",
"example": "admin"
},
"name": {
"type": "string",
"description": "Full display name of the user",
"example": "John Doe"
},
"username": {
"type": "string",
"minLength": 3,
"maxLength": 32,
"pattern": "^[a-zA-Z0-9]+((_{1}|\\.|){1}[a-zA-Z0-9])*$",
"nullable": true,
"description": "Unique username for user identification",
"example": "john_doe"
},
"avatar": {
"type": "object",
"required": [
"url",
"thumbnailUrls"
],
"nullable": true,
"description": "Avatar information for the user with generated URLs",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL to the full-size avatar image",
"example": "https://storage.example.com/user-avatars/1357158568008091264/original.jpg"
},
"thumbnailUrls": {
"type": "object",
"required": [
"cover180"
],
"description": "URLs for different thumbnail sizes",
"properties": {
"cover180": {
"type": "string",
"format": "uri",
"description": "URL for 180px cover thumbnail",
"example": "https://storage.example.com/user-avatars/1357158568008091264/cover-180.jpg"
}
}
}
}
},
"gravatarUrl": {
"type": "string",
"format": "uri",
"description": "Gravatar URL for the user (conditionally added if configured)",
"example": "https://www.gravatar.com/avatar/abc123"
},
"phone": {
"type": "string",
"nullable": true,
"description": "Contact phone number",
"example": 1234567890
},
"organization": {
"type": "string",
"nullable": true,
"description": "Organization or company name",
"example": "Acme Corporation"
},
"language": {
"type": "string",
"enum": [
"ar-YE",
"bg-BG",
"cs-CZ",
"da-DK",
"de-DE",
"el-GR",
"en-GB",
"en-US",
"es-ES",
"et-EE",
"fa-IR",
"fi-FI",
"fr-FR",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ko-KR",
"nl-NL",
"pl-PL",
"pt-BR",
"pt-PT",
"ro-RO",
"ru-RU",
"sk-SK",
"sr-Cyrl-RS",
"sr-Latn-RS",
"sv-SE",
"tr-TR",
"uk-UA",
"uz-UZ",
"zh-CN",
"zh-TW"
],
"nullable": true,
"description": "Preferred language for user interface and notifications (personal field)",
"example": "en-US"
},
"subscribeToOwnCards": {
"type": "boolean",
"default": false,
"description": "Whether the user subscribes to their own cards (personal field)",
"example": false
},
"subscribeToCardWhenCommenting": {
"type": "boolean",
"default": true,
"description": "Whether the user subscribes to cards when commenting (personal field)",
"example": true
},
"turnOffRecentCardHighlighting": {
"type": "boolean",
"default": false,
"description": "Whether recent card highlighting is disabled (personal field)",
"example": false
},
"enableFavoritesByDefault": {
"type": "boolean",
"default": false,
"description": "Whether favorites are enabled by default (personal field)",
"example": false
},
"defaultEditorMode": {
"type": "string",
"enum": [
"wysiwyg",
"markup"
],
"default": "wysiwyg",
"description": "Default markdown editor mode (personal field)",
"example": "wysiwyg"
},
"defaultHomeView": {
"type": "string",
"enum": [
"gridProjects",
"groupedProjects"
],
"default": "groupedProjects",
"description": "Default view mode for the home page (personal field)",
"example": "groupedProjects"
},
"defaultProjectsOrder": {
"type": "string",
"enum": [
"byDefault",
"alphabetically",
"byCreationTime"
],
"default": "byDefault",
"description": "Default sort order for projects display (personal field)",
"example": "byDefault"
},
"termsType": {
"type": "string",
"description": "Type of terms applicable to the user based on role",
"example": "general"
},
"isSsoUser": {
"type": "boolean",
"default": false,
"description": "Whether the user is SSO user (private field)",
"example": false
},
"isDeactivated": {
"type": "boolean",
"default": false,
"description": "Whether the user account is deactivated and cannot log in",
"example": false
},
"isDefaultAdmin": {
"type": "boolean",
"description": "Whether the user is the default admin (visible only to current user or admin)",
"example": false
},
"lockedFieldNames": {
"type": "array",
"description": "List of fields locked from editing (visible only to current user or admin)",
"items": {
"type": "string"
},
"example": [
"email",
"password",
"name"
]
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the user was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the user was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
},
"Webhook": {
"type": "object",
"required": [
"id",
"name",
"url",
"accessToken",
"events",
"excludedEvents",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the webhook",
"example": "1357158568008091264"
},
"name": {
"type": "string",
"description": "Name/title of the webhook",
"example": "Webhook Updates"
},
"url": {
"type": "string",
"description": "URL endpoint for the webhook",
"example": "https://webhook.example.com/planka"
},
"accessToken": {
"type": "string",
"nullable": true,
"description": "Access token for webhook authentication",
"example": "secret_token_123"
},
"events": {
"type": "array",
"nullable": true,
"description": "List of events that trigger the webhook",
"items": {
"type": "string"
},
"example": [
"cardCreate",
"cardUpdate",
"cardDelete"
]
},
"excludedEvents": {
"type": "array",
"nullable": true,
"description": "List of events excluded from the webhook",
"items": {
"type": "string"
},
"example": [
"userCreate",
"userUpdate",
"userDelete"
]
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the webhook was created",
"example": "2024-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the webhook was last updated",
"example": "2024-01-01T00:00:00.000Z"
}
}
}
},
"responses": {
"Conflict": {
"description": "Request conflicts with current state of the resource",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_CONFLICT"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Resource already exists"
}
}
}
}
}
},
"Forbidden": {
"description": "Access forbidden - insufficient permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_FORBIDDEN"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Not enough rights"
}
}
}
}
}
},
"NotFound": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_NOT_FOUND"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Resource not found"
}
}
}
}
}
},
"Unauthorized": {
"description": "Authentication required or invalid credentials",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNAUTHORIZED"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Access token is missing, invalid or expired"
}
}
}
}
}
},
"UnprocessableEntity": {
"description": "Request contains semantic errors or validation failures",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNPROCESSABLE_ENTITY"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Validation failed"
}
}
}
}
}
},
"ValidationError": {
"description": "Request validation failed due to missing or invalid parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"problems",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_MISSING_OR_INVALID_PARAMS"
},
"problems": {
"type": "array",
"description": "Array of specific validation error messages",
"items": {
"type": "string"
},
"example": [
"\"emailOrUsername\" is required, but it was not defined.",
"\"password\" is required, but it was not defined."
]
},
"message": {
"type": "string",
"description": "Error message",
"example": "The server could not fulfill this request (`POST /api/access-tokens`) due to 2 missing or invalid parameters."
}
}
}
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/access-tokens/accept-terms": {
"post": {
"summary": "Accept terms and conditions",
"description": "Accept terms during the authentication flow. Converts the pending token to an access token.",
"tags": [
"Access Tokens"
],
"operationId": "acceptTerms",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pendingToken",
"signature"
],
"properties": {
"pendingToken": {
"type": "string",
"maxLength": 1024,
"description": "Pending token received from the authentication flow",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4..."
},
"signature": {
"type": "string",
"minLength": 64,
"maxLength": 64,
"description": "Terms signature hash based on user role",
"example": "940226c4c41f51afe3980ceb63704e752636526f4c52a4ea579e85b247493d94"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Terms accepted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"type": "string",
"description": "Access token for API authentication",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ5..."
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"description": "Invalid pending token",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNAUTHORIZED"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Invalid pending token"
}
}
}
}
}
},
"403": {
"description": "Authentication restriction",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_FORBIDDEN"
},
"message": {
"type": "string",
"enum": [
"Invalid signature",
"Admin login required to initialize instance"
],
"description": "Specific error message",
"example": "Invalid signature"
}
}
}
}
}
}
},
"security": []
}
},
"/access-tokens": {
"post": {
"summary": "User login",
"description": "Authenticates a user using email/username and password. Returns an access token for API authentication.",
"tags": [
"Access Tokens"
],
"operationId": "createAccessToken",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"emailOrUsername",
"password"
],
"properties": {
"emailOrUsername": {
"type": "string",
"maxLength": 256,
"description": "Email address or username of the user",
"example": "john.doe@example.com"
},
"password": {
"type": "string",
"maxLength": 256,
"description": "Password of the user",
"example": "SecurePassword123!"
},
"withHttpOnlyToken": {
"type": "boolean",
"description": "Whether to include an HTTP-only authentication cookie",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Login successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"type": "string",
"description": "Access token for API authentication",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4..."
}
}
}
}
},
"headers": {
"Set-Cookie": {
"description": "HTTP-only authentication cookie (if `withHttpOnlyToken` is true)",
"schema": {
"type": "string",
"example": "httpOnlyToken=29aa3e38-8d24-4029-9743-9cbcf0a0dd5c; HttpOnly; Secure; SameSite=Strict"
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"description": "Invalid credentials",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNAUTHORIZED"
},
"message": {
"type": "string",
"enum": [
"Invalid credentials",
"Invalid email or username",
"Invalid password"
],
"description": "Specific error message",
"example": "Invalid credentials"
}
}
}
}
}
},
"403": {
"description": "Authentication restriction",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_FORBIDDEN"
},
"message": {
"type": "string",
"enum": [
"Use single sign-on",
"Terms acceptance required",
"Admin login required to initialize instance"
],
"description": "Specific error message",
"example": "Use single sign-on"
}
}
}
}
}
}
},
"security": []
}
},
"/access-tokens/me": {
"delete": {
"summary": "User logout",
"description": "Logs out the current user by deleting the session and access token. Clears HTTP-only cookies if present.",
"tags": [
"Access Tokens"
],
"operationId": "deleteAccessToken",
"responses": {
"200": {
"description": "Logout successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"type": "string",
"description": "Revoked access token",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4..."
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/access-tokens/exchange-with-oidc": {
"post": {
"summary": "Exchange OIDC code for access token",
"description": "Exchanges an OIDC authorization code for an access token. Creates a user if they do not exist.",
"tags": [
"Access Tokens"
],
"operationId": "exchangeForAccessTokenWithOidc",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"nonce"
],
"properties": {
"code": {
"type": "string",
"maxLength": 2048,
"description": "Authorization code from OIDC provider",
"example": "abc123def456ghi789"
},
"nonce": {
"type": "string",
"maxLength": 1024,
"description": "Nonce value for OIDC security",
"example": "random-nonce-123456"
},
"withHttpOnlyToken": {
"type": "boolean",
"description": "Whether to include HTTP-only authentication cookie",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OIDC exchange successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"type": "string",
"description": "Access token for API authentication",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4..."
}
}
}
}
},
"headers": {
"Set-Cookie": {
"description": "HTTP-only authentication cookie (if `withHttpOnlyToken` is true)",
"schema": {
"type": "string",
"example": "httpOnlyToken=29aa3e38-8d24-4029-9743-9cbcf0a0dd5c; HttpOnly; Secure; SameSite=Strict"
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"description": "OIDC authentication error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNAUTHORIZED"
},
"message": {
"type": "string",
"enum": [
"Invalid code or nonce",
"Invalid userinfo configuration"
],
"description": "Specific error message",
"example": "Invalid code or nonce"
}
}
}
}
}
},
"403": {
"description": "Authentication restriction",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_FORBIDDEN"
},
"message": {
"type": "string",
"enum": [
"Terms acceptance required",
"Admin login required to initialize instance"
],
"description": "Specific error message",
"example": "Terms acceptance required"
}
}
}
}
}
},
"409": {
"description": "Conflict error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_CONFLICT"
},
"message": {
"type": "string",
"enum": [
"Email already in use",
"Username already in use",
"Active users limit reached"
],
"description": "Specific error message",
"example": "Email already in use"
}
}
}
}
}
},
"422": {
"description": "Missing required values",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNPROCESSABLE_ENTITY"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Unable to retrieve required values (email, name)"
}
}
}
}
}
},
"500": {
"description": "OIDC configuration error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_INTERNAL_SERVER_ERROR"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Invalid OIDC configuration"
}
}
}
}
}
}
},
"security": []
}
},
"/access-tokens/revoke-pending-token": {
"post": {
"summary": "Revoke pending token",
"description": "Revokes a pending authentication token and cancels the authentication flow.",
"tags": [
"Access Tokens"
],
"operationId": "revokePendingToken",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"pendingToken"
],
"properties": {
"pendingToken": {
"type": "string",
"maxLength": 1024,
"description": "Pending token to revoke",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4..."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Pending token revoked successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"item": {
"type": "object",
"nullable": true,
"description": "No data returned",
"example": null
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": []
}
},
"/boards/{boardId}/actions": {
"get": {
"summary": "Get board actions",
"description": "Retrieves a list of actions (activity history) for a specific board, with pagination support.",
"tags": [
"Actions"
],
"operationId": "getBoardActions",
"parameters": [
{
"name": "boardId",
"in": "path",
"required": true,
"description": "ID of the board to get actions for",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "beforeId",
"in": "query",
"required": false,
"description": "ID to get actions before (for pagination)",
"schema": {
"type": "string",
"example": "1357158568008091265"
}
}
],
"responses": {
"200": {
"description": "Board actions retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items",
"included"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Action"
}
},
"included": {
"type": "object",
"required": [
"users"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/cards/{cardId}/actions": {
"get": {
"summary": "Get card actions",
"description": "Retrieves a list of actions (activity history) for a specific card, with pagination support.",
"tags": [
"Actions"
],
"operationId": "getCardActions",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to get actions for",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "beforeId",
"in": "query",
"required": false,
"description": "ID to get actions before (for pagination)",
"schema": {
"type": "string",
"example": "1357158568008091265"
}
}
],
"responses": {
"200": {
"description": "Card actions retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items",
"included"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Action"
}
},
"included": {
"type": "object",
"required": [
"users"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/cards/{cardId}/attachments": {
"post": {
"summary": "Create attachment",
"description": "Creates an attachment on a card. Requires board editor permissions.",
"tags": [
"Attachments"
],
"operationId": "createAttachment",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to create the attachment on",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"file",
"link"
],
"description": "Type of the attachment",
"example": "link"
},
"file": {
"type": "string",
"format": "binary",
"description": "File to upload"
},
"url": {
"type": "string",
"format": "url",
"maxLength": 2048,
"description": "URL for the link attachment",
"example": "https://google.com/search?q=planka"
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the attachment",
"example": "Important Attachment"
},
"requestId": {
"type": "string",
"maxLength": 128,
"description": "Request ID for tracking",
"example": "req_123456"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Attachment created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Attachment"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "Upload or validation error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNPROCESSABLE_ENTITY"
},
"message": {
"type": "string",
"enum": [
"No file was uploaded",
"Url must be present"
],
"description": "Specific error message",
"example": "No file was uploaded"
}
}
}
}
}
}
}
}
},
"/attachments/{id}": {
"delete": {
"summary": "Delete attachment",
"description": "Deletes an attachment. Requires board editor permissions.",
"tags": [
"Attachments"
],
"operationId": "deleteAttachment",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the attachment to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Attachment deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Attachment"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update attachment",
"description": "Updates an attachment. Requires board editor permissions.",
"tags": [
"Attachments"
],
"operationId": "updateAttachment",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the attachment to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the attachment",
"example": "Important Attachment"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Attachment updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Attachment"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/projects/{projectId}/background-images": {
"post": {
"summary": "Upload background image",
"description": "Uploads a background image for a project. Requires project manager permissions.",
"tags": [
"Background Images"
],
"operationId": "createBackgroundImage",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"description": "ID of the project to upload background image for",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "Background image file (must be an image format)"
},
"requestId": {
"type": "string",
"maxLength": 128,
"description": "Request ID for tracking",
"example": "req_123456"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Background image uploaded successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/BackgroundImage"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "File upload error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNPROCESSABLE_ENTITY"
},
"message": {
"type": "string",
"enum": [
"No file was uploaded",
"File is not image"
],
"description": "Specific error message",
"example": "No file was uploaded"
}
}
}
}
}
}
}
}
},
"/background-images/{id}": {
"delete": {
"summary": "Delete background image",
"description": "Deletes a background image. Requires project manager permissions.",
"tags": [
"Background Images"
],
"operationId": "deleteBackgroundImage",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the background image to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Background image deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/BackgroundImage"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/projects/{projectId}/base-custom-field-groups": {
"post": {
"summary": "Create base custom field group",
"description": "Creates a base custom field group within a project. Requires project manager permissions.",
"tags": [
"Base Custom Field Groups"
],
"operationId": "createBaseCustomFieldGroup",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"description": "ID of the project to create the base custom field group in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the base custom field group",
"example": "Base Properties"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Base custom field group created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/BaseCustomFieldGroup"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/base-custom-field-groups/{id}": {
"delete": {
"summary": "Delete base custom field group",
"description": "Deletes a base custom field group. Requires project manager permissions.",
"tags": [
"Base Custom Field Groups"
],
"operationId": "deleteBaseCustomFieldGroup",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the base custom field group to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Base custom field group deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/BaseCustomFieldGroup"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update base custom field group",
"description": "Updates a base custom field group. Requires project manager permissions.",
"tags": [
"Base Custom Field Groups"
],
"operationId": "updateBaseCustomFieldGroup",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the base custom field group to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the base custom field group",
"example": "Base Properties"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Base custom field group updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/BaseCustomFieldGroup"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/boards/{boardId}/board-memberships": {
"post": {
"summary": "Create board membership",
"description": "Creates a board membership within a board. Requires project manager permissions.",
"tags": [
"Board Memberships"
],
"operationId": "createBoardMembership",
"parameters": [
{
"name": "boardId",
"in": "path",
"required": true,
"description": "ID of the board to create the board membership in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"userId",
"role"
],
"properties": {
"userId": {
"type": "string",
"description": "ID of the user who is a member of the board",
"example": "1357158568008091265"
},
"role": {
"type": "string",
"enum": [
"editor",
"viewer"
],
"description": "Role of the user in the board",
"example": "editor"
},
"canComment": {
"type": "boolean",
"nullable": true,
"description": "Whether the user can comment on cards (applies only to viewers)",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Board membership created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/BoardMembership"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/board-memberships/{id}": {
"delete": {
"summary": "Delete board membership",
"description": "Deletes a board membership. Users can remove their own membership, project managers can remove any membership.",
"tags": [
"Board Memberships"
],
"operationId": "deleteBoardMembership",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the board membership to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Board membership deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/BoardMembership"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update board membership",
"description": "Updates a board membership. Requires project manager permissions.",
"tags": [
"Board Memberships"
],
"operationId": "updateBoardMembership",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the board membership to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"editor",
"viewer"
],
"description": "Role of the user in the board",
"example": "editor"
},
"canComment": {
"type": "boolean",
"nullable": true,
"description": "Whether the user can comment on cards (applies only to viewers)",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Board membership updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/BoardMembership"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/projects/{projectId}/boards": {
"post": {
"summary": "Create board",
"description": "Creates a board within a project. Supports importing from Trello. Requires project manager permissions.",
"tags": [
"Boards"
],
"operationId": "createBoard",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"description": "ID of the project to create the board in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"position",
"name"
],
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the board within the project",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the board",
"example": "Development Board"
},
"importType": {
"type": "string",
"enum": [
"trello"
],
"description": "Type of import",
"example": "trello"
},
"importFile": {
"type": "string",
"format": "binary",
"description": "Import file"
},
"requestId": {
"type": "string",
"maxLength": 128,
"description": "Request ID for tracking",
"example": "req_123456"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Board created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Board"
},
"included": {
"type": "object",
"required": [
"boardMemberships"
],
"properties": {
"boardMemberships": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BoardMembership"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "Import file upload error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "E_UNPROCESSABLE_ENTITY"
},
"message": {
"type": "string",
"enum": [
"No import file was uploaded",
"Invalid import file"
],
"description": "Specific error message",
"example": "No import file was uploaded"
}
}
}
}
}
}
}
}
},
"/boards/{id}": {
"delete": {
"summary": "Delete board",
"description": "Deletes a board and all its contents (lists, cards, etc.). Requires project manager permissions.",
"tags": [
"Boards"
],
"operationId": "deleteBoard",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the board to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Board deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Board"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"get": {
"summary": "Get board details",
"description": "Retrieves comprehensive board information, including lists, cards, and other related data.",
"tags": [
"Boards"
],
"operationId": "getBoard",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the board to retrieve",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "subscribe",
"in": "query",
"required": false,
"description": "Whether to subscribe to real-time updates for this board (only for socket connections)",
"schema": {
"type": "boolean",
"example": true
}
}
],
"responses": {
"200": {
"description": "Board details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"allOf": [
{
"$ref": "#/components/schemas/Board"
},
{
"type": "object",
"properties": {
"isSubscribed": {
"type": "boolean",
"description": "Whether the current user is subscribed to the board",
"example": true
}
}
}
]
},
"included": {
"type": "object",
"required": [
"users",
"projects",
"boardMemberships",
"labels",
"lists",
"cards",
"cardMemberships",
"cardLabels",
"taskLists",
"tasks",
"attachments",
"customFieldGroups",
"customFields",
"customFieldValues"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
},
"projects": {
"type": "array",
"description": "Parent project",
"items": {
"$ref": "#/components/schemas/Project"
}
},
"boardMemberships": {
"type": "array",
"description": "Related board memberships",
"items": {
"$ref": "#/components/schemas/BoardMembership"
}
},
"labels": {
"type": "array",
"description": "Related labels",
"items": {
"$ref": "#/components/schemas/Label"
}
},
"lists": {
"type": "array",
"description": "Related lists",
"items": {
"$ref": "#/components/schemas/List"
}
},
"cards": {
"type": "array",
"description": "Related cards",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Card"
},
{
"type": "object",
"properties": {
"isSubscribed": {
"type": "boolean",
"description": "Whether the current user is subscribed to the card",
"example": true
}
}
}
]
}
},
"cardMemberships": {
"type": "array",
"description": "Related card-membership associations",
"items": {
"$ref": "#/components/schemas/CardMembership"
}
},
"cardLabels": {
"type": "array",
"description": "Related card-label associations",
"items": {
"$ref": "#/components/schemas/CardLabel"
}
},
"taskLists": {
"type": "array",
"description": "Related task lists",
"items": {
"$ref": "#/components/schemas/TaskList"
}
},
"tasks": {
"type": "array",
"description": "Related tasks",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"attachments": {
"type": "array",
"description": "Related attachments",
"items": {
"$ref": "#/components/schemas/Attachment"
}
},
"customFieldGroups": {
"type": "array",
"description": "Related custom field groups",
"items": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
},
"customFields": {
"type": "array",
"description": "Related custom fields",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"customFieldValues": {
"type": "array",
"description": "Related custom field values",
"items": {
"$ref": "#/components/schemas/CustomFieldValue"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update board",
"description": "Updates a board. Project managers can update all fields, board members can only subscribe/unsubscribe.",
"tags": [
"Boards"
],
"operationId": "updateBoard",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the board to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the board within the project",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the board",
"example": "Development Board"
},
"defaultView": {
"type": "string",
"enum": [
"kanban",
"grid",
"list"
],
"description": "Default view for the board",
"example": "kanban"
},
"defaultCardType": {
"type": "string",
"enum": [
"project",
"story"
],
"description": "Default card type for new cards",
"example": "project"
},
"limitCardTypesToDefaultOne": {
"type": "boolean",
"description": "Whether to limit card types to default one",
"example": false
},
"alwaysDisplayCardCreator": {
"type": "boolean",
"description": "Whether to always display card creators",
"example": false
},
"expandTaskListsByDefault": {
"type": "boolean",
"description": "Whether to expand task lists by default",
"example": false
},
"isSubscribed": {
"type": "boolean",
"description": "Whether the current user is subscribed to the board",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Board updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Board"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/cards/{cardId}/card-labels": {
"post": {
"summary": "Add label to card",
"description": "Adds a label to a card. Requires board editor permissions.",
"tags": [
"Card Labels"
],
"operationId": "createCardLabel",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to add the label to",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"labelId"
],
"properties": {
"labelId": {
"type": "string",
"description": "ID of the label to add to the card",
"example": "1357158568008091265"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Label added to card successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CardLabel"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/cards/{cardId}/card-labels/labelId:{labelId}": {
"delete": {
"summary": "Remove label from card",
"description": "Removes a label from a card. Requires board editor permissions.",
"tags": [
"Card Labels"
],
"operationId": "deleteCardLabel",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to remove the label from",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "labelId",
"in": "path",
"required": true,
"description": "ID of the label to remove from the card",
"schema": {
"type": "string",
"example": "1357158568008091265"
}
}
],
"responses": {
"200": {
"description": "Label removed from card successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CardLabel"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/cards/{cardId}/card-memberships": {
"post": {
"summary": "Add user to card",
"description": "Adds a user to a card. Requires board editor permissions.",
"tags": [
"Card Memberships"
],
"operationId": "createCardMembership",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to add the user to",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"userId"
],
"properties": {
"userId": {
"type": "string",
"description": "ID of the card to add the user to",
"example": "1357158568008091265"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User added to card successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CardMembership"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/cards/{cardId}/card-memberships/userId:{userId}": {
"delete": {
"summary": "Remove user from card",
"description": "Removes a user from a card. Requires board editor permissions.",
"tags": [
"Card Memberships"
],
"operationId": "deleteCardMembership",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to remove the user from",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"description": "ID of the user to remove from the card",
"schema": {
"type": "string",
"example": "1357158568008091265"
}
}
],
"responses": {
"200": {
"description": "User removed from card successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CardMembership"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/lists/{listId}/cards": {
"post": {
"summary": "Create card",
"description": "Creates a card within a list. Requires board editor permissions.",
"tags": [
"Cards"
],
"operationId": "createCard",
"parameters": [
{
"name": "listId",
"in": "path",
"required": true,
"description": "ID of the list to create the card in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"project",
"story"
],
"description": "Type of the card",
"example": "project"
},
"position": {
"type": "number",
"minimum": 0,
"nullable": true,
"description": "Position of the card within the list",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 1024,
"description": "Name/title of the card",
"example": "Implement user authentication"
},
"description": {
"type": "string",
"maxLength": 1048576,
"nullable": true,
"description": "Detailed description of the card",
"example": "Add JWT-based authentication system..."
},
"dueDate": {
"type": "string",
"format": "date-time",
"description": "Due date for the card",
"example": "2024-01-01T00:00:00.000Z"
},
"isDueCompleted": {
"type": "boolean",
"nullable": true,
"description": "Whether the due date is completed",
"example": false
},
"stopwatch": {
"type": "object",
"required": [
"startedAt",
"total"
],
"nullable": true,
"description": "Stopwatch data for time tracking",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When the stopwatch was started",
"example": "2024-01-01T00:00:00.000Z"
},
"total": {
"type": "number",
"description": "Total time in seconds",
"example": 3600
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Card created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Card"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"get": {
"summary": "Get cards in list",
"description": "Retrieves cards from an endless list with filtering, search, and pagination support.",
"tags": [
"Cards"
],
"operationId": "getCards",
"parameters": [
{
"name": "listId",
"in": "path",
"required": true,
"description": "ID of the list to get cards from (must be an endless list)",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "before",
"in": "query",
"required": false,
"description": "Pagination cursor (JSON object with id and listChangedAt)",
"schema": {
"type": "string",
"example": "{\"id\": \"1357158568008091269\", \"listChangedAt\": \"2024-01-01T00:00:00.000Z\"}"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Search term to filter cards",
"schema": {
"type": "string",
"maxLength": 128,
"example": "bug fix"
}
},
{
"name": "filterUserIds",
"in": "query",
"required": false,
"description": "Comma-separated user IDs to filter by members",
"schema": {
"type": "string",
"example": "1357158568008091265,1357158568008091266"
}
},
{
"name": "filterLabelIds",
"in": "query",
"required": false,
"description": "Comma-separated label IDs to filter by labels",
"schema": {
"type": "string",
"example": "1357158568008091267,1357158568008091268"
}
}
],
"responses": {
"200": {
"description": "Cards retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items",
"included"
],
"properties": {
"items": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Card"
},
{
"type": "object",
"properties": {
"isSubscribed": {
"type": "boolean",
"description": "Whether the current user is subscribed to the card",
"example": true
}
}
}
]
}
},
"included": {
"type": "object",
"required": [
"users",
"cardMemberships",
"cardLabels",
"taskLists",
"tasks",
"attachments",
"customFieldGroups",
"customFields",
"customFieldValues"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
},
"cardMemberships": {
"type": "array",
"description": "Related card-membership associations",
"items": {
"$ref": "#/components/schemas/CardMembership"
}
},
"cardLabels": {
"type": "array",
"description": "Related card-label associations",
"items": {
"$ref": "#/components/schemas/CardLabel"
}
},
"taskLists": {
"type": "array",
"description": "Realted Task lists",
"items": {
"$ref": "#/components/schemas/TaskList"
}
},
"tasks": {
"type": "array",
"description": "Related tasks",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"attachments": {
"type": "array",
"description": "Related attachments",
"items": {
"$ref": "#/components/schemas/Attachment"
}
},
"customFieldGroups": {
"type": "array",
"description": "Related custom field groups",
"items": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
},
"customFields": {
"type": "array",
"description": "Related custom fields",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"customFieldValues": {
"type": "array",
"description": "Related custom field values",
"items": {
"$ref": "#/components/schemas/CustomFieldValue"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/cards/{id}": {
"delete": {
"summary": "Delete card",
"description": "Deletes a card and all its contents (tasks, attachments, etc.). Requires board editor permissions.",
"tags": [
"Cards"
],
"operationId": "deleteCard",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the card to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Card deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Card"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"get": {
"summary": "Get card details",
"description": "Retrieves comprehensive card information, including tasks, attachments, and other related data.",
"tags": [
"Cards"
],
"operationId": "getCard",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the card to retrieve",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Card details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"allOf": [
{
"$ref": "#/components/schemas/Card"
},
{
"type": "object",
"properties": {
"isSubscribed": {
"type": "boolean",
"description": "Whether the current user is subscribed to the card",
"example": true
}
}
}
]
},
"included": {
"type": "object",
"required": [
"users",
"cardMemberships",
"cardLabels",
"taskLists",
"tasks",
"attachments",
"customFieldGroups",
"customFields",
"customFieldValues"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
},
"cardMemberships": {
"type": "array",
"description": "Related card-membership associations",
"items": {
"$ref": "#/components/schemas/CardMembership"
}
},
"cardLabels": {
"type": "array",
"description": "Related card-label associations",
"items": {
"$ref": "#/components/schemas/CardLabel"
}
},
"taskLists": {
"type": "array",
"description": "Related task lists",
"items": {
"$ref": "#/components/schemas/TaskList"
}
},
"tasks": {
"type": "array",
"description": "Related tasks",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"attachments": {
"type": "array",
"description": "Related attachments",
"items": {
"$ref": "#/components/schemas/Attachment"
}
},
"customFieldGroups": {
"type": "array",
"description": "Related custom field groups",
"items": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
},
"customFields": {
"type": "array",
"description": "Related custom fields",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"customFieldValues": {
"type": "array",
"description": "Related custom field values",
"items": {
"$ref": "#/components/schemas/CustomFieldValue"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update card",
"description": "Updates a card. Board editors can update all fields, viewers can only subscribe/unsubscribe.",
"tags": [
"Cards"
],
"operationId": "updateCard",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the card to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"boardId": {
"type": "string",
"description": "ID of the board to move the card to",
"example": "1357158568008091265"
},
"listId": {
"type": "string",
"description": "ID of the list to move the card to",
"example": "1357158568008091266"
},
"coverAttachmentId": {
"type": "string",
"nullable": true,
"description": "ID of the attachment used as cover",
"example": "1357158568008091267"
},
"type": {
"type": "string",
"enum": [
"project",
"story"
],
"description": "Type of the card",
"example": "project"
},
"position": {
"type": "number",
"minimum": 0,
"nullable": true,
"description": "Position of the card within the list",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 1024,
"description": "Name/title of the card",
"example": "Implement user authentication"
},
"description": {
"type": "string",
"maxLength": 1048576,
"nullable": true,
"description": "Detailed description of the card",
"example": "Add JWT-based authentication system..."
},
"dueDate": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Due date for the card",
"example": "2024-01-01T00:00:00.000Z"
},
"isDueCompleted": {
"type": "boolean",
"nullable": true,
"description": "Whether the due date is completed",
"example": false
},
"stopwatch": {
"type": "object",
"required": [
"startedAt",
"total"
],
"nullable": true,
"description": "Stopwatch data for time tracking",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When the stopwatch was started",
"example": "2024-01-01T00:00:00.000Z"
},
"total": {
"type": "number",
"description": "Total time in seconds",
"example": 3600
}
}
},
"isSubscribed": {
"type": "boolean",
"description": "Whether the current user is subscribed to the card"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Card updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Card"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/cards/{id}/duplicate": {
"post": {
"summary": "Duplicate card",
"description": "Creates a duplicate of a card with all its contents (tasks, attachments, etc.). Requires board editor permissions.",
"tags": [
"Cards"
],
"operationId": "duplicateCard",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the card to duplicate",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"position",
"name"
],
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position for the duplicated card within the list",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 1024,
"description": "Name/title for the duplicated card",
"example": "Implement user authentication (copy)"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Card duplicated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Card"
},
"included": {
"type": "object",
"required": [
"cardMemberships",
"cardLabels",
"taskLists",
"tasks",
"attachments",
"customFieldGroups",
"customFields",
"customFieldValues"
],
"properties": {
"cardMemberships": {
"type": "array",
"description": "Related card-membership associations",
"items": {
"$ref": "#/components/schemas/CardMembership"
}
},
"cardLabels": {
"type": "array",
"description": "Related card-label associations",
"items": {
"$ref": "#/components/schemas/CardLabel"
}
},
"taskLists": {
"type": "array",
"description": "Related task lists",
"items": {
"$ref": "#/components/schemas/TaskList"
}
},
"tasks": {
"type": "array",
"description": "Related tasks",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"attachments": {
"type": "array",
"description": "Related attachments",
"items": {
"$ref": "#/components/schemas/Attachment"
}
},
"customFieldGroups": {
"type": "array",
"description": "Related custom field groups",
"items": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
},
"customFields": {
"type": "array",
"description": "Related custom fields",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"customFieldValues": {
"type": "array",
"description": "Related custom field values",
"items": {
"$ref": "#/components/schemas/CustomFieldValue"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/cards/{id}/read-notifications": {
"post": {
"summary": "Mark card notifications as read",
"description": "Marks all notifications for a specific card as read for the current user. Requires access to the card.",
"tags": [
"Cards"
],
"operationId": "readCardNotifications",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the card to mark notifications as read for",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Notifications marked as read successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Card"
},
"included": {
"type": "object",
"required": [
"notifications"
],
"properties": {
"notifications": {
"type": "array",
"description": "Related notifications",
"items": {
"$ref": "#/components/schemas/Notification"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/cards/{cardId}/comments": {
"post": {
"summary": "Create comment",
"description": "Creates a new comment on a card. Requires board editor permissions or comment permissions.",
"tags": [
"Comments"
],
"operationId": "createComment",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to create the comment on",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 1048576,
"description": "Content of the comment",
"example": "This task is almost complete..."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Comment created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Comment"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"get": {
"summary": "Get card comments",
"description": "Retrieves comments for a card with pagination support. Requires access to the card.",
"tags": [
"Comments"
],
"operationId": "getComments",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to retrieve comments for",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "beforeId",
"in": "query",
"required": false,
"description": "ID to get comments before (for pagination)",
"schema": {
"type": "string",
"example": "1357158568008091265"
}
}
],
"responses": {
"200": {
"description": "Comments retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items",
"included"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Comment"
}
},
"included": {
"type": "object",
"required": [
"users"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/comments/{id}": {
"delete": {
"summary": "Delete comment",
"description": "Deletes a comment. Can be deleted by the comment author (with comment permissions) or project manager.",
"tags": [
"Comments"
],
"operationId": "deleteComment",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the comment to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Comment deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Comment"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update comment",
"description": "Updates a comment. Only the author of the comment can update it.",
"tags": [
"Comments"
],
"operationId": "updateComments",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the comment to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"maxLength": 1048576,
"description": "Content of the comment",
"example": "This task is almost complete..."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Comment updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Comment"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/config": {
"get": {
"summary": "Get application configuration",
"description": "Retrieves the application configuration.",
"tags": [
"Config"
],
"operationId": "getConfig",
"responses": {
"200": {
"description": "Configuration retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Config"
}
}
}
}
}
}
},
"security": []
}
},
"/boards/{boardId}/custom-field-groups": {
"post": {
"summary": "Create board custom field group",
"description": "Creates a custom field group within a board. Either `baseCustomFieldGroupId` or `name` must be provided. Requires board editor permissions.",
"tags": [
"Custom Field Groups"
],
"operationId": "createBoardCustomFieldGroup",
"parameters": [
{
"name": "boardId",
"in": "path",
"required": true,
"description": "ID of the board to create the custom field group in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"position"
],
"properties": {
"baseCustomFieldGroupId": {
"type": "string",
"description": "ID of the base custom field group used as a template",
"example": "1357158568008091265"
},
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the custom field group within the board",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Name/title of the custom field group (required if `baseCustomFieldGroupId` is not provided)",
"example": "Properties"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Custom field group created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/cards/{cardId}/custom-field-groups": {
"post": {
"summary": "Create card custom field group",
"description": "Creates a custom field group within a card. Either `baseCustomFieldGroupId` or `name` must be provided. Requires board editor permissions.",
"tags": [
"Custom Field Groups"
],
"operationId": "createCardCustomFieldGroup",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to create the custom field group in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"position"
],
"properties": {
"baseCustomFieldGroupId": {
"type": "string",
"description": "ID of the base custom field group used as a template",
"example": "1357158568008091265"
},
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the custom field group within the card",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Name/title of the custom field group (required if `baseCustomFieldGroupId` is not provided)",
"example": "Properties"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Custom field group created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/custom-field-groups/{id}": {
"delete": {
"summary": "Delete custom field group",
"description": "Deletes a custom field group. Requires board editor permissions.",
"tags": [
"Custom Field Groups"
],
"operationId": "deleteCustomFieldGroup",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the custom field group to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Custom field group deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"get": {
"summary": "Get custom field group details",
"description": "Retrieves comprehensive custom field group information, including fields and values. Requires access to the board/card.",
"tags": [
"Custom Field Groups"
],
"operationId": "getCustomFieldGroup",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the custom field group to retrieve",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Custom field group details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomFieldGroup"
},
"included": {
"type": "object",
"required": [
"customFields",
"customFieldValues"
],
"properties": {
"customFields": {
"type": "array",
"description": "Related custom fields",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"customFieldValues": {
"type": "array",
"description": "Related custom field values (for card-specific groups)",
"items": {
"$ref": "#/components/schemas/CustomFieldValue"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update custom field group",
"description": "Updates a custom field group. Supports both board-wide and card-specific groups. Requires board editor permissions.",
"tags": [
"Custom Field Groups"
],
"operationId": "updateCustomFieldGroup",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the custom field group to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the custom field group within the board/card",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Name/title of the custom field group",
"example": "Properties"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Custom field group updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/cards/{cardId}/custom-field-values/customFieldGroupId:{customFieldGroupId}:customFieldId:${customFieldId}": {
"patch": {
"summary": "Create or update custom field value",
"description": "Creates or updates a custom field value for a card. Requires board editor permissions.",
"tags": [
"Custom Field Values"
],
"operationId": "updateCustomFieldValue",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to set the custom field value for",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "customFieldGroupId",
"in": "path",
"required": true,
"description": "ID of the custom field group the value belongs to",
"schema": {
"type": "string",
"example": "1357158568008091265"
}
},
{
"name": "customFieldId",
"in": "path",
"required": true,
"description": "ID of the custom field the value belongs to",
"schema": {
"type": "string",
"example": "1357158568008091266"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"maxLength": 512,
"description": "Content/value of the custom field",
"example": "High Priority"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Custom field value created or updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomFieldValue"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/cards/{cardId}/custom-field-value/customFieldGroupId:{customFieldGroupId}:customFieldId:${customFieldId}": {
"delete": {
"summary": "Delete custom field value",
"description": "Deletes a custom field value for a specific card. Requires board editor permissions.",
"tags": [
"Custom Field Values"
],
"operationId": "deleteCustomFieldValue",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to delete the custom field value from",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "customFieldGroupId",
"in": "path",
"required": true,
"description": "ID of the custom field group the value belongs to",
"schema": {
"type": "string",
"example": "1357158568008091265"
}
},
{
"name": "customFieldId",
"in": "path",
"required": true,
"description": "ID of the custom field the value belongs to",
"schema": {
"type": "string",
"example": "1357158568008091266"
}
}
],
"responses": {
"200": {
"description": "Custom field value deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomFieldValue"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/base-custom-field-groups/{baseCustomFieldGroupId}/custom-fields": {
"post": {
"summary": "Create custom field in base custom field group",
"description": "Creates a custom field within a base custom field group. Requires project manager permissions.",
"tags": [
"Custom Fields"
],
"operationId": "createCustomFieldInBaseGroup",
"parameters": [
{
"name": "baseCustomFieldGroupId",
"in": "path",
"required": true,
"description": "ID of the base custom field group to create the custom field in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"position",
"name"
],
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the custom field within the group",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the custom field",
"example": "Priority"
},
"showOnFrontOfCard": {
"type": "boolean",
"description": "Whether to show the field on the front of cards",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Custom field created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomField"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/custom-field-groups/{customFieldGroupId}/custom-fields": {
"post": {
"summary": "Create custom field in custom field group",
"description": "Creates a custom field within a custom field group. Requires board editor permissions.",
"tags": [
"Custom Fields"
],
"operationId": "createCustomFieldInGroup",
"parameters": [
{
"name": "customFieldGroupId",
"in": "path",
"required": true,
"description": "ID of the custom field group to create the custom field in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"position",
"name"
],
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the custom field within the group",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the custom field",
"example": "Priority"
},
"showOnFrontOfCard": {
"type": "boolean",
"description": "Whether to show the field on the front of cards",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Custom field created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomField"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/custom-fields/{id}": {
"delete": {
"summary": "Delete custom field",
"description": "Deletes a custom field. Can delete the in base custom field group (requires project manager permissions) or the custom field group (requires board editor permissions).",
"tags": [
"Custom Fields"
],
"operationId": "deleteCustomField",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the custom field to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Custom field deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomField"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update custom field",
"description": "Updates a custom field. Can update in the base custom field group (requires project manager permissions) or the custom field group (requires board editor permissions).",
"tags": [
"Custom Fields"
],
"operationId": "updateCustomField",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the custom field to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the custom field within the group",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the custom field",
"example": "Priority"
},
"showOnFrontOfCard": {
"type": "boolean",
"description": "Whether to show the field on the front of cards",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Custom field updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/CustomField"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/boards/{boardId}/labels": {
"post": {
"summary": "Create label",
"description": "Creates a label within a board. Requires board editor permissions.",
"tags": [
"Labels"
],
"operationId": "createLabel",
"parameters": [
{
"name": "boardId",
"in": "path",
"required": true,
"description": "ID of the board to create the label in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"position",
"color"
],
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the label within the board",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Name/title of the label",
"example": "Bug"
},
"color": {
"type": "string",
"enum": [
"muddy-grey",
"autumn-leafs",
"morning-sky",
"antique-blue",
"egg-yellow",
"desert-sand",
"dark-granite",
"fresh-salad",
"lagoon-blue",
"midnight-blue",
"light-orange",
"pumpkin-orange",
"light-concrete",
"sunny-grass",
"navy-blue",
"lilac-eyes",
"apricot-red",
"orange-peel",
"silver-glint",
"bright-moss",
"deep-ocean",
"summer-sky",
"berry-red",
"light-cocoa",
"grey-stone",
"tank-green",
"coral-green",
"sugar-plum",
"pink-tulip",
"shady-rust",
"wet-rock",
"wet-moss",
"turquoise-sea",
"lavender-fields",
"piggy-red",
"light-mud",
"gun-metal",
"modern-green",
"french-coast",
"sweet-lilac",
"red-burgundy",
"pirate-gold"
],
"description": "Color of the label",
"example": "berry-red"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Label created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Label"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/labels/{id}": {
"delete": {
"summary": "Delete label",
"description": "Deletes a label. Requires board editor permissions.",
"tags": [
"Labels"
],
"operationId": "deleteLabel",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the label to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Label deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Label"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update label",
"description": "Updates a label. Requires board editor permissions.",
"tags": [
"Labels"
],
"operationId": "updateLabel",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the label to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the label within the board",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Name/title of the label",
"example": "Bug"
},
"color": {
"type": "string",
"enum": [
"muddy-grey",
"autumn-leafs",
"morning-sky",
"antique-blue",
"egg-yellow",
"desert-sand",
"dark-granite",
"fresh-salad",
"lagoon-blue",
"midnight-blue",
"light-orange",
"pumpkin-orange",
"light-concrete",
"sunny-grass",
"navy-blue",
"lilac-eyes",
"apricot-red",
"orange-peel",
"silver-glint",
"bright-moss",
"deep-ocean",
"summer-sky",
"berry-red",
"light-cocoa",
"grey-stone",
"tank-green",
"coral-green",
"sugar-plum",
"pink-tulip",
"shady-rust",
"wet-rock",
"wet-moss",
"turquoise-sea",
"lavender-fields",
"piggy-red",
"light-mud",
"gun-metal",
"modern-green",
"french-coast",
"sweet-lilac",
"red-burgundy",
"pirate-gold"
],
"description": "Color of the label",
"example": "berry-red"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Label updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Label"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/lists/{id}/clear": {
"post": {
"summary": "Clear list",
"description": "Deletes all cards from a list. Only works with trash-type lists. Requires project manager or board editor permissions.",
"tags": [
"Lists"
],
"operationId": "clearList",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the list to clear (must be a trash-type list)",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "List cleared successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/List"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/boards/{boardId}/lists": {
"post": {
"summary": "Create list",
"description": "Creates a list within a board. Requires board editor permissions.",
"tags": [
"Lists"
],
"operationId": "createList",
"parameters": [
{
"name": "boardId",
"in": "path",
"required": true,
"description": "ID of the board to create the list in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"type",
"position",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"active",
"closed"
],
"description": "Type/status of the list",
"example": "active"
},
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the list within the board",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the list",
"example": "To Do"
}
}
}
}
}
},
"responses": {
"200": {
"description": "List created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/List"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/lists/{id}": {
"delete": {
"summary": "Delete list",
"description": "Deletes a list and moves its cards to a trash list. Can only delete finite lists. Requires board editor permissions.",
"tags": [
"Lists"
],
"operationId": "deleteList",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the list to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "List deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/List"
},
"included": {
"type": "object",
"required": [
"cards"
],
"properties": {
"cards": {
"type": "array",
"description": "Related cards",
"items": {
"$ref": "#/components/schemas/Card"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"get": {
"summary": "Get list details",
"description": "Retrieves comprehensive list information, including cards, attachments, and other related data. Requires access to the board.",
"tags": [
"Lists"
],
"operationId": "getList",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the list to retrieve",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "List details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/List"
},
"included": {
"type": "object",
"required": [
"users",
"cards",
"cardMemberships",
"cardLabels",
"taskLists",
"tasks",
"attachments",
"customFieldGroups",
"customFields",
"customFieldValues"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
},
"cards": {
"type": "array",
"description": "Related cards",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Card"
},
{
"type": "object",
"properties": {
"isSubscribed": {
"type": "boolean",
"description": "Whether the current user is subscribed to the card",
"example": true
}
}
}
]
}
},
"cardMemberships": {
"type": "array",
"description": "Related card-membership associations",
"items": {
"$ref": "#/components/schemas/CardMembership"
}
},
"cardLabels": {
"type": "array",
"description": "Related card-label associations",
"items": {
"$ref": "#/components/schemas/CardLabel"
}
},
"taskLists": {
"type": "array",
"description": "Related task lists",
"items": {
"$ref": "#/components/schemas/TaskList"
}
},
"tasks": {
"type": "array",
"description": "Related tasks",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"attachments": {
"type": "array",
"description": "Related attachments",
"items": {
"$ref": "#/components/schemas/Attachment"
}
},
"customFieldGroups": {
"type": "array",
"description": "Related custom field groups",
"items": {
"$ref": "#/components/schemas/CustomFieldGroup"
}
},
"customFields": {
"type": "array",
"description": "Related custom fields",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"customFieldValues": {
"type": "array",
"description": "Related custom field values",
"items": {
"$ref": "#/components/schemas/CustomFieldValue"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update list",
"description": "Updates a list. Can move lists between boards. Requires board editor permissions.",
"tags": [
"Lists"
],
"operationId": "updateList",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the list to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"boardId": {
"type": "string",
"description": "ID of the board to move list to",
"example": "1357158568008091265"
},
"type": {
"type": "string",
"enum": [
"active",
"closed"
],
"description": "Type/status of the list",
"example": "active"
},
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the list within the board",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the list",
"example": "To Do"
},
"color": {
"type": "string",
"enum": [
"berry-red",
"pumpkin-orange",
"lagoon-blue",
"pink-tulip",
"light-mud",
"orange-peel",
"bright-moss",
"antique-blue",
"dark-granite",
"turquoise-sea"
],
"nullable": true,
"description": "Color for the list",
"example": "lagoon-blue"
}
}
}
}
}
},
"responses": {
"200": {
"description": "List updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/List"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/lists/{id}/move-cards": {
"post": {
"summary": "Move cards",
"description": "Moves all cards from a closed list to an archive list. Requires board editor permissions.",
"tags": [
"Lists"
],
"operationId": "moveListCards",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the source list (must be a closed-type list)",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"listId"
],
"properties": {
"listId": {
"type": "string",
"description": "ID of the target list (must be an archive-type list)",
"example": "1357158568008091265"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Cards moved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/List"
},
"included": {
"type": "object",
"required": [
"cards",
"actions"
],
"properties": {
"cards": {
"type": "array",
"description": "Related cards",
"items": {
"$ref": "#/components/schemas/Card"
}
},
"actions": {
"type": "array",
"description": "Related actions",
"items": {
"$ref": "#/components/schemas/Action"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/lists/{id}/sort": {
"post": {
"summary": "Sort cards in list",
"description": "Sorts all cards within a list. Requires board editor permissions.",
"tags": [
"Lists"
],
"operationId": "sortList",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the list to sort",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"fieldName"
],
"properties": {
"fieldName": {
"type": "string",
"enum": [
"name",
"dueDate",
"createdAt"
],
"description": "Field to sort cards by",
"example": "name"
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sorting order",
"example": "asc"
}
}
}
}
}
},
"responses": {
"200": {
"description": "List sorted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/List"
},
"included": {
"type": "object",
"properties": {
"cards": {
"type": "array",
"description": "Related cards",
"items": {
"$ref": "#/components/schemas/Card"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/boards/{boardId}/notification-services": {
"post": {
"summary": "Create notification service for board",
"description": "Creates a new notification service for a board. Requires project manager permissions.",
"tags": [
"Notification Services"
],
"operationId": "createBoardNotificationService",
"parameters": [
{
"name": "boardId",
"in": "path",
"required": true,
"description": "ID of the board to create notification service for",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url",
"format"
],
"properties": {
"url": {
"type": "string",
"maxLength": 512,
"description": "URL endpoint for notifications",
"example": "https://service.example.com/planka"
},
"format": {
"type": "string",
"enum": [
"text",
"markdown",
"html"
],
"description": "Format for notification messages",
"example": "text"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Notification service created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/NotificationService"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/users/{userId}/notification-services": {
"post": {
"summary": "Create notification service for user",
"description": "Creates a new notification service for a user. Users can only create services for themselves.",
"tags": [
"Notification Services"
],
"operationId": "createUserNotificationService",
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"description": "ID of the user to create notification service for (must be the current user)",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url",
"format"
],
"properties": {
"url": {
"type": "string",
"maxLength": 512,
"description": "URL endpoint for notifications",
"example": "https://service.example.com/planka"
},
"format": {
"type": "string",
"enum": [
"text",
"markdown",
"html"
],
"description": "Format for notification messages",
"example": "text"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Notification service created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/NotificationService"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/notification-services/{id}": {
"delete": {
"summary": "Delete notification service",
"description": "Deletes a notification service. Users can delete their own services, project managers can delete board services.",
"tags": [
"Notification Services"
],
"operationId": "deleteNotificationService",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the notification service to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Notification service deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/NotificationService"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update notification service",
"description": "Updates a notification service. Users can update their own services, project managers can update board services.",
"tags": [
"Notification Services"
],
"operationId": "updateNotificationService",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the notification service to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"maxLength": 512,
"description": "URL endpoint for notifications",
"example": "https://service.example.com/planka"
},
"format": {
"type": "string",
"enum": [
"text",
"markdown",
"html"
],
"description": "Format for notification messages",
"example": "text"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Notification service updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/NotificationService"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/notification-services/{id}/test": {
"post": {
"summary": "Test notification service",
"description": "Sends a test notification to verify the notification service is working. Users can test their own services, project managers can test board services.",
"tags": [
"Notification Services"
],
"operationId": "testNotificationService",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the notification service to test",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Test notification sent successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/NotificationService"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/notifications": {
"get": {
"summary": "Get user notifications",
"description": "Retrieves all unread notifications for the current user, including creator users.",
"tags": [
"Notifications"
],
"operationId": "getNotifications",
"responses": {
"200": {
"description": "Notifications retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items",
"included"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Notification"
}
},
"included": {
"type": "object",
"required": [
"users"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/notifications/read-all": {
"post": {
"summary": "Mark all notifications as read",
"description": "Marks all notifications for the current user as read.",
"tags": [
"Notifications"
],
"operationId": "readAllNotifications",
"responses": {
"200": {
"description": "Notifications marked as read successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Notification"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/notifications/{id}": {
"get": {
"summary": "Get notification details",
"description": "Retrieves notification, including creator users. Users can only access their own notifications.",
"tags": [
"Notifications"
],
"operationId": "getNotification",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the notification to retrieve",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Notification details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Notification"
},
"included": {
"type": "object",
"required": [
"users"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update notification",
"description": "Updates a notification. Users can only update their own notifications.",
"tags": [
"Notifications"
],
"operationId": "updateNotification",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the notification to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"isRead": {
"type": "boolean",
"description": "Whether the notification has been read",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Notification updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Notification"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/projects/{projectId}/project-managers": {
"post": {
"summary": "Create project manager",
"description": "Creates a project manager within a project. Requires admin privileges for shared projects or existing project manager permissions. The user must be an admin or project owner.",
"tags": [
"Project Managers"
],
"operationId": "createProjectManager",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"description": "ID of the project to create the project manager in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"userId"
],
"properties": {
"userId": {
"type": "string",
"description": "ID of the user who is assigned as project manager",
"example": "1357158568008091265"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Project manager created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/ProjectManager"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/project-managers/{id}": {
"delete": {
"summary": "Delete project manager",
"description": "Deletes a project manager. Requires admin privileges for shared projects or existing project manager permissions. Cannot remove the last project manager.",
"tags": [
"Project Managers"
],
"operationId": "deleteProjectManager",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the project manager to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Project manager deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/ProjectManager"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/projects": {
"post": {
"summary": "Create project",
"description": "Creates a project. The current user automatically becomes a project manager.",
"tags": [
"Projects"
],
"operationId": "createProject",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"public",
"private"
],
"description": "Type of the project",
"example": "private"
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the project",
"example": "Development Project"
},
"description": {
"type": "string",
"maxLength": 1024,
"nullable": true,
"description": "Detailed description of the project",
"example": "A project for developing new features..."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Project created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Project"
},
"included": {
"type": "object",
"required": [
"projectManagers"
],
"properties": {
"projectManagers": {
"type": "array",
"description": "Related project managers",
"items": {
"$ref": "#/components/schemas/ProjectManager"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
},
"get": {
"summary": "Get all accessible projects",
"description": "Retrieves all projects the current user has access to, including managed projects, membership projects, and shared projects (for admins).",
"tags": [
"Projects"
],
"operationId": "getProjects",
"responses": {
"200": {
"description": "Projects retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items",
"included"
],
"properties": {
"items": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Project"
},
{
"type": "object",
"properties": {
"isFavorite": {
"type": "boolean",
"description": "Whether the project is marked as favorite by the current user",
"example": true
}
}
}
]
}
},
"included": {
"type": "object",
"required": [
"users",
"projectManagers",
"backgroundImages",
"baseCustomFieldGroups",
"boards",
"boardMemberships",
"customFields",
"notificationServices"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
},
"projectManagers": {
"type": "array",
"description": "Related project managers",
"items": {
"$ref": "#/components/schemas/ProjectManager"
}
},
"backgroundImages": {
"type": "array",
"description": "Related background images",
"items": {
"$ref": "#/components/schemas/BackgroundImage"
}
},
"baseCustomFieldGroups": {
"type": "array",
"description": "Related base custom field groups",
"items": {
"$ref": "#/components/schemas/BaseCustomFieldGroup"
}
},
"boards": {
"type": "array",
"description": "Related boards",
"items": {
"$ref": "#/components/schemas/Board"
}
},
"boardMemberships": {
"type": "array",
"description": "Related board memberships (for current user)",
"items": {
"$ref": "#/components/schemas/BoardMembership"
}
},
"customFields": {
"type": "array",
"description": "Related custom fields",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"notificationServices": {
"type": "array",
"description": "Related notification services (for managed projects)",
"items": {
"$ref": "#/components/schemas/NotificationService"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/projects/{id}": {
"delete": {
"summary": "Delete project",
"description": "Deletes a project. The project must not have any boards. Requires project manager permissions.",
"tags": [
"Projects"
],
"operationId": "deleteProject",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the project to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Project deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Project"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"get": {
"summary": "Get project details",
"description": "Retrieves comprehensive project information, including boards, board memberships, and other related data.",
"tags": [
"Projects"
],
"operationId": "getProject",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the project to retrieve",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Project details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"allOf": [
{
"$ref": "#/components/schemas/Project"
},
{
"type": "object",
"properties": {
"isFavorite": {
"type": "boolean",
"description": "Whether the project is marked as favorite by the current user",
"example": true
}
}
}
]
},
"included": {
"type": "object",
"required": [
"users",
"projectManagers",
"backgroundImages",
"baseCustomFieldGroups",
"boards",
"boardMemberships",
"customFields",
"notificationServices"
],
"properties": {
"users": {
"type": "array",
"description": "Related users",
"items": {
"$ref": "#/components/schemas/User"
}
},
"projectManagers": {
"type": "array",
"description": "Related project managers",
"items": {
"$ref": "#/components/schemas/ProjectManager"
}
},
"backgroundImages": {
"type": "array",
"description": "Related background images",
"items": {
"$ref": "#/components/schemas/BackgroundImage"
}
},
"baseCustomFieldGroups": {
"type": "array",
"description": "Related base custom field groups",
"items": {
"$ref": "#/components/schemas/BaseCustomFieldGroup"
}
},
"boards": {
"type": "array",
"description": "Related boards",
"items": {
"$ref": "#/components/schemas/Board"
}
},
"boardMemberships": {
"type": "array",
"description": "Related board memberships (for current user)",
"items": {
"$ref": "#/components/schemas/BoardMembership"
}
},
"customFields": {
"type": "array",
"description": "Related custom fields",
"items": {
"$ref": "#/components/schemas/CustomField"
}
},
"notificationServices": {
"type": "array",
"description": "Related notification services (for managed projects)",
"items": {
"$ref": "#/components/schemas/NotificationService"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update project",
"description": "Updates a project. Accessible fields depend on user permissions.",
"tags": [
"Projects"
],
"operationId": "updateProject",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the project to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ownerProjectManagerId": {
"type": "string",
"nullable": true,
"description": "ID of the project manager who owns the project",
"example": "1357158568008091265"
},
"backgroundImageId": {
"type": "string",
"nullable": true,
"description": "ID of the background image used as background",
"example": "1357158568008091266"
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the project",
"example": "Development Project"
},
"description": {
"type": "string",
"maxLength": 1024,
"nullable": true,
"description": "Detailed description of the project",
"example": "A project for developing new features..."
},
"backgroundType": {
"type": "string",
"enum": [
"gradient",
"image"
],
"nullable": true,
"description": "Type of background for the project",
"example": "gradient"
},
"backgroundGradient": {
"type": "string",
"enum": [
"old-lime",
"ocean-dive",
"tzepesch-style",
"jungle-mesh",
"strawberry-dust",
"purple-rose",
"sun-scream",
"warm-rust",
"sky-change",
"green-eyes",
"blue-xchange",
"blood-orange",
"sour-peel",
"green-ninja",
"algae-green",
"coral-reef",
"steel-grey",
"heat-waves",
"velvet-lounge",
"purple-rain",
"blue-steel",
"blueish-curve",
"prism-light",
"green-mist",
"red-curtain"
],
"nullable": true,
"description": "Gradient background for the project",
"example": "ocean-dive"
},
"isHidden": {
"type": "boolean",
"description": "Whether the project is hidden",
"example": false
},
"isFavorite": {
"type": "boolean",
"description": "Whether the project is marked as favorite by the current user",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Project updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Project"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/cards/{cardId}/task-lists": {
"post": {
"summary": "Create task list",
"description": "Creates a task list within a card. Requires board editor permissions.",
"tags": [
"Task Lists"
],
"operationId": "createTaskList",
"parameters": [
{
"name": "cardId",
"in": "path",
"required": true,
"description": "ID of the card to create task list in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"position",
"name"
],
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the task list within the card",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the task list",
"example": "Development Tasks"
},
"showOnFrontOfCard": {
"type": "boolean",
"description": "Whether to show the task list on the front of the card",
"example": true
},
"hideCompletedTasks": {
"type": "boolean",
"description": "Whether to hide completed tasks",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Task list created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/TaskList"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/task-lists/{id}": {
"delete": {
"summary": "Delete task list",
"description": "Deletes a task list and all its tasks. Requires board editor permissions.",
"tags": [
"Task Lists"
],
"operationId": "deleteTaskList",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the task list to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Task list deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/TaskList"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"get": {
"summary": "Get task list details",
"description": "Retrieves task list information, including tasks. Requires access to the card.",
"tags": [
"Task Lists"
],
"operationId": "getTaskList",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the task list to retrieve",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Task list details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/TaskList"
},
"included": {
"type": "object",
"required": [
"tasks"
],
"properties": {
"tasks": {
"type": "array",
"description": "Related tasks",
"items": {
"$ref": "#/components/schemas/Task"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update task list",
"description": "Updates a task list. Requires board editor permissions.",
"tags": [
"Task Lists"
],
"operationId": "updateTaskList",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the task list to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the task list within the card",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the task list",
"example": "Development Tasks"
},
"showOnFrontOfCard": {
"type": "boolean",
"description": "Whether to show the task list on the front of the card",
"example": true
},
"hideCompletedTasks": {
"type": "boolean",
"description": "Whether to hide completed tasks",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Task list updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/TaskList"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/task-lists/{taskListId}/tasks": {
"post": {
"summary": "Create task",
"description": "Creates a task within a task list. Either `linkedCardId` or `name` must be provided. Requires board editor permissions.",
"tags": [
"Tasks"
],
"operationId": "createTask",
"parameters": [
{
"name": "taskListId",
"in": "path",
"required": true,
"description": "ID of the task list to create task in",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"position"
],
"properties": {
"linkedCardId": {
"type": "string",
"description": "ID of the card linked to the task",
"example": "1357158568008091265"
},
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the task within the task list",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 1024,
"nullable": true,
"description": "Name/title of the task (required if `linkedCardId` is not provided)",
"example": "Write unit tests"
},
"isCompleted": {
"type": "boolean",
"description": "Whether the task is completed",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Task created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Task"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/tasks/{id}": {
"delete": {
"summary": "Delete task",
"description": "Deletes a task. Requires board editor permissions.",
"tags": [
"Tasks"
],
"operationId": "deleteTask",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the task to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Task deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Task"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update task",
"description": "Updates a task. Linked card tasks have limited update options. Requires board editor permissions.",
"tags": [
"Tasks"
],
"operationId": "updateTask",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the task to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"taskListId": {
"type": "string",
"description": "ID of the task list to move the task to",
"example": "1357158568008091265"
},
"assigneeUserId": {
"type": "string",
"nullable": true,
"description": "ID of the user assigned to the task (null to unassign)",
"example": "1357158568008091266"
},
"position": {
"type": "number",
"minimum": 0,
"description": "Position of the task within the task list",
"example": 65536
},
"name": {
"type": "string",
"maxLength": 1024,
"description": "Name/title of the task",
"example": "Write unit tests"
},
"isCompleted": {
"type": "boolean",
"description": "Whether the task is completed",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Task updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Task"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/terms/{type}": {
"get": {
"summary": "Get terms and conditions",
"description": "Retrieves terms and conditions in the specified language.",
"tags": [
"Terms"
],
"operationId": "getTerms",
"parameters": [
{
"name": "type",
"in": "path",
"required": true,
"description": "Type of terms to retrieve",
"schema": {
"type": "string",
"enum": [
"general",
"extended"
],
"example": "general"
}
},
{
"name": "language",
"in": "query",
"required": false,
"description": "Language code for terms localization",
"schema": {
"type": "string",
"enum": [
"de-DE",
"en-US"
],
"example": "en-US"
}
}
],
"responses": {
"200": {
"description": "Terms content retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"type": "object",
"required": [
"type",
"language",
"content",
"signature"
],
"properties": {
"type": {
"type": "string",
"enum": [
"general",
"extended"
],
"description": "Type of terms",
"example": "en-US"
},
"language": {
"type": "string",
"enum": [
"de-DE",
"en-US"
],
"description": "Language code used",
"example": "en-US"
},
"content": {
"type": "string",
"description": "Markdown content of the terms",
"example": "Your privacy is important to us..."
},
"signature": {
"type": "string",
"description": "Signature hash of terms",
"example": "940226c4c41f51afe3980ceb63704e752636526f4c52a4ea579e85b247493d94"
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": []
}
},
"/users": {
"post": {
"summary": "Create user",
"description": "Creates a user account. Requires admin privileges.",
"tags": [
"Users"
],
"operationId": "createUser",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email",
"password",
"role",
"name"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 256,
"description": "Email address for login and notifications",
"example": "john.doe@example.com"
},
"password": {
"type": "string",
"maxLength": 256,
"description": "Password for user authentication (must meet password requirements)",
"example": "SecurePassword123!"
},
"role": {
"type": "string",
"enum": [
"admin",
"projectOwner",
"boardUser"
],
"description": "User role defining access permissions",
"example": "admin"
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Full display name of the user",
"example": "John Doe"
},
"username": {
"type": "string",
"minLength": 3,
"maxLength": 16,
"pattern": "^[a-zA-Z0-9]+((_{1}|\\.|){1}[a-zA-Z0-9])*$",
"nullable": true,
"description": "Unique username for user identification",
"example": "john_doe"
},
"phone": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Contact phone number",
"example": 1234567890
},
"organization": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Organization or company name",
"example": "Acme Corporation"
},
"language": {
"type": "string",
"enum": [
"ar-YE",
"bg-BG",
"cs-CZ",
"da-DK",
"de-DE",
"el-GR",
"en-GB",
"en-US",
"es-ES",
"et-EE",
"fa-IR",
"fi-FI",
"fr-FR",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ko-KR",
"nl-NL",
"pl-PL",
"pt-BR",
"pt-PT",
"ro-RO",
"ru-RU",
"sk-SK",
"sr-Cyrl-RS",
"sr-Latn-RS",
"sv-SE",
"tr-TR",
"uk-UA",
"uz-UZ",
"zh-CN",
"zh-TW"
],
"nullable": true,
"description": "Preferred language for user interface and notifications",
"example": "en-US"
},
"subscribeToOwnCards": {
"type": "boolean",
"description": "Whether the user subscribes to their own cards",
"example": false
},
"subscribeToCardWhenCommenting": {
"type": "boolean",
"description": "Whether the user subscribes to cards when commenting",
"example": true
},
"turnOffRecentCardHighlighting": {
"type": "boolean",
"description": "Whether recent card highlighting is disabled",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "User created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
},
"get": {
"summary": "Get all users",
"description": "Retrieves a list of all users. Requires admin or project owner privileges.",
"tags": [
"Users"
],
"operationId": "getUsers",
"responses": {
"200": {
"description": "List of users retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/users/{id}": {
"delete": {
"summary": "Delete user",
"description": "Deletes a user account. Cannot delete the default admin user. Requires admin privileges.",
"tags": [
"Users"
],
"operationId": "deleteUser",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the user to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "User deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"get": {
"summary": "Get user details",
"description": "Retrieves a user. Use 'me' as ID to get the current user.",
"tags": [
"Users"
],
"operationId": "getUser",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the user or 'me' for current user",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
},
{
"name": "subscribe",
"in": "query",
"required": false,
"description": "Whether to subscribe to real-time updates for this user (only for socket connections)",
"schema": {
"type": "boolean",
"example": true
}
}
],
"responses": {
"200": {
"description": "User details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item",
"included"
],
"properties": {
"item": {
"$ref": "#/components/schemas/User"
},
"included": {
"type": "object",
"required": [
"notificationServices"
],
"properties": {
"notificationServices": {
"type": "array",
"description": "Related notification services (for current user)",
"items": {
"$ref": "#/components/schemas/NotificationService"
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update user",
"description": "Updates a user. Users can update their own profile, admins can update any user.",
"tags": [
"Users"
],
"operationId": "updateUser",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the user to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"admin",
"projectOwner",
"boardUser"
],
"description": "User role defining access permissions",
"example": "admin"
},
"name": {
"type": "string",
"maxLength": 128,
"description": "Full display name of the user",
"example": "John Doe"
},
"avatar": {
"type": "object",
"nullable": true,
"description": "Avatar of the user (only null value to remove avatar)",
"example": null
},
"phone": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Contact phone number",
"example": 1234567890
},
"organization": {
"type": "string",
"maxLength": 128,
"nullable": true,
"description": "Organization or company name",
"example": "Acme Corporation"
},
"language": {
"type": "string",
"enum": [
"ar-YE",
"bg-BG",
"cs-CZ",
"da-DK",
"de-DE",
"el-GR",
"en-GB",
"en-US",
"es-ES",
"et-EE",
"fa-IR",
"fi-FI",
"fr-FR",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ko-KR",
"nl-NL",
"pl-PL",
"pt-BR",
"pt-PT",
"ro-RO",
"ru-RU",
"sk-SK",
"sr-Cyrl-RS",
"sr-Latn-RS",
"sv-SE",
"tr-TR",
"uk-UA",
"uz-UZ",
"zh-CN",
"zh-TW"
],
"nullable": true,
"description": "Preferred language for user interface and notifications",
"example": "en-US"
},
"subscribeToOwnCards": {
"type": "boolean",
"description": "Whether the user subscribes to their own cards",
"example": false
},
"subscribeToCardWhenCommenting": {
"type": "boolean",
"description": "Whether the user subscribes to cards when commenting",
"example": true
},
"turnOffRecentCardHighlighting": {
"type": "boolean",
"description": "Whether recent card highlighting is disabled",
"example": false
},
"enableFavoritesByDefault": {
"type": "boolean",
"description": "Whether favorites are enabled by default",
"example": false
},
"defaultEditorMode": {
"type": "string",
"enum": [
"wysiwyg",
"markup"
],
"description": "Default markdown editor mode",
"example": "wysiwyg"
},
"defaultHomeView": {
"type": "string",
"enum": [
"gridProjects",
"groupedProjects"
],
"description": "Default view mode for the home page",
"example": "groupedProjects"
},
"defaultProjectsOrder": {
"type": "string",
"enum": [
"byDefault",
"alphabetically",
"byCreationTime"
],
"description": "Default sort order for projects display",
"example": "byDefault"
},
"isDeactivated": {
"type": "boolean",
"description": "Whether the user account is deactivated and cannot log in (for admins)",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "User updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/users/{id}/avatar": {
"post": {
"summary": "Update user avatar",
"description": "Updates a user's avatar image. Users can update their own avatar, admins can update any user's avatar.",
"tags": [
"Users"
],
"operationId": "updateUserAvatar",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the user whose avatar to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "Avatar image file (must be an image format)"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Avatar updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/users/{id}/email": {
"patch": {
"summary": "Update user email",
"description": "Updates a user's email address. Users must provide current password when updating their own email. Admins can update any user's email without a password.",
"tags": [
"Users"
],
"operationId": "updateUserEmail",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "ID of the user whose email to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 256,
"description": "Email address for login and notifications",
"example": "john.doe@example.com"
},
"currentPassword": {
"type": "string",
"maxLength": 256,
"description": "Current password (required when updating own email)",
"example": "SecurePassword123!"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Email updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/users/{id}/password": {
"patch": {
"summary": "Update user password",
"description": "Updates a user's password. Users must provide a current password when updating their own password. Admins can update any user's password without the current password. Returns a new access token when updating own password.",
"tags": [
"Users"
],
"operationId": "updateUserPassword",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "ID of the user whose password to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"password"
],
"properties": {
"password": {
"type": "string",
"maxLength": 256,
"description": "Password (must meet password requirements)",
"example": "SecurePassword123!"
},
"currentPassword": {
"type": "string",
"maxLength": 256,
"description": "Current password (required when updating own password)",
"example": "SecurePassword456!"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Password updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/User"
},
"included": {
"type": "object",
"required": [
"accessTokens"
],
"properties": {
"accessTokens": {
"type": "array",
"description": "New acces tokens (when updating own password)",
"items": {
"type": "string",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4..."
}
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/users/{id}/username": {
"patch": {
"summary": "Update user username",
"description": "Updates a user's username. Users must provide a current password when updating their own username (unless they are SSO users with `oidcIgnoreUsername` enabled). Admins can update any user's username without the current password.",
"tags": [
"Users"
],
"operationId": "updateUserUsername",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "ID of the user whose username to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"username": {
"type": "string",
"minLength": 3,
"maxLength": 16,
"pattern": "^[a-zA-Z0-9]+((_|\\.)?[a-zA-Z0-9])*$",
"nullable": true,
"description": "Unique username for user identification",
"example": "john_doe"
},
"currentPassword": {
"type": "string",
"maxLength": 256,
"description": "Current password (required when updating own username)",
"example": "SecurePassword123!"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Username updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
}
},
"/webhooks": {
"post": {
"summary": "Create webhook",
"description": "Creates a webhook. Requires admin privileges.",
"tags": [
"Webhooks"
],
"operationId": "createWebhook",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the webhook",
"example": "Webhook Updates"
},
"url": {
"type": "string",
"format": "url",
"maxLength": 2048,
"description": "URL endpoint for the webhook",
"example": "https://service.example.com/planka"
},
"accessToken": {
"type": "string",
"maxLength": 512,
"nullable": true,
"description": "Access token for webhook authentication",
"example": "secret_token_123"
},
"events": {
"type": "string",
"maxLength": 2048,
"nullable": true,
"description": "Comma-separated list of events that trigger the webhook",
"example": "cardCreate,cardUpdate,cardDelete"
},
"excludedEvents": {
"type": "string",
"maxLength": 2048,
"nullable": true,
"description": "Comma-separated list of events excluded from the webhook",
"example": "userCreate,userUpdate,userDelete"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
},
"get": {
"summary": "Get all webhooks",
"description": "Retrieves a list of all configured webhooks. Requires admin privileges.",
"tags": [
"Webhooks"
],
"operationId": "getWebhooks",
"responses": {
"200": {
"description": "List of webhooks retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/webhooks/{id}": {
"delete": {
"summary": "Delete webhook",
"description": "Deletes a webhook. Requires admin privileges.",
"tags": [
"Webhooks"
],
"operationId": "deleteWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the webhook to delete",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"responses": {
"200": {
"description": "Webhook deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"patch": {
"summary": "Update webhook",
"description": "Updates a webhook. Requires admin privileges.",
"tags": [
"Webhooks"
],
"operationId": "updateWebhook",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the webhook to update",
"schema": {
"type": "string",
"example": "1357158568008091264"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"description": "Name/title of the webhook",
"example": "Webhook Updates"
},
"url": {
"type": "string",
"format": "url",
"maxLength": 2048,
"description": "URL endpoint for the webhook",
"example": "https://service.example.com/planka"
},
"accessToken": {
"type": "string",
"maxLength": 512,
"nullable": true,
"description": "Access token for webhook authentication",
"example": "secret_token_123"
},
"events": {
"type": "string",
"maxLength": 2048,
"nullable": true,
"description": "Comma-separated list of events that trigger the webhook",
"example": "cardCreate,cardUpdate,cardDelete"
},
"excludedEvents": {
"type": "string",
"maxLength": 2048,
"nullable": true,
"description": "Comma-separated list of events excluded from the webhook",
"example": "userCreate,userUpdate,userDelete"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"item"
],
"properties": {
"item": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
}
},
"tags": []
}
Reference in New Issue View Git Blame Copy Permalink