API reference

Columns

The set, the done mark and the order.

Every column belongs to a set, and the set is the pair (tenantId, projectId). Which one holds for a card is decided by columnScope in Settings; see Columns and scope.

GET/api/columns

Role: ViewerWorkspace

The columns of a workspace.

With ?project=, it returns only the set IN EFFECT for a card of that project, already resolved by the columnScope in Settings.

Query parameters

Field	Type	Description
`tenant`	`cuid`	Without it, the route returns the columns of every workspace the account reaches.When absent: todos os espaços da pessoa
`project`	`cuid`	Slices by that project's set. It only has an effect alongside `tenant`.

Request

# every column of the workspace: the tenant set and each project set
curl -s "http://localhost:3000/api/columns?tenant=cmsp4djx60002p801o7ybpkv7" \
  -H "Authorization: Bearer $TOKEN"

# only the set IN EFFECT for a card of that project
curl -s "http://localhost:3000/api/columns?tenant=cmsp4djx60002p801o7ybpkv7&project=cmttg1vjy000zlf015g097nhi" \
  -H "Authorization: Bearer $TOKEN"

Response200

[
  {
    "id": "cmttg1vdl000tlf01uuqhz8ad",
    "projectId": null,
    "name": "A fazer",
    "accent": "stone",
    "position": 0,
    "done": false
  }
]

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.

It serves whoever calls the API from outside: the interface reads columns from the /api/board payload, which is already scoped.

POST/api/columns

Role: MemberWorkspace

Creates a column at the end of the set.

Request body

Field	Type	Description
`tenantId`required	`cuid`
`projectId`	`cuid \| null`	Absent or null is the TENANT set, which also serves cards with no project.When absent: conjunto do tenant
`name`required	`string`
`color`	`acento`	Accent token only, no free hex.When absent: sugerido pelo servidor
`done`	`boolean`	Marking it here already unsets the mark on the others: there is exactly one done column per set.When absent: false

Request

curl -s -X POST http://localhost:3000/api/columns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "cmsp4djx60002p801o7ybpkv7",
    "name": "Revisão",
    "color": "lilac"
  }'

Response201

{
  "id": "cmttg39e8001nlf01fmyfx43e",
  "projectId": null,
  "name": "Revisão",
  "accent": "lilac",
  "position": 5,
  "done": false
}

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	Column management is turned off in Settings. No column is deleted by that: only editing is locked.
`403`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.
`422`	The body did not pass the schema. The `details` field carries zod's `fieldErrors` and `formErrors`, field by field.

PATCH/api/columns/[id]

Role: MemberWorkspace

Renames, recolours or transfers the done mark.

Path parameters

Field	Type	Description
`id`required	`cuid`

Request body

Field	Type	Description
`name`	`string`
`color`	`acento`
`done`	`boolean`

Request

curl -s -X PATCH http://localhost:3000/api/columns/cmttg39e8001nlf01fmyfx43e \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Em revisão", "color": "clay" }'

Response200

{
  "id": "cmttg39e8001nlf01fmyfx43e",
  "projectId": null,
  "name": "Em revisão",
  "accent": "clay",
  "position": 5,
  "done": false
}

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	Column management is turned off in Settings. No column is deleted by that: only editing is locked.
`404`	The resource does not exist, or has already been deleted.
`422`	The done mark is not unset: it is transferred. Mark another column of the set.

A column's set is IMMUTABLE: neither tenantId nor projectId appears here.

DELETE/api/columns/[id]

Role: MemberWorkspace

Deletes a column, deciding what happens to its cards.

Path parameters

Field	Type	Description
`id`required	`cuid`

Request body

Field	Type	Description
`cards`	`enum`	`MOVE` sends the cards to another column of the same set; `DELETE` deletes the cards.MOVE · DELETE
`targetColumnId`	`cuid`	Required when `cards` is `MOVE`.
`confirm`	`"APAGAR CARDS"`	Required when `cards` is `DELETE`.

Request

# sends the cards to another column of the same set
curl -s -X DELETE http://localhost:3000/api/columns/cmttg39e8001nlf01fmyfx43e \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": "MOVE",
    "targetColumnId": "cmttg1vdl000tlf01uuqhz8ad"
  }'

# deletes the cards too, hence the phrase
curl -s -X DELETE http://localhost:3000/api/columns/cmttg39e8001nlf01fmyfx43e \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cards": "DELETE", "confirm": "APAGAR CARDS" }'

Response200

{ "deleted": true, "cardsMoved": 0, "cardsDeleted": 0 }

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	Column management is turned off in Settings. No column is deleted by that: only editing is locked.
`404`	The resource does not exist, or has already been deleted.
`422`	Every set ends with at least one column, and one of them concludes. Mark another one first.
`422`	The body did not pass the schema. The `details` field carries zod's `fieldErrors` and `formErrors`, field by field.

The decision is REQUIRED: without the cards field, the route refuses.

PATCH/api/columns/order

Role: MemberWorkspace

Reorders columns of the same set.

It takes a SUBSET: the given ids take, in that order, the positions they already occupy together. That is what lets the arrows send only the pair that swapped.

Request body

Field	Type	Description
`columnIds`required	`cuid[]`

Request

# a SUBSET: the given ids take the positions they already occupy together
curl -s -X PATCH http://localhost:3000/api/columns/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "columnIds": [
      "cmttg1vdl000ulf01nhqhd23w",
      "cmttg1vdl000tlf01uuqhz8ad"
    ]
  }'

Response200

{ "updated": 2 }

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	Column management is turned off in Settings. No column is deleted by that: only editing is locked.
`404`	The resource does not exist, or has already been deleted.
`422`	The given ids do not all belong to the same set. The route takes a subset, but it has to come from one place.