{ "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": [] }