API reference

Projects

The filter label inside a workspace.

A project isolates nothing: what isolates is the workspace. Deleting a project releases its cards and takes its epics along.

GET/api/projects

Role: ViewerWorkspace

The projects of a workspace.

Query parameters

Field	Type	Description
`tenant`	`cuid`	When absent: todos os espaços da pessoa

Request

curl -s "http://localhost:3000/api/projects?tenant=cmsp4djx60002p801o7ybpkv7" \
  -H "Authorization: Bearer $TOKEN"

Response200

[
  {
    "id": "cmttg1vjy000zlf015g097nhi",
    "name": "Integrações",
    "description": "Consumo da API por outros sistemas",
    "color": "sky",
    "position": 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`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.

POST/api/projects

Role: MemberWorkspace

Creates a project.

Request body

Field	Type	Description
`tenantId`required	`cuid`	Required: there is no project outside a workspace.
`name`required	`string`
`description`	`string \| null`
`color`	`acento ou #rrggbb`	Takes one of the 8 accents or a `#rrggbb`.When absent: sugerido pelo servidor

Request

curl -s -X POST http://localhost:3000/api/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "cmsp4djx60002p801o7ybpkv7",
    "name": "Integrações",
    "description": "Consumo da API por outros sistemas",
    "color": "sky"
  }'

Response201

{
  "id": "cmttg1vjy000zlf015g097nhi",
  "name": "Integrações",
  "description": "Consumo da API por outros sistemas",
  "color": "sky",
  "position": 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`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.
`409`	A record with that name already exists in the same workspace.
`422`	The body did not pass the schema. The `details` field carries zod's `fieldErrors` and `formErrors`, field by field.

PATCH/api/projects/[id]

Role: MemberWorkspace

Renames, recolours or describes a project.

Path parameters

Field	Type	Description
`id`required	`cuid`

Request body

Field	Type	Description
`name`	`string`
`description`	`string \| null`
`color`	`acento ou #rrggbb`

Request

curl -s -X PATCH http://localhost:3000/api/projects/cmttg1vjy000zlf015g097nhi \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Consumo da API por outros sistemas e integrações." }'

Response200

{
  "id": "cmttg1vjy000zlf015g097nhi",
  "name": "Integrações",
  "description": "Consumo da API por outros sistemas e integrações.",
  "color": "sky",
  "position": 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`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.
`404`	The resource does not exist, or has already been deleted.
`422`	The body came empty. An absent field means do not touch, so a `PATCH` with no field would have no effect at all.

No tenantId: the workspace is chosen at creation and never changes.

DELETE/api/projects/[id]

Role: MemberWorkspace

Deletes a project. Cards are RELEASED; epics go with it.

A card's projectId is nullable, so the cards go back to “no project”. An epic, by contrast, does not exist outside a project, which is why it goes along.

Path parameters

Field	Type	Description
`id`required	`cuid`

Request

curl -s -X DELETE http://localhost:3000/api/projects/cmttg1vjy000zlf015g097nhi \
  -H "Authorization: Bearer $TOKEN"

Response200

{ "deleted": true, "cardsReleased": 4 }

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.
`404`	The resource does not exist, or has already been deleted.