{ "openapi": "3.0.2", "info": { "title": "Klaro Cards API", "description": "# Introduction\n\nWelcome to the Klaro Cards API documentation. If you have experience with\nRESTFul APIs, you should not be surprised.\n\nMake sure you read the [About Klaro Cards](#about-klaro-cards) section\nthat contains important information about the various Klaro Cards concepts\nand the way they are represented on the API.\n\n## API Version and Stability\n\nThe API is a V1 ; it's the version of the API used by the Klaro Cards desktop\nand mobile applications. It has been designed as a decent RESTFul API, but\nwith a main focus on the needs of those applications.\n\nWe make a strong effort to make the API stable and backward compatible for\nseveral years ahead. In particular, we adopt the following practices:\n\n- Resources (urls) and Verbs may be deprecated, but won't be removed in V1\n- Fields can be added to resources, but never removed\n- We make a strong effort not to change the semantics attached to fields\n\nPlease reach the technical team with suggestions or to get help. You can either\nuse [support@klaro.cards](support@klaro.cards) or reach us on social networks.\n\n## API Endpoints\n\n```curl\n# GET stories on the project hosted at helloworld.klaro.cards and board all\ncurl \\\n -H \"Authorization: Bearer ...\"\n -H \"Accept: application/json\"\n -H \"X-Klaro-Project-Subdomain: helloworld\"\n -H \"X-Klaro-ViewAs: admins\"\n -X GET\n https://api.klaro.cards/v1/boards/all/stories/\n```\n\nYou typically use the API against :\n\n- a specific Klaro Cards `instance`, typically the public cloud hosted under `klaro.cards`\n- within the context of a given Klaro Cards `project`, hosted on a subdomain of the instance\n- a specific version, `v1` for now\n\nGiven an instance, say `klaro.cards`, you have two possible endpoints :\n\n- Either use, `https://api.klaro.cards/v1/` and specify the project via the headers below\n- Or use `https://yourproject.klaro.cards/api/v1/` and skip the project header.\n\nIf your company bought or runs a dedicated instance, simply replace `klaro.cards` above\nby domain of your instance, e.g. `mycompany.klaro.cards`, or `klaro.yourcompany.com`.\n\n## Test or Sandbox\n\nThere are ways to use the API for tests :\n\n1. Either duplicate your project in Klaro Cards (see the Danger zone of the Settings screen)\n and run your tests against that project.\n\n2. Use the [`staging.klaro.cards` instance](https://app.staging.klaro.cards). You can create\n temporary projects and use the API on them. Note that the staging instance can be redeployed\n and its database reset at any time.\n\n## HTTP Headers\n\nMost resources require an authorization token. See the [Authentication section](#authentication)\nand the [`POST /auth/tokens/`](#create-token) service for details. If you use public boards, data\nabout boards and their cards will be served without requiring any such token/header, though.\n\nMore generally, the following headers are supported. Some of them may be required according to\nthe endpoint and service you use.\n\nHeader | Semantics\n------ | ---------\n`X-Klaro-Project-Id` | The UUID of the project you want to manipulate via the API\n`X-Klaro-Project-Subdomain` | A human friendly alternative to specify the project\n`X-Klaro-ViewAs` | A specific workspace to use if your user belongs to many workspaces\n`Authorization` | A valid Authorization token obtained via `POST /auth/tokens`\n`Content-Type` | The content type of the input data on non-GET requests (use `application/json`)\n`Accept` | The content type of the output data (use `application/json`)\n\n## Verbs and semantics\n\nThe API consistently uses the following HTTP Verb conventions :\n\nVerb | URL of | Description | Idempotent |\n------ | ------ | ----------- | ---------- |\nGET | Resource & Collection | Get the representation of the resource or collection | Yes\nPOST | Collection | Create a new resource or bunch of resources in the collection | No\nPOST | Action | Execute the resource action | No\nPATCH | Resource | Update a resource via a representation patch | No\nDELETE | Resource | Delete the resource | No\nDELETE | Collection | Delete some or all resources in the collection | No\n\nNote that `PATCH` and `DELETE` are not idempotent as sometimes suggested by RESTful. Notably,\ntrying to delete an already deleted resource will return a 404.\n\n## Resource, Collection, Patch\n\n```typescript\n// This could be a card resource\n{ id: \"...\", title: \"Hello world\", progress: \"todo\" }\n\n// This is a collection of cards\n[\n { id: \"...\", title: \"Hello world\", progress: \"todo\" },\n { id: \"...\", title: \"And all developers there\", progress: \"done\" },\n]\n\n// This is a card patch\n{ progress: \"abandonned\" }\n```\n\nThe V1 API uses simple and unconvoluted/flat representations for Resources and Collections.\nThat is, most web services simply follow the following conventions :\n\n- Resources are represented as Plain Old Json Objects (POJO)\n- Collections are arrays of POJOs\n- A resource patch is a subset of its POJO\n\nMost services accept and serve `application/json`.\nSome of them also support other content types, notably `text/csv`.\n\n## Pagination\n\nThe API does not support pagination for now. Favor filters.\n\nWe know, it's a big short for an API, we're still working on it. If that's blocking\nfor your use case, reach us immediately.\n\n## Common success codes\n\nThe API uses the following codes on successful requests :\n\nSuccess Code | Name | Reason\n---------- | ---- | ------\n200 | OK | Your request is valid, the representation/data can be found in body\n201 | Created | A resource has been created, it's representation can be found in body\n204 | No Content | The request has been executed but no data or representation is returned.\n\n## Common error codes\n\nThe following error codes may be observed on all services. We make a strong effort\nto use their semantics where applicable.\n\nAll 4xx errors have a body with error details encoded in JSON using the schema\nshown at right:\n\n```typescript\n// Error schema, with a unique code and description of the issue\n{\n code : String\n description : String\n}\n```\n\nError Code | Name | Reason\n---------- | ---- | ------\n400 | Bad Request | Your request is invalid ; typically your input data violates the input schema\n401 | Unauthorized | Your request is missing a token or the token is invalid or expired.\n403 | Forbidden | You don't have the necessary permissions for that action.\n404 | Not Found | The specified resource could not be found.\n406 | Not Acceptable Error | The `Accept` http header is missing or unrecognized.\n409 | Conflit Error | Your request is valid but ends up violating a data constraint.\n415 | Unsupported Media Type | The format of your input data cannot be used, check your `Content-Type` header.\n500 | Internal Server Error | We had a problem with our server. Try again later.\n501 | Not Implemented Error | You clearly use the API on an edge case we don't cover yet.\n503 | Service Unavailable | We're temporarily offline for maintenance. Please try again later.\n\n# About Klaro Cards\n\n## Core concepts\n\nThe API is structured around main Klaro Cards concepts :\n\n- `Projects`, which are independent databases of cards\n- `Cards`, formally called `Stories` on the API for historical reasons\n- `Dimensions`, that enrich cards with structured data and allow filtering them in boards\n- `Boards`, that select a subset of a cards and visualize them in a certain way\n- `Board cards`, that designate the subset of cards visible in a board given its filters.\n- `Danger zone`, which is the set of potentially destructive project actions\n\nThere are plenty of other resources of course, but that are considered second\nclass citizen according to Klaro Cards' core value proposition.\n\n## Conceptual model\n\n![](object-model.mermaid.png)\n\nWithin a Klaro Cards project, a board displays a subset of the project cards.\nA card has a few fixed fields, as well as fields contributed by the project dimensions.\nA Dimension has a list of values, that are used enrich the cards and install the\nboard filters.\n\n### Cards & Dimensions\n\n```typescript\n// Let's say you have the following card\n{\n id: \"...\",\n title: \"Hello world\",\n progress: \"todo\",\n // ...\n}\n\n// The following dimensions explains that representation:\n[\n {\n id: \"...\",\n code: \"title\",\n label: \"Card title\",\n datatype: \"Title\",\n // ...\n },\n {\n id: \"...\",\n code: \"progress\",\n label: \"Progress\",\n datatype: \"UserDefined\",\n values: [\n { id: \"todo\", label: \"Todo\" },\n { id: \"ongoing\", label: \"Ongoing\" },\n // ...\n ]\n },\n // ...\n]\n\n// A board showing ongoing cards will have the following filters :\n{\n id: \"...\",\n name: \"Ongoing tasks\",\n filters: {\n progress: [\"ongoing\"]\n }\n // ...\n}\n\n// A kanban board by progress, showing the assignee on cards will have the\n// folllowing anchors :\n{\n id: \"...\",\n name: \"Ongoing tasks\",\n anchors: {\n displayBy: [\"progress\"],\n cards: [\"assignee\"]\n }\n // ...\n}\n```\n\nThe cards fixed fields are `id`, `identifier`, `project`, `attachments`, and `linked`.\n\nSystem dimensions contribute the fields `title`, `specification` (aka card description),\n`createdAt`, `updatedAt`.\n\nAll other card fields are contributed by configurable dimensions. The rules simply are:\n\n- The field name is the dimension code\n- The field value is the id of a dimension value (unless the dimension captures a scalar, e.g. numbers and dates)\n\n### Board Filters & Anchors\n\nBoards use dimensions both for `filters` and for spacial organisation of cards (and more generally the user\ninterface) via `anchors`.\n\n- Filters currently capture a simple Conjunctive Normal Form over dimensions values. They are represented by an\n object mapping dimension codes to ids of dimension values. The actual filtering logic is implemented by dimension\n values themselves, and depend on the Dimension datatype (UserDefined, Date, ProjectMember, etc.) and value\n semantics.\n\n- Anchors capture the use of dimensions to arrange cards in rows and columns, choose what dimensions are shown\n on cards in a board, or what dimensions are visible in the filter decks. Anchors are represented by an object\n mapping the anchor name to a list of dimension codes.\n\n## Tips & Tricks\n\n**Use boards, even for creating stories**\n\nBoard filters are used to automatically enrich created stories with default values. This allows you to create\nstories without having to specify all fields.\n\n## FAQ\n\n**Where is the markdown card description ?**\n\nFor historical reasons, cards are called `stories` on the V1 API, and their description is called the\n`specification`. Sorry for the confusion introduced.\n\n**Why no `GET /stories` web service**\n\nYou should always access stories/cards via a given board. See [`GET /boards/{id}/stories`](#get-stories) instead.\n\n# ---", "termsOfService": "https://www.klaro.cards/legal/terms-of-use", "contact": { "name": "Klaro Cards Support", "email": "support@klaro.cards" }, "version": "v1 (0.268.1)" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The API supports an OAuth2 authentication mechanism, using tokens served from\nuser credentials by [`POST /auth/tokens`](#create-token).\n\nThe token scopes follow the user permission model of the Klaro Cards app.\nThe scope documented on web services is the minimum scope required, knowing that\nthe hierarchy below applies.\n\n Owner > Admin > Member > User > Anonymous", "flows": { "clientCredentials": { "tokenUrl": "/auth/tokens/" } } } } }, "tags": [ { "name": "Auth Token", "description": "Everything about the tokens used to authenticate and logout" }, { "name": "User", "description": "Everything about the user currently using the API" }, { "name": "Projects", "description": "Everything about the projects on the instance and the current project being accessed" }, { "name": "Dimensions", "description": "Everything about the dimensions of the current project" }, { "name": "Dimension values", "description": "Everything about the dimensions values" }, { "name": "Stories (aka Cards)", "description": "Everything about all cards of the current project" }, { "name": "Boards", "description": "Everything about the boards of the current project" }, { "name": "Board stories", "description": "Everything about the cards visible in a specific board" }, { "name": "Danger zone", "description": "Everything about dangerous project actions" }, { "name": "User" }, { "name": "Auth Token" }, { "name": "Boards" }, { "name": "Board stories" }, { "name": "Dimensions" }, { "name": "Dimension values" }, { "name": "Danger zone" }, { "name": "Projects" }, { "name": "Stories (aka Cards)" } ], "paths": { "/auth/me": { "summary": "User", "get": { "summary": "Get user", "description": "Returns information about the current user and their preferences on the\ncurrent project", "tags": [ "User" ], "parameters": [], "security": [ { "OAuth2": [ "Anonymous" ] }, {} ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "User unique id" }, "email": { "type": "string", "description": "User's email" }, "emailValidated": { "type": "boolean", "description": "Whether the email has been verified" }, "firstname": { "type": "string", "description": "User's first name" }, "lastname": { "type": "string", "description": "User's last name" }, "nickname": { "type": "string", "description": "User's nickname on the project" }, "isOwner": { "type": "boolean", "description": "Whether the user owns the current project" }, "lang": { "type": "string", "description": "Prefered language for communications with Klaro Cards" }, "isMember": { "type": "boolean", "description": "Whether the user is a member of the current project" }, "createdAt": { "type": "string", "description": "When was the user created on the project" }, "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Workspace unique id" }, "code": { "type": "string", "description": "Workspace unique code (used in urls and dimension values)" }, "name": { "type": "string", "description": "Workspace human readable name" }, "space": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "description": "Associated klaro space (reserved)" }, "ordering": { "type": "integer", "description": "Order of workspace in the all workspaces" }, "createdAt": { "type": "string", "description": "When the workspace has been created" } }, "required": [ "id", "code", "name", "space", "ordering", "createdAt" ] }, "description": "Information about the user's membership to workspaces" }, "preferences": { "type": "object", "properties": { "homeWorkspace": { "type": "string", "description": "Which workspace is used as home page, if any" }, "homeBoard": { "type": "string", "description": "Which board is used as home page, if any" }, "lang": { "type": "string", "description": "Prefered user language on the current project" }, "syncMode": { "type": "string", "description": "Prefered board synchronization mode on the current project" }, "labs": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the lab is enabled on the current project" } }, "required": [ "enabled" ], "additionalProperties": {} }, "description": "Which labs are currently enabled and their configuration" } }, "required": [ "homeWorkspace", "homeBoard", "lang", "syncMode" ], "description": "The user preferences on this current project" }, "passwordChangedAt": { "type": "string", "description": "Last time the password has been changed" } }, "required": [ "id", "email", "emailValidated", "firstname", "lastname", "isOwner", "lang", "isMember", "createdAt", "workspaces", "preferences", "passwordChangedAt" ] }, "examples": { "Get information about the current project user": { "description": "Get information about the current project user", "value": { "id": "a0ebde37-1234-449b-b564-39efaca0f37f", "email": "bernard@klaro.cards", "emailValidated": true, "passwordChangedAt": "2025-08-31T12:27:52+00:00", "firstname": "Bernard", "lastname": "Lambeau", "lang": "en", "createdAt": "2024-06-15T10:23:05+00:00", "nickname": "Bernard", "isOwner": true, "preferences": { "homeBoard": null, "homeWorkspace": null, "lang": null, "syncMode": null, "labs": null }, "workspaces": [ { "id": "aaa27578-be58-4634-a24f-35057759bd46", "code": "admins", "name": "Admins", "space": { "id": "dbe8cc25-8c98-4ead-b1a9-36e2d95424fb" }, "ordering": 0, "createdAt": "2025-03-21T16:30:16+00:00" } ], "isMember": true } } } } } } } }, "patch": { "summary": "Save user & preferences", "description": "Updates the user profile and their preferences on the current project", "tags": [ "User" ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstname": { "type": "string", "description": "User's first name" }, "lastname": { "type": "string", "description": "User's last name" }, "lang": { "type": "string", "description": "Prefered language for communications with Klaro Cards" }, "preferences": { "type": "object", "properties": { "homeWorkspace": { "type": "string", "description": "Which workspace is used as home page, if any" }, "homeBoard": { "type": "string", "description": "Which board is used as home page, if any" }, "lang": { "type": "string", "description": "Prefered user language on the current project" }, "syncMode": { "type": "string", "description": "Prefered board synchronization mode on the current project" }, "labs": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the lab is enabled on the current project" } }, "required": [ "enabled" ], "additionalProperties": {} }, "description": "Which labs are currently enabled and their configuration" } }, "required": [ "homeWorkspace", "homeBoard", "lang", "syncMode" ], "description": "The user preferences on this current project" } } }, "examples": { "Update the user name and preferences": { "description": "Update the user name and preferences", "value": { "firstname": "Foo", "lastname": "Bar", "preferences": { "homeBoard": "kanban", "homeWorkspace": "admins", "lang": "fr", "syncMode": "onDemand" } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "User unique id" }, "email": { "type": "string", "description": "User's email" }, "emailValidated": { "type": "boolean", "description": "Whether the email has been verified" }, "firstname": { "type": "string", "description": "User's first name" }, "lastname": { "type": "string", "description": "User's last name" }, "nickname": { "type": "string", "description": "User's nickname on the project" }, "isOwner": { "type": "boolean", "description": "Whether the user owns the current project" }, "lang": { "type": "string", "description": "Prefered language for communications with Klaro Cards" }, "isMember": { "type": "boolean", "description": "Whether the user is a member of the current project" }, "createdAt": { "type": "string", "description": "When was the user created on the project" }, "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Workspace unique id" }, "code": { "type": "string", "description": "Workspace unique code (used in urls and dimension values)" }, "name": { "type": "string", "description": "Workspace human readable name" }, "space": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "description": "Associated klaro space (reserved)" }, "ordering": { "type": "integer", "description": "Order of workspace in the all workspaces" }, "createdAt": { "type": "string", "description": "When the workspace has been created" } }, "required": [ "id", "code", "name", "space", "ordering", "createdAt" ] }, "description": "Information about the user's membership to workspaces" }, "preferences": { "type": "object", "properties": { "homeWorkspace": { "type": "string", "description": "Which workspace is used as home page, if any" }, "homeBoard": { "type": "string", "description": "Which board is used as home page, if any" }, "lang": { "type": "string", "description": "Prefered user language on the current project" }, "syncMode": { "type": "string", "description": "Prefered board synchronization mode on the current project" }, "labs": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the lab is enabled on the current project" } }, "required": [ "enabled" ], "additionalProperties": {} }, "description": "Which labs are currently enabled and their configuration" } }, "required": [ "homeWorkspace", "homeBoard", "lang", "syncMode" ], "description": "The user preferences on this current project" }, "passwordChangedAt": { "type": "string", "description": "Last time the password has been changed" } }, "required": [ "id", "email", "emailValidated", "firstname", "lastname", "isOwner", "lang", "isMember", "createdAt", "workspaces", "preferences", "passwordChangedAt" ] }, "examples": { "Update the user name and preferences": { "description": "Update the user name and preferences", "value": { "id": "a0ebde37-1234-449b-b564-39efaca0f37f", "email": "bernard@klaro.cards", "emailValidated": true, "passwordChangedAt": "2025-08-31T12:27:52+00:00", "firstname": "Foo", "lastname": "Bar", "lang": "en", "createdAt": "2024-06-15T10:23:05+00:00", "nickname": "Bernard", "isOwner": true, "preferences": { "homeBoard": "kanban", "homeWorkspace": "admins", "lang": "fr", "syncMode": "onDemand", "labs": {} }, "workspaces": [ { "id": "aaa27578-be58-4634-a24f-35057759bd46", "code": "admins", "name": "Admins", "space": { "id": "dbe8cc25-8c98-4ead-b1a9-36e2d95424fb" }, "ordering": 0, "createdAt": "2025-03-21T16:30:16+00:00" } ], "isMember": true } } } } } } } } }, "/auth/tokens": { "summary": "Authentication token", "post": { "summary": "Create token", "description": "Allows creating a fresh new token from user credentials. The token can then\nbe used during 5 days. Consider [revoking it](#revoke-token) when done.", "tags": [ "Auth Token" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Use 'client_credentials'" }, "client_id": { "type": "string", "description": "Use user login" }, "client_secret": { "type": "string", "description": "Use user password" }, "redirect_to": { "type": "string", "description": "Reserved for Klaro Cards app" } }, "required": [ "grant_type", "client_id", "client_secret" ] }, "examples": { "Create a token with a valid user/password pair": { "description": "Create a token with a valid user/password pair", "value": { "grant_type": "client_credentials", "client_id": "bernard@klaro.cards", "client_secret": "password" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "token_type": { "type": "string", "description": "Type of token, typically Bearer" }, "access_token": { "type": "string", "description": "The token to pass in Authorization header" }, "expires_in": { "type": "integer", "description": "Expiration in seconds" } }, "required": [ "token_type", "access_token", "expires_in" ] }, "examples": { "Create a token with a valid user/password pair": { "description": "Create a token with a valid user/password pair", "value": { "token_type": "Bearer", "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiYTBlYmRlMzctMTIzNC00NDliLWI1NjQtMzllZmFjYTBmMzdmIiwiaWF0IjoxNzU2NzI5NjczLCJleHAiOjE3NTcxNjE2NzN9.etDN_S2Y7pMg_VO_48N1H0xK_PpSFhLS3jvCsNMsa2U", "expires_in": 432000 } } } } } } } } }, "/auth/tokens/self": { "summary": "Authentication token", "delete": { "summary": "Revoke token", "description": "Allows revoking a token without waiting for it to expire, e.g. when the\nuser logs out or the script is finished.\n\nJust call the web service with the usual Authentication header, the token\nwill be revoked", "tags": [ "Auth Token" ], "parameters": [], "security": [ { "OAuth2": [ "Member" ] } ], "responses": { "204": { "description": "" } } } }, "/boards/{id}": { "summary": "Board", "get": { "summary": "Get board", "description": "Returns the complete definition of a board", "tags": [ "Boards" ], "parameters": [ { "in": "path", "name": "id", "description": "Either the board id or location", "schema": { "type": "string", "description": "Either the board id or location" }, "required": true, "example": "kanban" } ], "security": [ { "OAuth2": [ "Anonymous" ] }, {} ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Board unique ID" }, "label": { "type": "string", "description": "Board human friendly name" }, "location": { "type": "string", "description": "Board friendly location (used in url)" }, "mode": { "type": "string", "description": "Board mode (e.g. grid, list, kanban)" }, "connector": { "type": "string", "description": "Reserved (use BaseConnector)" }, "objective": { "type": "string", "description": "Board objective (shown to users on load)" }, "objectiveModal": { "type": "boolean", "description": "Whether the objective must be shown to users" }, "decksOpen": { "type": "boolean", "description": "Whether the filter decks are open on board load" }, "coloredDimension": { "type": "string", "description": "Dimension (code) used for card colors" }, "compactDisplay": { "type": "boolean", "description": "Whether empty columns/rows/categories are hidden" }, "compactDecks": { "type": "boolean", "description": "Whether unused values are hidden in filters" }, "explorerDecks": { "type": "boolean", "description": "Whether the filter decks use left-to-right layout" }, "background": { "type": "string", "description": "Name of the board background" }, "createdBy": { "type": "string", "description": "Who created the board" }, "createdAt": { "type": "string", "description": "When was the board created" }, "ordering": { "type": "integer", "description": "Order index of the board in the collection" }, "ganttScale": { "type": "string", "description": "Scale used in the gantt mode" }, "manualDimensionsInDecks": { "type": "boolean", "description": "Whether the user selected specific dimensions to be shown in decks" }, "displayDimensionsOnCards": { "type": "boolean", "description": "Whether dimensions are shown on cards" }, "displayDimensionLabels": { "type": "boolean", "description": "Whether dimension labels are shown on cards" }, "displayNoneOnCards": { "type": "boolean", "description": "Whether empty values are shown on carts" }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Dimension unique ID" }, "code": { "type": "string", "description": "Dimension code (used in URLs, filters, anchors, etc.)" }, "datatype": { "type": "string", "description": "Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "supportsRequired": { "type": "boolean", "description": "Whether the users can decided whether the dimension is required" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "supportsTagging": { "type": "boolean", "description": "Whether users can choose to lock/unlock the dimension" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "supportsMultiple": { "type": "boolean", "description": "Whether the dimension datatype supports multiple values" }, "supportsAlphabeticalOrdering": { "type": "boolean", "description": "Whether values can be ordered alphabetically" }, "userEditable": { "type": "boolean", "description": "Whether values can be choosen by end-users on cards" }, "attribute": { "type": "boolean", "description": "Whether this dimension is a fixed card attribute (deprecated)" }, "supportsColor": { "type": "boolean", "description": "Whether the dimension supports colors on values" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "description": "The dimension list of values" }, "deleted": { "type": "boolean", "description": "Whether the dimension has been deleted" }, "deletedAt": { "type": "string", "description": "When this dimension was deleted, if deleted" }, "deletedBy": { "type": "string", "description": "Who deleted this dimension, if deleted" } }, "required": [ "id", "code", "datatype", "datatypeOptions", "label", "description", "required", "supportsRequired", "tagging", "supportsTagging", "multiple", "supportsMultiple", "supportsAlphabeticalOrdering", "userEditable", "attribute", "supportsColor", "ordering", "semanticsType", "relevantKinds", "values", "deleted", "deletedAt", "deletedBy" ] }, "description": "List of board dimensions" }, "anchors": { "type": "object", "properties": { "decks": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show in filters deck" }, "displayBy": { "type": "array", "items": { "type": "string" }, "description": "Dimension(s) used to group cards in board" }, "cards": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show on cards" }, "ordering": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to use to sort cards in board" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Dimensions required in the board" }, "gantt": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used for Gantt mode" }, "hierarchyBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to hierarchy in List mode" }, "seriesBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to as series in Chart mode" }, "rowsBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used as rows in Matrix mode" } }, "additionalProperties": {}, "description": "List of board anchors, see Data Model" }, "anchorOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } } }, "required": [ "autoDimValues" ] } }, "description": "Anchors options" }, "filters": { "type": "object", "description": "List of board filters, see Data Model" }, "workspacePermissions": { "type": "array", "items": { "type": "object", "properties": { "workspace": { "type": "string", "description": "Workspace code" }, "canRead": { "type": "boolean", "description": "Whether the users can read cards" }, "canWrite": { "type": "boolean", "description": "Whether the users can write cards" }, "canManage": { "type": "boolean", "description": "Whether the users can manage cards" } }, "required": [ "workspace", "canRead", "canWrite", "canManage" ] }, "description": "List of workspaces permissions on this board" }, "summaries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Summary function code" }, "label": { "type": "string", "description": "Summary function label" }, "expr": { "type": "string", "description": "Formal expression" }, "ordering": { "type": "integer", "description": "Summary order index in collection" } }, "required": [ "code", "label", "expr", "ordering" ] }, "description": "List of board summaries shown" }, "importers": { "type": "array", "items": { "type": "object" }, "description": "List of board importers" }, "extraSettings": { "type": "object", "properties": { "onCardClick": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Action options" } }, "required": [ "type", "options" ], "description": "Behavior on card click" }, "swipeGestures": { "type": "object", "properties": { "left": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping left" }, "right": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping right" }, "up": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping up" }, "down": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping down" } }, "description": "Behavior when swiping on mobile" }, "chartOptions": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "description": "Options for chart mode" } }, "description": "Extra board settings used by the various modes" } }, "required": [ "id", "label", "location", "mode", "connector", "objective", "objectiveModal", "decksOpen", "coloredDimension", "compactDisplay", "compactDecks", "explorerDecks", "background", "createdBy", "createdAt", "ordering", "ganttScale", "manualDimensionsInDecks", "displayDimensionsOnCards", "displayDimensionLabels", "displayNoneOnCards", "dimensions", "anchors", "anchorOptions", "filters", "workspacePermissions", "summaries", "extraSettings" ] }, "examples": { "When getting a board, you can use both the board ID of the human-friendly location field in\nURL.": { "description": "When getting a board, you can use both the board ID of the human-friendly location field in\nURL.", "value": { "id": "7a95ea0d-b029-41c8-a95d-b65a4a356ea4", "label": "Kanban", "location": "kanban", "mode": "kanban", "objective": "", "objectiveModal": false, "decksOpen": false, "coloredDimension": "progress", "compactDisplay": false, "compactDecks": false, "explorerDecks": false, "background": "lagoon", "anchors": { "cards": [ "assignee" ], "displayBy": [ "progress" ], "required": [ "progress" ] }, "anchorOptions": {}, "filters": { "kind": [ "todo" ], "progress": [ "todo", "ongoing" ] }, "summaries": [], "workspacePermissions": [ { "workspace": "admins", "canRead": true, "canWrite": true, "canManage": true } ], "createdBy": "Bernard", "createdAt": "2025-03-21T16:32:45+00:00", "dimensions": [ { "code": "kind", "ordering": 20000, "label": "Kind", "tagging": true, "multiple": false, "required": true, "id": "0d3c755c-b3d3-4940-947e-e90de07e571f", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Kind", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "color": "#b7137e", "ordering": 1000000, "semantics": null, "colorDimension": null, "description": null, "placeholder": null, "deprecated": false, "summaryDimensions": [] } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "identifier", "ordering": 1000, "label": "Card n°", "tagging": false, "multiple": false, "required": true, "id": "af352fc7-8c9b-4030-934e-da0b1f737741", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Identifier", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": false }, { "code": "title", "ordering": 1010, "label": "Card title", "tagging": false, "multiple": false, "required": false, "id": "4e5bf2b8-b0d3-4f5d-b966-e017f7feadda", "deleted": false, "deletedAt": null, "deletedBy": null, "description": "Card title", "semanticsType": null, "datatype": "Title", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": true }, { "code": "specification", "ordering": 1011, "label": "Card description", "tagging": false, "multiple": false, "required": false, "id": "039fdea8-4dd7-488f-85f5-38f2c11eff8a", "deleted": false, "deletedAt": null, "deletedBy": null, "description": "Card (Markdown) description", "semanticsType": null, "datatype": "Specification", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": true }, { "code": "progress", "ordering": 120000, "label": "Progress", "tagging": true, "multiple": false, "required": false, "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Progress", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "ordering": 10000, "color": "#e01514", "semantics": null, "description": null, "deprecated": false }, { "id": "ongoing", "label": "Ongoing", "ordering": 20000, "color": "#f77d00", "semantics": null, "description": null, "deprecated": false }, { "id": "done", "label": "Done", "ordering": 30000, "color": "#00b048", "semantics": null, "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "assignee", "ordering": 220000, "label": "Assignee", "tagging": true, "multiple": false, "required": false, "id": "0334196e-1aba-4049-9769-b8fde2eb2227", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "ProjectMember", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "Bernard", "label": "Bernard", "ordering": 1000000, "color": "#ffffff", "semantics": "Bernard", "description": null, "deprecated": false }, { "id": "Victor", "label": "Victor", "ordering": 2000000, "color": "#ffffff", "semantics": "Victor", "description": null, "deprecated": false }, { "id": "Marc", "label": "Marc", "ordering": 3000000, "color": "#ffffff", "semantics": "Marc", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": true, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "due_date", "ordering": 320000, "label": "Due date", "tagging": false, "multiple": false, "required": false, "id": "44c78647-0a68-48a2-b6e0-0fd926752f4f", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": "DateRange", "datatype": "DueDate", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "late_", "label": "Late!", "ordering": 10000, "color": "#202020", "semantics": "-BOT", "description": null, "deprecated": false }, { "id": "late_tomorrow", "label": "Late tomorrow", "ordering": 20000, "color": "#e01514", "semantics": "+P1D", "description": null, "deprecated": false }, { "id": "late_in_3_days", "label": "Late in 3 days", "ordering": 30000, "color": "#a85319", "semantics": "+P1D .. +P3D", "description": null, "deprecated": false }, { "id": "next_7_days", "label": "Next 7 days", "ordering": 40000, "color": "#ffba00", "semantics": "+P3D .. +P7D", "description": null, "deprecated": false }, { "id": "next_15_days", "label": "Next 15 days", "ordering": 50000, "color": "#99cc2d", "semantics": "+P7D .. +P15D", "description": null, "deprecated": false }, { "id": "next_30_days", "label": "Next 30 days", "ordering": 60000, "color": "#00b048", "semantics": "+P15D .. +P30D", "description": null, "deprecated": false }, { "id": "later", "label": "Later", "ordering": 70000, "color": "#00b048", "semantics": "+P30D .. P100Y", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": false, "supportsColor": true, "userEditable": true } ], "ordering": 2, "ganttScale": null, "displayDimensionLabels": false, "manualDimensionsInDecks": false, "displayDimensionsOnCards": true, "displayNoneOnCards": false, "connector": "BaseConnector", "importers": [], "extraSettings": { "onCardClick": { "type": "fullEdit", "options": {} } } } } } } } } } }, "patch": { "summary": "Save board", "description": "Updates the definition of a board", "tags": [ "Boards" ], "parameters": [ { "in": "path", "name": "id", "description": "Either the board id or location", "schema": { "type": "string", "description": "Either the board id or location" }, "required": true, "example": "kanban" } ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Board human friendly name" }, "location": { "type": "string", "description": "Board friendly location (used in url)" }, "mode": { "type": "string", "description": "Board mode (e.g. grid, list, kanban)" }, "objective": { "type": "string", "description": "Board objective (shown to users on load)" }, "objectiveModal": { "type": "boolean", "description": "Whether the objective must be shown to users" }, "decksOpen": { "type": "boolean", "description": "Whether the filter decks are open on board load" }, "coloredDimension": { "type": "string", "description": "Dimension (code) used for card colors" }, "compactDisplay": { "type": "boolean", "description": "Whether empty columns/rows/categories are hidden" }, "compactDecks": { "type": "boolean", "description": "Whether unused values are hidden in filters" }, "explorerDecks": { "type": "boolean", "description": "Whether the filter decks use left-to-right layout" }, "displayDimensionLabels": { "type": "boolean", "description": "Whether dimension labels are shown on cards" }, "manualDimensionsInDecks": { "type": "boolean", "description": "Whether the user selected specific dimensions to be shown in decks" }, "displayDimensionsOnCards": { "type": "boolean", "description": "Whether dimensions are shown on cards" }, "displayNoneOnCards": { "type": "boolean", "description": "Whether empty values are shown on carts" }, "background": { "type": "string", "description": "Name of the board background" }, "ganttScale": { "type": "string", "description": "Scale used in the gantt mode" }, "anchors": { "type": "object", "properties": { "decks": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show in filters deck" }, "displayBy": { "type": "array", "items": { "type": "string" }, "description": "Dimension(s) used to group cards in board" }, "cards": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show on cards" }, "ordering": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to use to sort cards in board" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Dimensions required in the board" }, "gantt": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used for Gantt mode" }, "hierarchyBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to hierarchy in List mode" }, "seriesBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to as series in Chart mode" }, "rowsBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used as rows in Matrix mode" } }, "additionalProperties": {}, "description": "List of board anchors, see Data Model" }, "anchorOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } } }, "required": [ "autoDimValues" ] } }, "description": "Anchors options" }, "filters": { "type": "object", "description": "List of board filters, see Data Model" }, "summaries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Summary function code" }, "label": { "type": "string", "description": "Summary function label" }, "ordering": { "type": "integer", "description": "Summary order index in collection" }, "expr": { "type": "string", "description": "Formal expression" } }, "required": [ "code" ], "additionalProperties": {} }, "description": "List of board summaries shown" }, "workspacePermissions": { "type": "array", "items": { "type": "object", "properties": { "workspace": { "type": "string", "description": "Workspace code" }, "canRead": { "type": "boolean", "description": "Whether the users can read cards" }, "canWrite": { "type": "boolean", "description": "Whether the users can write cards" }, "canManage": { "type": "boolean", "description": "Whether the users can manage cards" } }, "required": [ "workspace", "canRead", "canWrite", "canManage" ] }, "description": "List of workspaces permissions on this board" }, "extraSettings": { "type": "object", "properties": { "onCardClick": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Action options" } }, "required": [ "type", "options" ], "description": "Behavior on card click" }, "swipeGestures": { "type": "object", "properties": { "left": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping left" }, "right": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping right" }, "up": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping up" }, "down": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping down" } }, "description": "Behavior when swiping on mobile" }, "chartOptions": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "description": "Options for chart mode" } }, "description": "Extra board settings used by the various modes" } }, "additionalProperties": {} }, "examples": { "Update some fields of a board. Both the ID or the board location can\nbe used as URL parameter.": { "description": "Update some fields of a board. Both the ID or the board location can\nbe used as URL parameter.", "value": { "label": "A new label", "location": "a-new-location" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Board unique ID" }, "label": { "type": "string", "description": "Board human friendly name" }, "location": { "type": "string", "description": "Board friendly location (used in url)" }, "mode": { "type": "string", "description": "Board mode (e.g. grid, list, kanban)" }, "connector": { "type": "string", "description": "Reserved (use BaseConnector)" }, "objective": { "type": "string", "description": "Board objective (shown to users on load)" }, "objectiveModal": { "type": "boolean", "description": "Whether the objective must be shown to users" }, "decksOpen": { "type": "boolean", "description": "Whether the filter decks are open on board load" }, "coloredDimension": { "type": "string", "description": "Dimension (code) used for card colors" }, "compactDisplay": { "type": "boolean", "description": "Whether empty columns/rows/categories are hidden" }, "compactDecks": { "type": "boolean", "description": "Whether unused values are hidden in filters" }, "explorerDecks": { "type": "boolean", "description": "Whether the filter decks use left-to-right layout" }, "background": { "type": "string", "description": "Name of the board background" }, "createdBy": { "type": "string", "description": "Who created the board" }, "createdAt": { "type": "string", "description": "When was the board created" }, "ordering": { "type": "integer", "description": "Order index of the board in the collection" }, "ganttScale": { "type": "string", "description": "Scale used in the gantt mode" }, "manualDimensionsInDecks": { "type": "boolean", "description": "Whether the user selected specific dimensions to be shown in decks" }, "displayDimensionsOnCards": { "type": "boolean", "description": "Whether dimensions are shown on cards" }, "displayDimensionLabels": { "type": "boolean", "description": "Whether dimension labels are shown on cards" }, "displayNoneOnCards": { "type": "boolean", "description": "Whether empty values are shown on carts" }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Dimension unique ID" }, "code": { "type": "string", "description": "Dimension code (used in URLs, filters, anchors, etc.)" }, "datatype": { "type": "string", "description": "Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "supportsRequired": { "type": "boolean", "description": "Whether the users can decided whether the dimension is required" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "supportsTagging": { "type": "boolean", "description": "Whether users can choose to lock/unlock the dimension" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "supportsMultiple": { "type": "boolean", "description": "Whether the dimension datatype supports multiple values" }, "supportsAlphabeticalOrdering": { "type": "boolean", "description": "Whether values can be ordered alphabetically" }, "userEditable": { "type": "boolean", "description": "Whether values can be choosen by end-users on cards" }, "attribute": { "type": "boolean", "description": "Whether this dimension is a fixed card attribute (deprecated)" }, "supportsColor": { "type": "boolean", "description": "Whether the dimension supports colors on values" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "description": "The dimension list of values" }, "deleted": { "type": "boolean", "description": "Whether the dimension has been deleted" }, "deletedAt": { "type": "string", "description": "When this dimension was deleted, if deleted" }, "deletedBy": { "type": "string", "description": "Who deleted this dimension, if deleted" } }, "required": [ "id", "code", "datatype", "datatypeOptions", "label", "description", "required", "supportsRequired", "tagging", "supportsTagging", "multiple", "supportsMultiple", "supportsAlphabeticalOrdering", "userEditable", "attribute", "supportsColor", "ordering", "semanticsType", "relevantKinds", "values", "deleted", "deletedAt", "deletedBy" ] }, "description": "List of board dimensions" }, "anchors": { "type": "object", "properties": { "decks": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show in filters deck" }, "displayBy": { "type": "array", "items": { "type": "string" }, "description": "Dimension(s) used to group cards in board" }, "cards": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show on cards" }, "ordering": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to use to sort cards in board" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Dimensions required in the board" }, "gantt": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used for Gantt mode" }, "hierarchyBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to hierarchy in List mode" }, "seriesBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to as series in Chart mode" }, "rowsBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used as rows in Matrix mode" } }, "additionalProperties": {}, "description": "List of board anchors, see Data Model" }, "anchorOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } } }, "required": [ "autoDimValues" ] } }, "description": "Anchors options" }, "filters": { "type": "object", "description": "List of board filters, see Data Model" }, "workspacePermissions": { "type": "array", "items": { "type": "object", "properties": { "workspace": { "type": "string", "description": "Workspace code" }, "canRead": { "type": "boolean", "description": "Whether the users can read cards" }, "canWrite": { "type": "boolean", "description": "Whether the users can write cards" }, "canManage": { "type": "boolean", "description": "Whether the users can manage cards" } }, "required": [ "workspace", "canRead", "canWrite", "canManage" ] }, "description": "List of workspaces permissions on this board" }, "summaries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Summary function code" }, "label": { "type": "string", "description": "Summary function label" }, "expr": { "type": "string", "description": "Formal expression" }, "ordering": { "type": "integer", "description": "Summary order index in collection" } }, "required": [ "code", "label", "expr", "ordering" ] }, "description": "List of board summaries shown" }, "importers": { "type": "array", "items": { "type": "object" }, "description": "List of board importers" }, "extraSettings": { "type": "object", "properties": { "onCardClick": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Action options" } }, "required": [ "type", "options" ], "description": "Behavior on card click" }, "swipeGestures": { "type": "object", "properties": { "left": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping left" }, "right": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping right" }, "up": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping up" }, "down": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping down" } }, "description": "Behavior when swiping on mobile" }, "chartOptions": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "description": "Options for chart mode" } }, "description": "Extra board settings used by the various modes" } }, "required": [ "id", "label", "location", "mode", "connector", "objective", "objectiveModal", "decksOpen", "coloredDimension", "compactDisplay", "compactDecks", "explorerDecks", "background", "createdBy", "createdAt", "ordering", "ganttScale", "manualDimensionsInDecks", "displayDimensionsOnCards", "displayDimensionLabels", "displayNoneOnCards", "dimensions", "anchors", "anchorOptions", "filters", "workspacePermissions", "summaries", "extraSettings" ] }, "examples": { "Update some fields of a board. Both the ID or the board location can\nbe used as URL parameter.": { "description": "Update some fields of a board. Both the ID or the board location can\nbe used as URL parameter.", "value": { "id": "7a95ea0d-b029-41c8-a95d-b65a4a356ea4", "label": "A new label", "location": "a-new-location", "mode": "kanban", "objective": "", "objectiveModal": false, "decksOpen": false, "coloredDimension": "progress", "compactDisplay": false, "compactDecks": false, "explorerDecks": false, "background": "lagoon", "anchors": { "cards": [ "assignee" ], "displayBy": [ "progress" ], "required": [ "progress" ] }, "anchorOptions": {}, "filters": { "kind": [ "todo" ], "progress": [ "todo", "ongoing" ] }, "summaries": [], "workspacePermissions": [ { "workspace": "admins", "canRead": true, "canWrite": true, "canManage": true } ], "createdBy": "Bernard", "createdAt": "2025-03-21T16:32:45+00:00", "dimensions": [ { "code": "kind", "ordering": 20000, "label": "Kind", "tagging": true, "multiple": false, "required": true, "id": "0d3c755c-b3d3-4940-947e-e90de07e571f", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Kind", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "color": "#b7137e", "ordering": 1000000, "semantics": null, "colorDimension": null, "description": null, "placeholder": null, "deprecated": false, "summaryDimensions": [] } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "identifier", "ordering": 1000, "label": "Card n°", "tagging": false, "multiple": false, "required": true, "id": "af352fc7-8c9b-4030-934e-da0b1f737741", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Identifier", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": false }, { "code": "title", "ordering": 1010, "label": "Card title", "tagging": false, "multiple": false, "required": false, "id": "4e5bf2b8-b0d3-4f5d-b966-e017f7feadda", "deleted": false, "deletedAt": null, "deletedBy": null, "description": "Card title", "semanticsType": null, "datatype": "Title", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": true }, { "code": "specification", "ordering": 1011, "label": "Card description", "tagging": false, "multiple": false, "required": false, "id": "039fdea8-4dd7-488f-85f5-38f2c11eff8a", "deleted": false, "deletedAt": null, "deletedBy": null, "description": "Card (Markdown) description", "semanticsType": null, "datatype": "Specification", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": true }, { "code": "progress", "ordering": 120000, "label": "Progress", "tagging": true, "multiple": false, "required": false, "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Progress", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "ordering": 10000, "color": "#e01514", "semantics": null, "description": null, "deprecated": false }, { "id": "ongoing", "label": "Ongoing", "ordering": 20000, "color": "#f77d00", "semantics": null, "description": null, "deprecated": false }, { "id": "done", "label": "Done", "ordering": 30000, "color": "#00b048", "semantics": null, "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "assignee", "ordering": 220000, "label": "Assignee", "tagging": true, "multiple": false, "required": false, "id": "0334196e-1aba-4049-9769-b8fde2eb2227", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "ProjectMember", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "Bernard", "label": "Bernard", "ordering": 1000000, "color": "#ffffff", "semantics": "Bernard", "description": null, "deprecated": false }, { "id": "Victor", "label": "Victor", "ordering": 2000000, "color": "#ffffff", "semantics": "Victor", "description": null, "deprecated": false }, { "id": "Marc", "label": "Marc", "ordering": 3000000, "color": "#ffffff", "semantics": "Marc", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": true, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "due_date", "ordering": 320000, "label": "Due date", "tagging": false, "multiple": false, "required": false, "id": "44c78647-0a68-48a2-b6e0-0fd926752f4f", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": "DateRange", "datatype": "DueDate", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "late_", "label": "Late!", "ordering": 10000, "color": "#202020", "semantics": "-BOT", "description": null, "deprecated": false }, { "id": "late_tomorrow", "label": "Late tomorrow", "ordering": 20000, "color": "#e01514", "semantics": "+P1D", "description": null, "deprecated": false }, { "id": "late_in_3_days", "label": "Late in 3 days", "ordering": 30000, "color": "#a85319", "semantics": "+P1D .. +P3D", "description": null, "deprecated": false }, { "id": "next_7_days", "label": "Next 7 days", "ordering": 40000, "color": "#ffba00", "semantics": "+P3D .. +P7D", "description": null, "deprecated": false }, { "id": "next_15_days", "label": "Next 15 days", "ordering": 50000, "color": "#99cc2d", "semantics": "+P7D .. +P15D", "description": null, "deprecated": false }, { "id": "next_30_days", "label": "Next 30 days", "ordering": 60000, "color": "#00b048", "semantics": "+P15D .. +P30D", "description": null, "deprecated": false }, { "id": "later", "label": "Later", "ordering": 70000, "color": "#00b048", "semantics": "+P30D .. P100Y", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": false, "supportsColor": true, "userEditable": true } ], "ordering": 2, "ganttScale": null, "displayDimensionLabels": false, "manualDimensionsInDecks": false, "displayDimensionsOnCards": true, "displayNoneOnCards": false, "connector": "BaseConnector", "importers": [], "extraSettings": { "onCardClick": { "type": "fullEdit", "options": {} } } } } } } } } } }, "delete": { "summary": "Delete board", "description": "Deletes a single board and all its dependencies", "tags": [ "Boards" ], "parameters": [ { "in": "path", "name": "id", "description": "Either the board id or location", "schema": { "type": "string", "description": "Either the board id or location" }, "required": true, "example": "kanban" } ], "security": [ { "OAuth2": [ "Member" ] } ], "responses": { "204": { "description": "" } } } }, "/boards/{board}/stories/{story}": { "summary": "Board single story", "get": { "summary": "Get story", "description": "Returns a single story", "tags": [ "Board stories" ], "parameters": [ { "in": "path", "name": "board", "schema": { "type": "string" }, "required": true, "example": "kanban" }, { "in": "path", "name": "story", "schema": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "required": true, "example": "8ed76538-ee9a-4b39-9407-6b392a7ddc35" } ], "security": [ { "OAuth2": [ "Anonymous" ] }, {} ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" }, "linked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" } }, "required": [ "id", "identifier", "title" ], "additionalProperties": { "type": "object" } }, "description": "Linked stories" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachement unique ID" }, "filename": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "URL of the attachement, relative to the project's imgBaseUrl" }, "description": { "type": "string", "description": "Attachment description, if any" }, "sizeInBytes": { "type": "integer", "description": "Attachment size in bytes" }, "isCover": { "type": "boolean", "description": "Whether the attachment is used as story cover" }, "createdAt": { "type": "string", "description": "When was the attachent created" }, "createdBy": { "type": "string", "description": "Who created the attachent" } }, "required": [ "id", "filename", "url", "description", "sizeInBytes", "isCover", "createdAt", "createdBy" ] }, "description": "Story attachments" } }, "required": [ "id", "identifier", "title", "specification", "createdBy", "createdAt", "updatedAt", "linked", "attachments" ], "additionalProperties": { "type": "object" } }, "examples": { "Get a story that belongs to the board": { "description": "Get a story that belongs to the board", "value": { "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35", "identifier": 2, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "Document the RESTful API", "createdAt": "2025-03-21T16:32:17+00:00", "createdBy": "Bernard", "updatedAt": "2025-03-24T13:23:07+00:00", "specification": "", "kind": "todo", "progress": "ongoing", "assignee": "Bernard", "due_date": null, "attachments": [], "linked": [] } } } } } } } }, "patch": { "summary": "Update story", "description": "Patches a single story", "tags": [ "Board stories" ], "parameters": [ { "in": "path", "name": "board", "description": "Board id or location in which the update takes place", "schema": { "type": "string", "description": "Board id or location in which the update takes place" }, "required": true, "example": "kanban" } ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID or identifier of the story" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" } }, "additionalProperties": { "type": "object" } }, "examples": { "Update the title of a story whose id is known": { "description": "Update the title of a story whose id is known", "value": { "title": "A new title" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" }, "linked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" } }, "required": [ "id", "identifier", "title" ], "additionalProperties": { "type": "object" } }, "description": "Linked stories" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachement unique ID" }, "filename": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "URL of the attachement, relative to the project's imgBaseUrl" }, "description": { "type": "string", "description": "Attachment description, if any" }, "sizeInBytes": { "type": "integer", "description": "Attachment size in bytes" }, "isCover": { "type": "boolean", "description": "Whether the attachment is used as story cover" }, "createdAt": { "type": "string", "description": "When was the attachent created" }, "createdBy": { "type": "string", "description": "Who created the attachent" } }, "required": [ "id", "filename", "url", "description", "sizeInBytes", "isCover", "createdAt", "createdBy" ] }, "description": "Story attachments" } }, "required": [ "id", "identifier", "title", "specification", "createdBy", "createdAt", "updatedAt", "linked", "attachments" ], "additionalProperties": { "type": "object" } }, "examples": { "Update the title of a story whose id is known": { "description": "Update the title of a story whose id is known", "value": { "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35", "identifier": 2, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "A new title", "createdAt": "2025-03-21T16:32:17+00:00", "createdBy": "Bernard", "updatedAt": "2025-09-01T12:27:54+00:00", "specification": "", "kind": "todo", "progress": "ongoing", "assignee": "Bernard", "due_date": null, "attachments": [], "linked": [] } } } } } } } }, "delete": { "summary": "Delete story", "description": "Deletes a single story", "tags": [ "Board stories" ], "parameters": [ { "in": "path", "name": "board", "schema": { "type": "string" }, "required": true, "example": "kanban" }, { "in": "path", "name": "story", "schema": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "required": true, "example": "8ed76538-ee9a-4b39-9407-6b392a7ddc35" } ], "security": [ { "OAuth2": [ "Member" ] } ], "responses": { "204": { "description": "" } } } }, "/boards/{board}/stories": { "summary": "Board stories", "post": { "summary": "Create story/stories", "description": "Creates a new story within the board.\n\nThe service also supports an Array of stories as input, and will create all\nof them and return them.", "tags": [ "Board stories" ], "parameters": [], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID or identifier of the story" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "URL of the attachement, relative to the project's imgBaseUrl" }, "isCover": { "type": "boolean", "description": "Whether the attachment is used as story cover" }, "description": { "type": "string", "description": "Whether the attachment is used as story cover" }, "sizeInBytes": { "type": "integer", "description": "Attachment size in bytes" } }, "required": [ "filename", "url", "isCover", "description", "sizeInBytes" ] }, "description": "List of story attachments to create" } }, "required": [ "title" ], "additionalProperties": { "type": "object" } }, "examples": { "Create a new story within the board": { "description": "Create a new story within the board", "value": { "kind": "todo", "progress": "ongoing", "assignee": "Bernard", "title": "Document the API" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" }, "linked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" } }, "required": [ "id", "identifier", "title" ], "additionalProperties": { "type": "object" } }, "description": "Linked stories" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachement unique ID" }, "filename": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "URL of the attachement, relative to the project's imgBaseUrl" }, "description": { "type": "string", "description": "Attachment description, if any" }, "sizeInBytes": { "type": "integer", "description": "Attachment size in bytes" }, "isCover": { "type": "boolean", "description": "Whether the attachment is used as story cover" }, "createdAt": { "type": "string", "description": "When was the attachent created" }, "createdBy": { "type": "string", "description": "Who created the attachent" } }, "required": [ "id", "filename", "url", "description", "sizeInBytes", "isCover", "createdAt", "createdBy" ] }, "description": "Story attachments" } }, "required": [ "id", "identifier", "title", "specification", "createdBy", "createdAt", "updatedAt", "linked", "attachments" ], "additionalProperties": { "type": "object" } }, "examples": { "Create a new story within the board": { "description": "Create a new story within the board", "value": { "id": "32eed28f-0076-415e-a85c-1866125d7be9", "identifier": 5, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "Document the API", "createdAt": "2025-09-01T12:27:55+00:00", "createdBy": "Bernard", "updatedAt": "2025-09-01T12:27:55+00:00", "specification": "", "kind": "todo", "progress": "ongoing", "assignee": "Bernard", "due_date": null, "attachments": [], "linked": [] } } } } } } } }, "patch": { "summary": "Update stories", "description": "Applies the same patch to many stories of the board", "tags": [ "Board stories" ], "parameters": [ { "in": "path", "name": "board", "description": "Either the board id or location", "schema": { "type": "string", "description": "Either the board id or location" }, "required": true, "example": "kanban" } ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "patch": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Story unique ID" } }, "required": [ "id" ], "additionalProperties": { "type": "object" } }, { "type": "object", "properties": { "identifier": { "type": "integer", "description": "Story unique identifier" } }, "required": [ "identifier" ], "additionalProperties": { "type": "object" } } ] }, "description": "Story patches to apply" } }, "required": [ "patch" ] }, "examples": { "Assigning multiple stories a once": { "description": "Assigning multiple stories a once", "value": { "patch": [ { "identifier": 2, "progress": "done" }, { "identifier": 4, "progress": "done" } ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" } }, "required": [ "id", "identifier", "title" ], "additionalProperties": { "type": "object" } } }, "examples": { "Assigning multiple stories a once": { "description": "Assigning multiple stories a once", "value": [ { "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35", "identifier": 2, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "Document the RESTful API", "createdAt": "2025-03-21T16:32:17+00:00", "createdBy": "Bernard", "updatedAt": "2025-09-01T12:27:54+00:00", "kind": "todo", "progress": "done", "assignee": "Bernard", "due_date": null }, { "id": "64751a76-d7dc-4695-b6c4-139f7082fc52", "identifier": 4, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "Make sur the World knows about us", "createdAt": "2025-03-21T16:32:17+00:00", "createdBy": "Bernard", "updatedAt": "2025-09-01T12:27:54+00:00", "kind": "todo", "progress": "done", "assignee": "Marc", "due_date": null } ] } } } } } } }, "delete": { "summary": "Delete stories", "description": "Deletes many stories present in the board", "tags": [ "Board stories" ], "parameters": [ { "in": "path", "name": "board", "description": "Either the board id or location", "schema": { "type": "string", "description": "Either the board id or location" }, "required": true, "example": "kanban" } ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stories": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, { "type": "object", "properties": { "identifier": { "type": "integer" } }, "required": [ "identifier" ] } ] }, "description": "List of story references to delete" } }, "required": [ "stories" ] }, "examples": { "Deleting many stories, based on their identifier": { "description": "Deleting many stories, based on their identifier", "value": { "stories": [ { "identifier": 1 }, { "identifier": 2 } ] } } } } } }, "responses": { "204": { "description": "" } } } }, "/boards/{id}/stories": { "summary": "Board", "get": { "summary": "Get stories", "description": "Returns the stories visible in the board.", "tags": [ "Board stories" ], "parameters": [ { "in": "path", "name": "id", "description": "Either the board id or location", "schema": { "type": "string", "description": "Either the board id or location" }, "required": true, "example": "kanban" } ], "security": [ { "OAuth2": [ "Anonymous" ] }, {} ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" } }, "required": [ "id", "identifier", "title" ], "additionalProperties": { "type": "object" } } }, "examples": { "Getting the stories in the kanban board, filtered on assignee": { "description": "Getting the stories in the kanban board, filtered on assignee", "value": [ { "id": "64751a76-d7dc-4695-b6c4-139f7082fc52", "identifier": 4, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "Make sur the World knows about us", "createdAt": "2025-03-21T16:32:17+00:00", "createdBy": "Bernard", "updatedAt": "2025-03-24T13:23:10+00:00", "kind": "todo", "progress": "ongoing", "assignee": "Marc", "due_date": null }, { "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35", "identifier": 2, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "Document the RESTful API", "createdAt": "2025-03-21T16:32:17+00:00", "createdBy": "Bernard", "updatedAt": "2025-03-24T13:23:07+00:00", "kind": "todo", "progress": "ongoing", "assignee": "Bernard", "due_date": null } ] } } } } } } } }, "/boards": { "summary": "Board", "post": { "summary": "Create board", "description": "Allows creating a new board", "tags": [ "Boards" ], "security": [ { "OAuth2": [ "Admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Board human friendly name" }, "location": { "type": "string", "description": "Board friendly location (used in url)" }, "mode": { "type": "string", "description": "Board mode (e.g. grid, list, kanban)" }, "connector": { "type": "string", "description": "Reserved (use BaseConnector)" }, "objective": { "type": "string", "description": "Board objective (shown to users on load)" }, "decksOpen": { "type": "boolean", "description": "Whether the filter decks are open on board load" }, "coloredDimension": { "type": "string", "description": "Dimension (code) used for card colors" }, "compactDisplay": { "type": "boolean", "description": "Whether empty columns/rows/categories are hidden" }, "compactDecks": { "type": "boolean", "description": "Whether unused values are hidden in filters" }, "explorerDecks": { "type": "boolean", "description": "Whether the filter decks use left-to-right layout" }, "displayDimensionLabels": { "type": "boolean", "description": "Whether dimension labels are shown on cards" }, "manualDimensionsInDecks": { "type": "boolean", "description": "Whether the user selected specific dimensions to be shown in decks" }, "displayDimensionsOnCards": { "type": "boolean", "description": "Whether dimensions are shown on cards" }, "displayNoneOnCards": { "type": "boolean", "description": "Whether empty values are shown on carts" }, "background": { "type": "string", "description": "Name of the board background" }, "anchors": { "type": "object", "properties": { "decks": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show in filters deck" }, "displayBy": { "type": "array", "items": { "type": "string" }, "description": "Dimension(s) used to group cards in board" }, "cards": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show on cards" }, "ordering": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to use to sort cards in board" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Dimensions required in the board" }, "gantt": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used for Gantt mode" }, "hierarchyBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to hierarchy in List mode" }, "seriesBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to as series in Chart mode" }, "rowsBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used as rows in Matrix mode" } }, "additionalProperties": {}, "description": "List of board anchors, see Data Model" }, "anchorOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } } }, "required": [ "autoDimValues" ] } }, "description": "Anchors options" }, "filters": { "type": "object", "description": "List of board filters, see Data Model" }, "summaries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Summary function code" }, "label": { "type": "string", "description": "Summary function label" }, "ordering": { "type": "integer", "description": "Summary order index in collection" }, "expr": { "type": "string", "description": "Formal expression" } }, "required": [ "code" ], "additionalProperties": {} }, "description": "List of board summaries shown" }, "workspacePermissions": { "type": "array", "items": { "type": "object", "properties": { "workspace": { "type": "string", "description": "Workspace code" }, "canRead": { "type": "boolean", "description": "Whether the users can read cards" }, "canWrite": { "type": "boolean", "description": "Whether the users can write cards" }, "canManage": { "type": "boolean", "description": "Whether the users can manage cards" } }, "required": [ "workspace", "canRead", "canWrite", "canManage" ] }, "description": "List of workspaces permissions on this board" }, "extraSettings": { "type": "object", "properties": { "onCardClick": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Action options" } }, "required": [ "type", "options" ], "description": "Behavior on card click" }, "swipeGestures": { "type": "object", "properties": { "left": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping left" }, "right": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping right" }, "up": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping up" }, "down": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping down" } }, "description": "Behavior when swiping on mobile" }, "chartOptions": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "description": "Options for chart mode" } }, "description": "Extra board settings used by the various modes" } }, "required": [ "label", "location", "mode", "objective", "decksOpen", "coloredDimension", "compactDisplay", "compactDecks", "explorerDecks", "displayDimensionLabels", "manualDimensionsInDecks", "displayDimensionsOnCards", "displayNoneOnCards", "background", "anchors", "filters", "summaries", "workspacePermissions" ], "additionalProperties": {} }, "examples": { "Create a new grid board with a filter along the progress dimension": { "description": "Create a new grid board with a filter along the progress dimension", "value": { "connector": "BaseConnector", "label": "Todo grid", "location": "todo-grid", "mode": "grid", "objective": "Show the todos in a grid view", "decksOpen": false, "coloredDimension": "kind", "compactDisplay": true, "compactDecks": true, "explorerDecks": true, "manualDimensionsInDecks": true, "displayDimensionLabels": false, "displayDimensionsOnCards": true, "displayNoneOnCards": true, "background": "sunset", "anchors": {}, "summaries": [], "filters": { "progress": "todo" }, "workspacePermissions": [ { "workspace": "admins", "canRead": true, "canWrite": true, "canManage": true } ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Board unique ID" }, "label": { "type": "string", "description": "Board human friendly name" }, "location": { "type": "string", "description": "Board friendly location (used in url)" }, "mode": { "type": "string", "description": "Board mode (e.g. grid, list, kanban)" }, "connector": { "type": "string", "description": "Reserved (use BaseConnector)" }, "objective": { "type": "string", "description": "Board objective (shown to users on load)" }, "objectiveModal": { "type": "boolean", "description": "Whether the objective must be shown to users" }, "decksOpen": { "type": "boolean", "description": "Whether the filter decks are open on board load" }, "coloredDimension": { "type": "string", "description": "Dimension (code) used for card colors" }, "compactDisplay": { "type": "boolean", "description": "Whether empty columns/rows/categories are hidden" }, "compactDecks": { "type": "boolean", "description": "Whether unused values are hidden in filters" }, "explorerDecks": { "type": "boolean", "description": "Whether the filter decks use left-to-right layout" }, "background": { "type": "string", "description": "Name of the board background" }, "createdBy": { "type": "string", "description": "Who created the board" }, "createdAt": { "type": "string", "description": "When was the board created" }, "ordering": { "type": "integer", "description": "Order index of the board in the collection" }, "ganttScale": { "type": "string", "description": "Scale used in the gantt mode" }, "manualDimensionsInDecks": { "type": "boolean", "description": "Whether the user selected specific dimensions to be shown in decks" }, "displayDimensionsOnCards": { "type": "boolean", "description": "Whether dimensions are shown on cards" }, "displayDimensionLabels": { "type": "boolean", "description": "Whether dimension labels are shown on cards" }, "displayNoneOnCards": { "type": "boolean", "description": "Whether empty values are shown on carts" }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Dimension unique ID" }, "code": { "type": "string", "description": "Dimension code (used in URLs, filters, anchors, etc.)" }, "datatype": { "type": "string", "description": "Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "supportsRequired": { "type": "boolean", "description": "Whether the users can decided whether the dimension is required" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "supportsTagging": { "type": "boolean", "description": "Whether users can choose to lock/unlock the dimension" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "supportsMultiple": { "type": "boolean", "description": "Whether the dimension datatype supports multiple values" }, "supportsAlphabeticalOrdering": { "type": "boolean", "description": "Whether values can be ordered alphabetically" }, "userEditable": { "type": "boolean", "description": "Whether values can be choosen by end-users on cards" }, "attribute": { "type": "boolean", "description": "Whether this dimension is a fixed card attribute (deprecated)" }, "supportsColor": { "type": "boolean", "description": "Whether the dimension supports colors on values" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "description": "The dimension list of values" }, "deleted": { "type": "boolean", "description": "Whether the dimension has been deleted" }, "deletedAt": { "type": "string", "description": "When this dimension was deleted, if deleted" }, "deletedBy": { "type": "string", "description": "Who deleted this dimension, if deleted" } }, "required": [ "id", "code", "datatype", "datatypeOptions", "label", "description", "required", "supportsRequired", "tagging", "supportsTagging", "multiple", "supportsMultiple", "supportsAlphabeticalOrdering", "userEditable", "attribute", "supportsColor", "ordering", "semanticsType", "relevantKinds", "values", "deleted", "deletedAt", "deletedBy" ] }, "description": "List of board dimensions" }, "anchors": { "type": "object", "properties": { "decks": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show in filters deck" }, "displayBy": { "type": "array", "items": { "type": "string" }, "description": "Dimension(s) used to group cards in board" }, "cards": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to show on cards" }, "ordering": { "type": "array", "items": { "type": "string" }, "description": "Dimensions to use to sort cards in board" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Dimensions required in the board" }, "gantt": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used for Gantt mode" }, "hierarchyBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to hierarchy in List mode" }, "seriesBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used to as series in Chart mode" }, "rowsBy": { "type": "array", "items": { "type": "string" }, "description": "Dimensions used as rows in Matrix mode" } }, "additionalProperties": {}, "description": "List of board anchors, see Data Model" }, "anchorOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } } }, "required": [ "autoDimValues" ] } }, "description": "Anchors options" }, "filters": { "type": "object", "description": "List of board filters, see Data Model" }, "workspacePermissions": { "type": "array", "items": { "type": "object", "properties": { "workspace": { "type": "string", "description": "Workspace code" }, "canRead": { "type": "boolean", "description": "Whether the users can read cards" }, "canWrite": { "type": "boolean", "description": "Whether the users can write cards" }, "canManage": { "type": "boolean", "description": "Whether the users can manage cards" } }, "required": [ "workspace", "canRead", "canWrite", "canManage" ] }, "description": "List of workspaces permissions on this board" }, "summaries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Summary function code" }, "label": { "type": "string", "description": "Summary function label" }, "expr": { "type": "string", "description": "Formal expression" }, "ordering": { "type": "integer", "description": "Summary order index in collection" } }, "required": [ "code", "label", "expr", "ordering" ] }, "description": "List of board summaries shown" }, "importers": { "type": "array", "items": { "type": "object" }, "description": "List of board importers" }, "extraSettings": { "type": "object", "properties": { "onCardClick": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "options": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Action options" } }, "required": [ "type", "options" ], "description": "Behavior on card click" }, "swipeGestures": { "type": "object", "properties": { "left": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping left" }, "right": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping right" }, "up": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping up" }, "down": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of action" }, "value": { "type": "string", "description": "Dimension value ID, if any" } }, "required": [ "type" ], "description": "Behavior when swipping down" } }, "description": "Behavior when swiping on mobile" }, "chartOptions": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "description": "Options for chart mode" } }, "description": "Extra board settings used by the various modes" } }, "required": [ "id", "label", "location", "mode", "connector", "objective", "objectiveModal", "decksOpen", "coloredDimension", "compactDisplay", "compactDecks", "explorerDecks", "background", "createdBy", "createdAt", "ordering", "ganttScale", "manualDimensionsInDecks", "displayDimensionsOnCards", "displayDimensionLabels", "displayNoneOnCards", "dimensions", "anchors", "anchorOptions", "filters", "workspacePermissions", "summaries", "extraSettings" ] }, "examples": { "Create a new grid board with a filter along the progress dimension": { "description": "Create a new grid board with a filter along the progress dimension", "value": { "id": "cca5dbf7-3c61-45da-8058-91d5f7539df6", "label": "Todo grid", "location": "todo-grid", "mode": "grid", "objective": "Show the todos in a grid view", "objectiveModal": false, "decksOpen": false, "coloredDimension": "kind", "compactDisplay": true, "compactDecks": true, "explorerDecks": true, "background": "sunset", "anchors": {}, "anchorOptions": {}, "filters": { "progress": [ "todo" ] }, "summaries": [], "workspacePermissions": [ { "workspace": "admins", "canRead": true, "canWrite": true, "canManage": true } ], "createdBy": "Bernard", "createdAt": "2025-09-01T12:27:55+00:00", "dimensions": [ { "code": "kind", "ordering": 20000, "label": "Kind", "tagging": true, "multiple": false, "required": true, "id": "0d3c755c-b3d3-4940-947e-e90de07e571f", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Kind", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "color": "#b7137e", "ordering": 1000000, "semantics": null, "colorDimension": null, "description": null, "placeholder": null, "deprecated": false, "summaryDimensions": [] } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "identifier", "ordering": 1000, "label": "Card n°", "tagging": false, "multiple": false, "required": true, "id": "af352fc7-8c9b-4030-934e-da0b1f737741", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Identifier", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": false }, { "code": "title", "ordering": 1010, "label": "Card title", "tagging": false, "multiple": false, "required": false, "id": "4e5bf2b8-b0d3-4f5d-b966-e017f7feadda", "deleted": false, "deletedAt": null, "deletedBy": null, "description": "Card title", "semanticsType": null, "datatype": "Title", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": true }, { "code": "specification", "ordering": 1011, "label": "Card description", "tagging": false, "multiple": false, "required": false, "id": "039fdea8-4dd7-488f-85f5-38f2c11eff8a", "deleted": false, "deletedAt": null, "deletedBy": null, "description": "Card (Markdown) description", "semanticsType": null, "datatype": "Specification", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": true }, { "code": "progress", "ordering": 120000, "label": "Progress", "tagging": true, "multiple": false, "required": false, "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Progress", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "ordering": 10000, "color": "#e01514", "semantics": null, "description": null, "deprecated": false }, { "id": "ongoing", "label": "Ongoing", "ordering": 20000, "color": "#f77d00", "semantics": null, "description": null, "deprecated": false }, { "id": "done", "label": "Done", "ordering": 30000, "color": "#00b048", "semantics": null, "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "assignee", "ordering": 220000, "label": "Assignee", "tagging": true, "multiple": false, "required": false, "id": "0334196e-1aba-4049-9769-b8fde2eb2227", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "ProjectMember", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "Bernard", "label": "Bernard", "ordering": 1000000, "color": "#ffffff", "semantics": "Bernard", "description": null, "deprecated": false }, { "id": "Victor", "label": "Victor", "ordering": 2000000, "color": "#ffffff", "semantics": "Victor", "description": null, "deprecated": false }, { "id": "Marc", "label": "Marc", "ordering": 3000000, "color": "#ffffff", "semantics": "Marc", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": true, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "due_date", "ordering": 320000, "label": "Due date", "tagging": false, "multiple": false, "required": false, "id": "44c78647-0a68-48a2-b6e0-0fd926752f4f", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": "DateRange", "datatype": "DueDate", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "late_", "label": "Late!", "ordering": 10000, "color": "#202020", "semantics": "-BOT", "description": null, "deprecated": false }, { "id": "late_tomorrow", "label": "Late tomorrow", "ordering": 20000, "color": "#e01514", "semantics": "+P1D", "description": null, "deprecated": false }, { "id": "late_in_3_days", "label": "Late in 3 days", "ordering": 30000, "color": "#a85319", "semantics": "+P1D .. +P3D", "description": null, "deprecated": false }, { "id": "next_7_days", "label": "Next 7 days", "ordering": 40000, "color": "#ffba00", "semantics": "+P3D .. +P7D", "description": null, "deprecated": false }, { "id": "next_15_days", "label": "Next 15 days", "ordering": 50000, "color": "#99cc2d", "semantics": "+P7D .. +P15D", "description": null, "deprecated": false }, { "id": "next_30_days", "label": "Next 30 days", "ordering": 60000, "color": "#00b048", "semantics": "+P15D .. +P30D", "description": null, "deprecated": false }, { "id": "later", "label": "Later", "ordering": 70000, "color": "#00b048", "semantics": "+P30D .. P100Y", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": false, "supportsColor": true, "userEditable": true } ], "ordering": 3, "ganttScale": null, "displayDimensionLabels": false, "manualDimensionsInDecks": true, "displayDimensionsOnCards": true, "displayNoneOnCards": true, "connector": "BaseConnector", "importers": [], "extraSettings": {} } } } } } } } } }, "/dimensions/{id}": { "summary": "Dimension", "get": { "summary": "Get dimension", "description": "Returns a given dimension", "tags": [ "Dimensions" ], "parameters": [ { "in": "path", "name": "id", "description": "Either the dimension id or code", "schema": { "type": "string", "description": "Either the dimension id or code" }, "required": true, "example": "progress" } ], "security": [ { "OAuth2": [ "Member" ] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Dimension unique ID" }, "code": { "type": "string", "description": "Dimension code (used in URLs, filters, anchors, etc.)" }, "datatype": { "type": "string", "description": "Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "supportsRequired": { "type": "boolean", "description": "Whether the users can decided whether the dimension is required" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "supportsTagging": { "type": "boolean", "description": "Whether users can choose to lock/unlock the dimension" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "supportsMultiple": { "type": "boolean", "description": "Whether the dimension datatype supports multiple values" }, "supportsAlphabeticalOrdering": { "type": "boolean", "description": "Whether values can be ordered alphabetically" }, "userEditable": { "type": "boolean", "description": "Whether values can be choosen by end-users on cards" }, "attribute": { "type": "boolean", "description": "Whether this dimension is a fixed card attribute (deprecated)" }, "supportsColor": { "type": "boolean", "description": "Whether the dimension supports colors on values" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "description": "The dimension list of values" }, "deleted": { "type": "boolean", "description": "Whether the dimension has been deleted" }, "deletedAt": { "type": "string", "description": "When this dimension was deleted, if deleted" }, "deletedBy": { "type": "string", "description": "Who deleted this dimension, if deleted" } }, "required": [ "id", "code", "datatype", "datatypeOptions", "label", "description", "required", "supportsRequired", "tagging", "supportsTagging", "multiple", "supportsMultiple", "supportsAlphabeticalOrdering", "userEditable", "attribute", "supportsColor", "ordering", "semanticsType", "relevantKinds", "values", "deleted", "deletedAt", "deletedBy" ] }, "examples": { "Get a dimension, you can use either its ID or code as URL parameter": { "description": "Get a dimension, you can use either its ID or code as URL parameter", "value": { "code": "progress", "ordering": 120000, "label": "Progress", "tagging": true, "multiple": false, "required": false, "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Progress", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "ordering": 10000, "color": "#e01514", "semantics": null, "description": null, "deprecated": false }, { "id": "ongoing", "label": "Ongoing", "ordering": 20000, "color": "#f77d00", "semantics": null, "description": null, "deprecated": false }, { "id": "done", "label": "Done", "ordering": 30000, "color": "#00b048", "semantics": null, "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true } } } } } } } }, "patch": { "summary": "Update dimension", "description": "Allows updating an existing project dimension", "tags": [ "Dimensions" ], "parameters": [ { "in": "path", "name": "id", "description": "Either the dimension id or code", "schema": { "type": "string", "description": "Either the dimension id or code" }, "required": true, "example": "progress" } ], "security": [ { "OAuth2": [ "Admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" } } }, "examples": { "Update a dimension, you can use either its ID or code as URL parameter": { "description": "Update a dimension, you can use either its ID or code as URL parameter", "value": { "label": "Status" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Dimension unique ID" }, "code": { "type": "string", "description": "Dimension code (used in URLs, filters, anchors, etc.)" }, "datatype": { "type": "string", "description": "Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "supportsRequired": { "type": "boolean", "description": "Whether the users can decided whether the dimension is required" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "supportsTagging": { "type": "boolean", "description": "Whether users can choose to lock/unlock the dimension" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "supportsMultiple": { "type": "boolean", "description": "Whether the dimension datatype supports multiple values" }, "supportsAlphabeticalOrdering": { "type": "boolean", "description": "Whether values can be ordered alphabetically" }, "userEditable": { "type": "boolean", "description": "Whether values can be choosen by end-users on cards" }, "attribute": { "type": "boolean", "description": "Whether this dimension is a fixed card attribute (deprecated)" }, "supportsColor": { "type": "boolean", "description": "Whether the dimension supports colors on values" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "description": "The dimension list of values" }, "deleted": { "type": "boolean", "description": "Whether the dimension has been deleted" }, "deletedAt": { "type": "string", "description": "When this dimension was deleted, if deleted" }, "deletedBy": { "type": "string", "description": "Who deleted this dimension, if deleted" } }, "required": [ "id", "code", "datatype", "datatypeOptions", "label", "description", "required", "supportsRequired", "tagging", "supportsTagging", "multiple", "supportsMultiple", "supportsAlphabeticalOrdering", "userEditable", "attribute", "supportsColor", "ordering", "semanticsType", "relevantKinds", "values", "deleted", "deletedAt", "deletedBy" ] }, "examples": { "Update a dimension, you can use either its ID or code as URL parameter": { "description": "Update a dimension, you can use either its ID or code as URL parameter", "value": { "code": "status", "ordering": 120000, "label": "Status", "tagging": true, "multiple": false, "required": false, "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Progress", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "semantics": null, "ordering": 10000, "color": "#e01514", "description": null, "deprecated": false }, { "id": "ongoing", "label": "Ongoing", "semantics": null, "ordering": 20000, "color": "#f77d00", "description": null, "deprecated": false }, { "id": "done", "label": "Done", "semantics": null, "ordering": 30000, "color": "#00b048", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true } } } } } } } }, "delete": { "summary": "Delete dimension", "description": "Allows deleting a dimension", "tags": [ "Dimensions" ], "parameters": [ { "in": "path", "name": "id", "description": "Either the dimension id or code", "schema": { "type": "string", "description": "Either the dimension id or code" }, "required": true, "example": "progress" } ], "security": [ { "OAuth2": [ "Admin" ] } ], "responses": { "204": { "description": "" } } } }, "/dimensions/{dimension}/values/{id}": { "summary": "Dimension value", "get": { "summary": "Get dimension value", "description": "Returns the details of a dimension value", "tags": [ "Dimension values" ], "parameters": [ { "in": "path", "name": "dimension", "schema": { "type": "string" }, "required": true, "example": "progress" }, { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true, "example": "ongoing" } ], "security": [ { "OAuth2": [ "Member" ] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "examples": { "Getting the ongoing value of the progress dimension": { "description": "Getting the ongoing value of the progress dimension", "value": { "id": "ongoing", "label": "Ongoing", "ordering": 20000, "color": "#f77d00", "semantics": null, "description": null, "deprecated": false } } } } } } } }, "patch": { "summary": "Update dimension value", "description": "Allows updating a dimension value", "tags": [ "Dimension values" ], "parameters": [ { "in": "path", "name": "dimension", "description": "Dimension id or code", "schema": { "type": "string", "description": "Dimension id or code" }, "required": true, "example": "progress" }, { "in": "path", "name": "id", "description": "Value id", "schema": { "type": "string", "description": "Value id" }, "required": true, "example": "ongoing" } ], "security": [ { "OAuth2": [ "Admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" } }, "additionalProperties": {} }, "examples": { "Changing the label of the Ongoing progress step": { "description": "Changing the label of the Ongoing progress step", "value": { "label": "Current work" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "examples": { "Changing the label of the Ongoing progress step": { "description": "Changing the label of the Ongoing progress step", "value": { "id": "ongoing", "label": "Current work", "ordering": 20000, "color": "#f77d00", "semantics": null, "description": null, "deprecated": false } } } } } } } }, "delete": { "summary": "Delete dimension value", "description": "Deletes a given dimension value, replacing it by another value if needed", "tags": [ "Dimension values" ], "parameters": [ { "in": "path", "name": "dimension", "description": "Dimension id or code", "schema": { "type": "string", "description": "Dimension id or code" }, "required": true, "example": "progress" }, { "in": "path", "name": "id", "description": "Value id", "schema": { "type": "string", "description": "Value id" }, "required": true, "example": "ongoing" } ], "security": [ { "OAuth2": [ "Admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "onExisting": { "type": "string", "description": "Behavior if a value is used (fail, setNone, or replace)" }, "replaceBy": { "type": "string", "description": "ID of the replacement value, if any" } }, "required": [ "onExisting" ] }, "examples": { "Dropping the ongoing step, and moving all cards to todo": { "description": "Dropping the ongoing step, and moving all cards to todo", "value": { "onExisting": "replace", "replaceBy": "todo" } } } } } }, "responses": { "204": { "description": "" } } } }, "/dimensions/{dimension}/values": { "summary": "Dimension value", "post": { "summary": "Create dimension value", "description": "Creates a new dimension value", "tags": [ "Dimension values" ], "parameters": [ { "in": "path", "name": "dimension", "description": "Dimension id or code", "schema": { "type": "string", "description": "Dimension id or code" }, "required": true, "example": "progress" } ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Value id" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" } }, "required": [ "label" ], "additionalProperties": {} }, "examples": { "Creating an Abandonned step along the progress dimension": { "description": "Creating an Abandonned step along the progress dimension", "value": { "code": "abandonned", "label": "Abandonned", "color": "black", "ordering": 99, "semantics": null, "description": "Drop here when a task has been abandonned" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "examples": { "Creating an Abandonned step along the progress dimension": { "description": "Creating an Abandonned step along the progress dimension", "value": { "id": "abandonned", "label": "Abandonned", "ordering": 99, "color": "black", "semantics": null, "description": "Drop here when a task has been abandonned", "deprecated": false } } } } } } } } }, "/dimensions": { "summary": "Dimension", "get": { "summary": "Get dimensions", "description": "Returns the list of project dimensions", "tags": [ "Dimensions" ], "parameters": [], "security": [ { "OAuth2": [ "Member" ] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Dimension unique ID" }, "code": { "type": "string", "description": "Dimension code (used in URLs, filters, anchors, etc.)" }, "datatype": { "type": "string", "description": "Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "supportsRequired": { "type": "boolean", "description": "Whether the users can decided whether the dimension is required" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "supportsTagging": { "type": "boolean", "description": "Whether users can choose to lock/unlock the dimension" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "supportsMultiple": { "type": "boolean", "description": "Whether the dimension datatype supports multiple values" }, "supportsAlphabeticalOrdering": { "type": "boolean", "description": "Whether values can be ordered alphabetically" }, "userEditable": { "type": "boolean", "description": "Whether values can be choosen by end-users on cards" }, "attribute": { "type": "boolean", "description": "Whether this dimension is a fixed card attribute (deprecated)" }, "supportsColor": { "type": "boolean", "description": "Whether the dimension supports colors on values" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "description": "The dimension list of values" }, "deleted": { "type": "boolean", "description": "Whether the dimension has been deleted" }, "deletedAt": { "type": "string", "description": "When this dimension was deleted, if deleted" }, "deletedBy": { "type": "string", "description": "Who deleted this dimension, if deleted" } }, "required": [ "id", "code", "datatype", "datatypeOptions", "label", "description", "required", "supportsRequired", "tagging", "supportsTagging", "multiple", "supportsMultiple", "supportsAlphabeticalOrdering", "userEditable", "attribute", "supportsColor", "ordering", "semanticsType", "relevantKinds", "values", "deleted", "deletedAt", "deletedBy" ] } }, "examples": { "Get the dimensions": { "description": "Get the dimensions", "value": [ { "code": "identifier", "ordering": 1000, "label": "Card n°", "tagging": false, "multiple": false, "required": true, "id": "af352fc7-8c9b-4030-934e-da0b1f737741", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Identifier", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": false }, { "code": "title", "ordering": 1010, "label": "Card title", "tagging": false, "multiple": false, "required": false, "id": "4e5bf2b8-b0d3-4f5d-b966-e017f7feadda", "deleted": false, "deletedAt": null, "deletedBy": null, "description": "Card title", "semanticsType": null, "datatype": "Title", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": true }, { "code": "specification", "ordering": 1011, "label": "Card description", "tagging": false, "multiple": false, "required": false, "id": "039fdea8-4dd7-488f-85f5-38f2c11eff8a", "deleted": false, "deletedAt": null, "deletedBy": null, "description": "Card (Markdown) description", "semanticsType": null, "datatype": "Specification", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false } ], "attribute": true, "supportsMultiple": false, "supportsRequired": false, "supportsTagging": false, "supportsAlphabeticalOrdering": false, "supportsColor": false, "userEditable": true }, { "code": "kind", "ordering": 20000, "label": "Kind", "tagging": true, "multiple": false, "required": true, "id": "0d3c755c-b3d3-4940-947e-e90de07e571f", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Kind", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "color": "#b7137e", "ordering": 1000000, "semantics": null, "colorDimension": null, "description": null, "placeholder": null, "deprecated": false, "summaryDimensions": [] } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "progress", "ordering": 120000, "label": "Progress", "tagging": true, "multiple": false, "required": false, "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "Progress", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "todo", "label": "Todo", "ordering": 10000, "color": "#e01514", "semantics": null, "description": null, "deprecated": false }, { "id": "ongoing", "label": "Ongoing", "ordering": 20000, "color": "#f77d00", "semantics": null, "description": null, "deprecated": false }, { "id": "done", "label": "Done", "ordering": 30000, "color": "#00b048", "semantics": null, "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "assignee", "ordering": 220000, "label": "Assignee", "tagging": true, "multiple": false, "required": false, "id": "0334196e-1aba-4049-9769-b8fde2eb2227", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "ProjectMember", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "Bernard", "label": "Bernard", "ordering": 1000000, "color": "#ffffff", "semantics": "Bernard", "description": null, "deprecated": false }, { "id": "Victor", "label": "Victor", "ordering": 2000000, "color": "#ffffff", "semantics": "Victor", "description": null, "deprecated": false }, { "id": "Marc", "label": "Marc", "ordering": 3000000, "color": "#ffffff", "semantics": "Marc", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": true, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true }, { "code": "due_date", "ordering": 320000, "label": "Due date", "tagging": false, "multiple": false, "required": false, "id": "44c78647-0a68-48a2-b6e0-0fd926752f4f", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": "DateRange", "datatype": "DueDate", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "late_", "label": "Late!", "ordering": 10000, "color": "#202020", "semantics": "-BOT", "description": null, "deprecated": false }, { "id": "late_tomorrow", "label": "Late tomorrow", "ordering": 20000, "color": "#e01514", "semantics": "+P1D", "description": null, "deprecated": false }, { "id": "late_in_3_days", "label": "Late in 3 days", "ordering": 30000, "color": "#a85319", "semantics": "+P1D .. +P3D", "description": null, "deprecated": false }, { "id": "next_7_days", "label": "Next 7 days", "ordering": 40000, "color": "#ffba00", "semantics": "+P3D .. +P7D", "description": null, "deprecated": false }, { "id": "next_15_days", "label": "Next 15 days", "ordering": 50000, "color": "#99cc2d", "semantics": "+P7D .. +P15D", "description": null, "deprecated": false }, { "id": "next_30_days", "label": "Next 30 days", "ordering": 60000, "color": "#00b048", "semantics": "+P15D .. +P30D", "description": null, "deprecated": false }, { "id": "later", "label": "Later", "ordering": 70000, "color": "#00b048", "semantics": "+P30D .. P100Y", "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": false, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": false, "supportsColor": true, "userEditable": true } ] } } } } } } }, "post": { "summary": "Create dimension", "description": "Creates a new project dimension", "tags": [ "Dimensions" ], "security": [ { "OAuth2": [ "Admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "datatype": { "type": "string", "description": "Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" }, "values": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Dimension id or code" }, "id": { "type": "string", "description": "Value id" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" } }, "required": [ "label" ], "additionalProperties": {} }, "description": "The dimension list of values" } }, "required": [ "label", "tagging", "required", "multiple" ], "additionalProperties": {} }, "examples": { "Use the UserDefined datatype to create a new \"Track your own list\" dimension": { "description": "Use the UserDefined datatype to create a new \"Track your own list\" dimension", "value": { "label": "Priority", "required": true, "multiple": true, "tagging": false, "datatype": "UserDefined", "datatypeOptions": {}, "values": [ { "id": "low", "label": "Low" }, { "id": "medium", "label": "Medium" }, { "id": "high", "label": "High" } ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Dimension unique ID" }, "code": { "type": "string", "description": "Dimension code (used in URLs, filters, anchors, etc.)" }, "datatype": { "type": "string", "description": "Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)" }, "datatypeOptions": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "unit": { "type": "string" }, "formaldef": { "type": "string" }, "childCardsRole": { "type": "string" }, "hideOnChild": { "type": "boolean" }, "workspace": { "type": "string" }, "filters": { "type": "object" }, "onClick": { "type": "string" }, "along": { "type": "string" }, "autoDimValues": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "strategy": { "type": "string" } } }, "dataFormatOptions": { "type": "object", "properties": { "style": { "type": "string" } }, "required": [ "style" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } } }, "description": "Options of the datatype, configuring behavior" }, "label": { "type": "string", "description": "Dimension human friendly name" }, "description": { "type": "string", "description": "Dimension long description, if any" }, "required": { "type": "boolean", "description": "Whether a value is required on cards" }, "supportsRequired": { "type": "boolean", "description": "Whether the users can decided whether the dimension is required" }, "tagging": { "type": "boolean", "description": "Whether users can add/edit values in boards and cards (aka unlocked)" }, "supportsTagging": { "type": "boolean", "description": "Whether users can choose to lock/unlock the dimension" }, "multiple": { "type": "boolean", "description": "Whether multiple values can be choosen on cards" }, "supportsMultiple": { "type": "boolean", "description": "Whether the dimension datatype supports multiple values" }, "supportsAlphabeticalOrdering": { "type": "boolean", "description": "Whether values can be ordered alphabetically" }, "userEditable": { "type": "boolean", "description": "Whether values can be choosen by end-users on cards" }, "attribute": { "type": "boolean", "description": "Whether this dimension is a fixed card attribute (deprecated)" }, "supportsColor": { "type": "boolean", "description": "Whether the dimension supports colors on values" }, "ordering": { "type": "integer", "description": "Order index of the dimension in the project" }, "semanticsType": { "type": "string", "description": "Semantics of the dimension values" }, "relevantKinds": { "type": "array", "items": { "type": "string" }, "description": "For what card kinds this dimension is relevant" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the value (unique inside the dimension)" }, "label": { "type": "string", "description": "Human friendly label of the value" }, "semantics": { "type": "string", "description": "Filtering semantics, if any" }, "color": { "type": "string", "description": "Value color, if any" }, "ordering": { "type": "integer", "description": "Ordering of the value within the collection" }, "description": { "type": "string", "description": "Description of the value, if any" }, "placeholder": { "type": "string", "description": "Placeholder of the value, if any" }, "deprecated": { "type": "boolean", "description": "Whether the value is deprecated" } }, "required": [ "id", "label", "semantics", "color", "ordering", "deprecated" ], "additionalProperties": { "type": "object" } }, "description": "The dimension list of values" }, "deleted": { "type": "boolean", "description": "Whether the dimension has been deleted" }, "deletedAt": { "type": "string", "description": "When this dimension was deleted, if deleted" }, "deletedBy": { "type": "string", "description": "Who deleted this dimension, if deleted" } }, "required": [ "id", "code", "datatype", "datatypeOptions", "label", "description", "required", "supportsRequired", "tagging", "supportsTagging", "multiple", "supportsMultiple", "supportsAlphabeticalOrdering", "userEditable", "attribute", "supportsColor", "ordering", "semanticsType", "relevantKinds", "values", "deleted", "deletedAt", "deletedBy" ] }, "examples": { "Use the UserDefined datatype to create a new \"Track your own list\" dimension": { "description": "Use the UserDefined datatype to create a new \"Track your own list\" dimension", "value": { "code": "priority", "ordering": 420000, "label": "Priority", "tagging": false, "multiple": true, "required": true, "id": "7d86ddda-9097-4d7d-8923-55f3e75fa120", "deleted": false, "deletedAt": null, "deletedBy": null, "description": null, "semanticsType": null, "datatype": "UserDefined", "datatypeOptions": {}, "relevantKinds": [], "values": [ { "id": null, "label": "No value", "semantics": null, "ordering": -1, "color": "#ffffff", "description": null, "deprecated": false }, { "id": "low", "label": "Low", "ordering": 10000, "color": "#ffffff", "semantics": null, "description": null, "deprecated": false }, { "id": "medium", "label": "Medium", "ordering": 20000, "color": "#ffffff", "semantics": null, "description": null, "deprecated": false }, { "id": "high", "label": "High", "ordering": 30000, "color": "#ffffff", "semantics": null, "description": null, "deprecated": false } ], "attribute": false, "supportsMultiple": true, "supportsRequired": true, "supportsTagging": true, "supportsAlphabeticalOrdering": true, "supportsColor": true, "userEditable": true } } } } } } } } }, "/danger-zone/delete-all-stories": { "summary": "Project", "post": { "summary": "Delete all stories", "description": "Deletes all stories of the current project", "tags": [ "Danger zone" ], "parameters": [], "security": [ { "OAuth2": [ "Owner" ] } ], "responses": { "204": { "description": "" } } } }, "/danger-zone/delete-project": { "summary": "Project", "post": { "summary": "Delete project", "description": "Deletes the current project", "tags": [ "Danger zone" ], "parameters": [], "security": [ { "OAuth2": [ "Owner" ] } ], "responses": { "204": { "description": "" } } } }, "/danger-zone/duplicate-project": { "summary": "Root project", "post": { "summary": "Duplicate project", "description": "Duplicates a project, with the option to keep the cards or the members.", "tags": [ "Danger zone" ], "security": [ { "OAuth2": [ "Owner" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subdomain": { "type": "string" }, "keepCards": { "type": "boolean" }, "keepMembers": { "type": "boolean" } }, "required": [ "name", "subdomain", "keepCards", "keepMembers" ] }, "examples": { "Duplicating a project while keeping cards but not members": { "description": "Duplicating a project while keeping cards but not members", "value": { "name": "Hello Klaro", "subdomain": "a-duplicate", "keepCards": true, "keepMembers": false } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string" } }, "required": [ "location" ] }, "examples": { "Duplicating a project while keeping cards but not members": { "description": "Duplicating a project while keeping cards but not members", "value": { "location": "http://a-duplicate.klaro.devel/" } } } } } } } } }, "": { "summary": "Root project", "get": { "summary": "Get project", "description": "Returns information about the current project", "tags": [ "Projects" ], "parameters": [], "security": [ { "OAuth2": [ "Anonymous" ] }, {} ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project's unique ID" }, "name": { "type": "string", "description": "Project's human friendly name" }, "subdomain": { "type": "string", "description": "Subdomain of the instance where the project is hosted" }, "isPublic": { "type": "boolean", "description": "Whether this project is public" }, "isTemplate": { "type": "boolean", "description": "Whether this project is a template" }, "isBlocked": { "type": "boolean", "description": "Whether this project has been blocked by administrators" }, "isLocked": { "type": "boolean", "description": "(deprecated)" }, "timezone": { "type": "string", "description": "Project's timezone" }, "locale": { "type": "string", "description": "Project's locale, e.g. en-US or fr-BE" }, "url": { "type": "string", "description": "URL where users can reach the project" }, "imgBaseUrl": { "type": "string", "description": "Base URL for card images" }, "logoUrl": { "type": "string", "description": "URL for the project logo" }, "revision": { "type": "integer", "description": "Revision number of the project (increased when settings change)" }, "createdAt": { "type": "string", "description": "When was the project created" }, "updatedAt": { "type": "string", "description": "When was the project last updated" }, "title": { "type": "string", "description": "Project marketing title, if any" }, "summary": { "type": "string", "description": "Project marketing summary, if any" }, "description": { "type": "string", "description": "Project marketing description, if any" }, "imageUrl": { "type": "string", "description": "URL of the marketing image, if any" }, "thumbUrl": { "type": "string", "description": "URL of the marketing thumbnail, if any" }, "blogUrl": { "type": "string", "description": "URL of the blog post or internet page presenting the project, if any" }, "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subdomain": { "type": "string" }, "isPublic": { "type": "boolean" } }, "required": [ "id", "name", "subdomain", "isPublic" ], "description": "Parent template, if any" }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Category unique id" }, "name": { "type": "string", "description": "Category name" }, "color": { "type": "string", "description": "Category color" }, "code": { "type": "string", "description": "Category code (used in URLs)" }, "summary": { "type": "string", "description": "Category short summary, if any" } }, "required": [ "id", "name", "color", "code", "summary" ], "description": "Project category, if any" }, "settings": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Project settings" }, "integrations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether the integration is available on the project" } }, "required": [ "available" ] }, "description": "Integration availabilities, if any" } }, "required": [ "id", "name", "subdomain", "isPublic", "isTemplate", "isBlocked", "isLocked", "timezone", "locale", "url", "imgBaseUrl", "logoUrl", "revision", "createdAt", "updatedAt", "title", "summary", "description", "imageUrl", "thumbUrl", "blogUrl", "template", "category", "settings", "integrations" ] }, "examples": { "Get the details of the current project": { "description": "Get the details of the current project", "value": { "id": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "name": "Todolist OpenAPI", "subdomain": "openapi", "isPublic": false, "isTemplate": false, "isBlocked": false, "isLocked": true, "logoUrl": null, "timezone": "Europe/Brussels", "locale": "en-be", "imageUrl": null, "thumbUrl": null, "blogUrl": null, "revision": 3, "title": null, "summary": null, "description": "", "createdAt": "2025-03-21T16:30:11+00:00", "updatedAt": "2025-03-21T16:30:22+00:00", "template": { "id": "168d1896-f509-4cfa-8a12-9e86152e122b", "subdomain": "blank", "name": "Blank", "isPublic": true }, "category": null, "settings": { "max_upload_size": 10 }, "integrations": null, "url": "http://openapi.klaro.devel/", "imgBaseUrl": "http://openapi.klaro.devel/" } } } } } } } }, "post": { "summary": "Create project", "description": "Allows creating a fresh new project and/or instantiate a template. The resulting project\ncan be found at the location returned in output data.", "tags": [ "Projects" ], "security": [ { "OAuth2": [ "User" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project name" }, "subdomain": { "type": "string", "description": "Subdomain where the project will he bosted on the instance" }, "dryRun": { "type": "boolean", "description": "Set it to true to check the subdomain availability" }, "template": { "type": "string", "description": "Optional template, use either its UUID or subdomain" } }, "required": [ "name", "subdomain", "dryRun" ], "additionalProperties": {} }, "examples": { "Instantiate a template as a fresh new project": { "description": "Instantiate a template as a fresh new project", "value": { "name": "Hello klaro", "subdomain": "hello-klaro", "template": "todolist", "dryRun": false } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "location": { "type": "string" } }, "required": [ "location" ] }, { "type": "object", "properties": { "location": { "type": "string" }, "userExists": { "type": "boolean" } }, "required": [ "location", "userExists" ] } ] }, "examples": { "Instantiate a template as a fresh new project": { "description": "Instantiate a template as a fresh new project", "value": { "location": "http://hello-klaro.klaro.devel/" } } } } } } } }, "patch": { "summary": "Update project", "description": "Allows modifying the current project", "tags": [ "Projects" ], "security": [ { "OAuth2": [ "Admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project's human friendly name" }, "subdomain": { "type": "string", "description": "Subdomain of the instance where the project is hosted" }, "timezone": { "type": "string", "description": "Project's timezone" }, "locale": { "type": "string", "description": "Project's locale, e.g. en-US or fr-BE" }, "logoUrl": { "type": "string", "description": "URL for the project logo" }, "description": { "type": "string", "description": "Project marketing description, if any" }, "imageUrl": { "type": "string", "description": "URL of the marketing image, if any" }, "thumbUrl": { "type": "string", "description": "URL of the marketing thumbnail, if any" }, "blogUrl": { "type": "string", "description": "URL of the blog post or internet page presenting the project, if any" }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Category unique id" } }, "required": [ "id" ], "additionalProperties": {}, "description": "Project category, if any" } } }, "examples": { "Update the description and locale of the current project": { "description": "Update the description and locale of the current project", "value": { "description": "My Personal Todolist", "locale": "fr-be" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Project's unique ID" }, "name": { "type": "string", "description": "Project's human friendly name" }, "subdomain": { "type": "string", "description": "Subdomain of the instance where the project is hosted" }, "isPublic": { "type": "boolean", "description": "Whether this project is public" }, "isTemplate": { "type": "boolean", "description": "Whether this project is a template" }, "isBlocked": { "type": "boolean", "description": "Whether this project has been blocked by administrators" }, "isLocked": { "type": "boolean", "description": "(deprecated)" }, "timezone": { "type": "string", "description": "Project's timezone" }, "locale": { "type": "string", "description": "Project's locale, e.g. en-US or fr-BE" }, "url": { "type": "string", "description": "URL where users can reach the project" }, "imgBaseUrl": { "type": "string", "description": "Base URL for card images" }, "logoUrl": { "type": "string", "description": "URL for the project logo" }, "revision": { "type": "integer", "description": "Revision number of the project (increased when settings change)" }, "createdAt": { "type": "string", "description": "When was the project created" }, "updatedAt": { "type": "string", "description": "When was the project last updated" }, "title": { "type": "string", "description": "Project marketing title, if any" }, "summary": { "type": "string", "description": "Project marketing summary, if any" }, "description": { "type": "string", "description": "Project marketing description, if any" }, "imageUrl": { "type": "string", "description": "URL of the marketing image, if any" }, "thumbUrl": { "type": "string", "description": "URL of the marketing thumbnail, if any" }, "blogUrl": { "type": "string", "description": "URL of the blog post or internet page presenting the project, if any" }, "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subdomain": { "type": "string" }, "isPublic": { "type": "boolean" } }, "required": [ "id", "name", "subdomain", "isPublic" ], "description": "Parent template, if any" }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Category unique id" }, "name": { "type": "string", "description": "Category name" }, "color": { "type": "string", "description": "Category color" }, "code": { "type": "string", "description": "Category code (used in URLs)" }, "summary": { "type": "string", "description": "Category short summary, if any" } }, "required": [ "id", "name", "color", "code", "summary" ], "description": "Project category, if any" }, "settings": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Project settings" }, "integrations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether the integration is available on the project" } }, "required": [ "available" ] }, "description": "Integration availabilities, if any" } }, "required": [ "id", "name", "subdomain", "isPublic", "isTemplate", "isBlocked", "isLocked", "timezone", "locale", "url", "imgBaseUrl", "logoUrl", "revision", "createdAt", "updatedAt", "title", "summary", "description", "imageUrl", "thumbUrl", "blogUrl", "template", "category", "settings", "integrations" ] }, "examples": { "Update the description and locale of the current project": { "description": "Update the description and locale of the current project", "value": { "id": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "name": "Todolist OpenAPI", "subdomain": "openapi", "isPublic": false, "isTemplate": false, "isBlocked": false, "isLocked": true, "logoUrl": null, "timezone": "Europe/Brussels", "locale": "fr-be", "imageUrl": null, "thumbUrl": null, "blogUrl": null, "revision": 4, "title": null, "summary": null, "description": "My Personal Todolist", "createdAt": "2025-03-21T16:30:11+00:00", "updatedAt": "2025-09-01T12:27:57+00:00", "template": { "id": "168d1896-f509-4cfa-8a12-9e86152e122b", "subdomain": "blank", "name": "Blank", "isPublic": true }, "category": null, "settings": { "max_upload_size": 10 }, "integrations": null, "url": "http://openapi.klaro.devel/", "imgBaseUrl": "http://openapi.klaro.devel/" } } } } } } } } }, "/stories/{id}": { "summary": "Story", "get": { "summary": "Get story", "description": "Returns full details of a story, including attachments and linked cards.", "tags": [ "Stories (aka Cards)" ], "parameters": [ { "in": "path", "name": "id", "description": "The UUID and autoincrement identifier are supported", "schema": { "anyOf": [ { "type": "string" }, { "type": "integer" } ], "description": "The UUID and autoincrement identifier are supported" }, "required": true, "example": "8ed76538-ee9a-4b39-9407-6b392a7ddc35" } ], "security": [ { "OAuth2": [ "Anonymous" ] }, {} ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" }, "linked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" } }, "required": [ "id", "identifier", "title" ], "additionalProperties": { "type": "object" } }, "description": "Linked stories" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachement unique ID" }, "filename": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "URL of the attachement, relative to the project's imgBaseUrl" }, "description": { "type": "string", "description": "Attachment description, if any" }, "sizeInBytes": { "type": "integer", "description": "Attachment size in bytes" }, "isCover": { "type": "boolean", "description": "Whether the attachment is used as story cover" }, "createdAt": { "type": "string", "description": "When was the attachent created" }, "createdBy": { "type": "string", "description": "Who created the attachent" } }, "required": [ "id", "filename", "url", "description", "sizeInBytes", "isCover", "createdAt", "createdBy" ] }, "description": "Story attachments" } }, "required": [ "id", "identifier", "title", "specification", "createdBy", "createdAt", "updatedAt", "linked", "attachments" ], "additionalProperties": { "type": "object" } }, "examples": { "Get a story using it's uuid": { "description": "Get a story using it's uuid", "value": { "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35", "identifier": 2, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "Document the RESTful API", "createdAt": "2025-03-21T16:32:17+00:00", "createdBy": "Bernard", "updatedAt": "2025-03-24T13:23:07+00:00", "specification": "", "kind": "todo", "progress": "ongoing", "assignee": "Bernard", "due_date": null, "attachments": [], "linked": [] } } } } } } } }, "patch": { "summary": "Update story", "description": "Updates a story using a patch representation", "tags": [ "Stories (aka Cards)" ], "parameters": [ { "in": "path", "name": "id", "description": "ID or identifier of the story", "schema": { "type": "string", "description": "ID or identifier of the story" }, "required": true, "example": "8ed76538-ee9a-4b39-9407-6b392a7ddc35" } ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board": { "type": "string", "description": "Board id or location in which the update takes place" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" } }, "additionalProperties": { "type": "object" } }, "examples": { "Apply a patch to modify a few story fields": { "description": "Apply a patch to modify a few story fields", "value": { "title": "A new title for the todo", "assignee": "Marc" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" }, "linked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" } }, "required": [ "id", "identifier", "title" ], "additionalProperties": { "type": "object" } }, "description": "Linked stories" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachement unique ID" }, "filename": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "URL of the attachement, relative to the project's imgBaseUrl" }, "description": { "type": "string", "description": "Attachment description, if any" }, "sizeInBytes": { "type": "integer", "description": "Attachment size in bytes" }, "isCover": { "type": "boolean", "description": "Whether the attachment is used as story cover" }, "createdAt": { "type": "string", "description": "When was the attachent created" }, "createdBy": { "type": "string", "description": "Who created the attachent" } }, "required": [ "id", "filename", "url", "description", "sizeInBytes", "isCover", "createdAt", "createdBy" ] }, "description": "Story attachments" } }, "required": [ "id", "identifier", "title", "specification", "createdBy", "createdAt", "updatedAt", "linked", "attachments" ], "additionalProperties": { "type": "object" } }, "examples": { "Apply a patch to modify a few story fields": { "description": "Apply a patch to modify a few story fields", "value": { "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35", "identifier": 2, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "A new title for the todo", "createdAt": "2025-03-21T16:32:17+00:00", "createdBy": "Bernard", "updatedAt": "2025-09-01T12:27:58+00:00", "specification": "", "kind": "todo", "progress": "ongoing", "assignee": "Marc", "due_date": null, "attachments": [], "linked": [] } } } } } } } }, "delete": { "summary": "Delete story", "description": "Allows deleting a story. The story attachments are removed as well, but\nnot the linked cards.", "tags": [ "Stories (aka Cards)" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true, "example": "8ed76538-ee9a-4b39-9407-6b392a7ddc35" } ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "onExisting": { "type": "string" }, "replaceBy": { "type": "integer" } } }, "examples": { "Delete a story by UUID": { "description": "Delete a story by UUID", "value": {} } } } } }, "responses": { "204": { "description": "" } } } }, "/stories": { "summary": "Story", "post": { "summary": "Create story", "description": "Allows creating a new project story (aka card).", "tags": [ "Stories (aka Cards)" ], "security": [ { "OAuth2": [ "Member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID or identifier of the story" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "URL of the attachement, relative to the project's imgBaseUrl" }, "isCover": { "type": "boolean", "description": "Whether the attachment is used as story cover" }, "description": { "type": "string", "description": "Whether the attachment is used as story cover" }, "sizeInBytes": { "type": "integer", "description": "Attachment size in bytes" } }, "required": [ "filename", "url", "isCover", "description", "sizeInBytes" ] }, "description": "List of story attachments to create" } }, "required": [ "title" ], "additionalProperties": { "type": "object" } }, "examples": { "Create a new story": { "description": "Create a new story", "value": { "kind": "todo", "progress": "ongoing", "assignee": "Bernard", "title": "Document the API" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "specification": { "type": "string", "description": "Story specification, also known as description" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" }, "linked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique story ID" }, "identifier": { "type": "integer", "description": "Unique story identifier (autonumber)" }, "title": { "type": "string", "description": "Story title" }, "createdBy": { "type": "string", "description": "Who created the story" }, "createdAt": { "type": "string", "description": "When was the story created" }, "updatedAt": { "type": "string", "description": "When was the story last updated" } }, "required": [ "id", "identifier", "title" ], "additionalProperties": { "type": "object" } }, "description": "Linked stories" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachement unique ID" }, "filename": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "URL of the attachement, relative to the project's imgBaseUrl" }, "description": { "type": "string", "description": "Attachment description, if any" }, "sizeInBytes": { "type": "integer", "description": "Attachment size in bytes" }, "isCover": { "type": "boolean", "description": "Whether the attachment is used as story cover" }, "createdAt": { "type": "string", "description": "When was the attachent created" }, "createdBy": { "type": "string", "description": "Who created the attachent" } }, "required": [ "id", "filename", "url", "description", "sizeInBytes", "isCover", "createdAt", "createdBy" ] }, "description": "Story attachments" } }, "required": [ "id", "identifier", "title", "specification", "createdBy", "createdAt", "updatedAt", "linked", "attachments" ], "additionalProperties": { "type": "object" } }, "examples": { "Create a new story": { "description": "Create a new story", "value": { "id": "1045fd54-98d1-4000-9f93-88d5afc4f468", "identifier": 5, "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb", "title": "Document the API", "createdAt": "2025-09-01T12:27:58+00:00", "createdBy": "Bernard", "updatedAt": "2025-09-01T12:27:58+00:00", "specification": "", "kind": "todo", "progress": "ongoing", "assignee": "Bernard", "due_date": null, "attachments": [], "linked": [] } } } } } } } } } } }