API reference

Workspaces

The root of the hierarchy. An admin prefix.

A new workspace is born with the 5 default columns. Deleting takes everything inside along, which is why the route requires the phrase in the body.

GET/api/tenants

Role: Admin

The installation's workspaces, with the card and project counts.

Request

curl -s http://localhost:3000/api/tenants \
  -H "Authorization: Bearer $TOKEN"

Response200

[
  {
    "id": "cmsp4djx60002p801o7ybpkv7",
    "name": "Pessoal",
    "color": "amber",
    "position": 0,
    "cardCount": 12,
    "projectCount": 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`	The account is not an admin. This prefix requires `ADMIN` in every method, reading included.

POST/api/tenants

Role: Admin

Creates a workspace, already with the 5 default columns.

Request body

Field	Type	Description
`name`required	`string`
`color`	`acento ou #rrggbb`	When absent: sugerido pelo servidor

Request

curl -s -X POST http://localhost:3000/api/tenants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Rascunho Docs", "color": "lilac" }'

Response201

{
  "id": "cmttg1vbw000slf01380evq0t",
  "name": "Rascunho Docs",
  "color": "lilac",
  "position": 3,
  "cardCount": 0,
  "projectCount": 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 is not an admin. This prefix requires `ADMIN` in every method, reading included.
`403`	Workspace creation is turned off in Settings. The existing ones stay whole.
`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.

There is no seed: the default columns are born with each workspace, in the same transaction.

PATCH/api/tenants/[id]

Role: Admin

Renames or recolours a workspace.

Path parameters

Field	Type	Description
`id`required	`cuid`

Request body

Field	Type	Description
`name`	`string`
`color`	`acento ou #rrggbb`

Request

curl -s -X PATCH http://localhost:3000/api/tenants/cmsp4djx60002p801o7ybpkv7 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "color": "stone" }'

Response200

{
  "id": "cmsp4djx60002p801o7ybpkv7",
  "name": "Pessoal",
  "color": "stone",
  "position": 0,
  "cardCount": 12,
  "projectCount": 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`	The account is not an admin. This prefix requires `ADMIN` in every method, reading included.
`404`	The resource does not exist, or has already been deleted.
`409`	A record with that name already exists in the same workspace.
`422`	The body came empty. An absent field means do not touch, so a `PATCH` with no field would have no effect at all.

DELETE/api/tenants/[id]

Role: Admin

Deletes the workspace and EVERYTHING inside it.

Cards, projects, epics, labels, comments and the files on the volume. The phrase in the body is required: the interface's confirmation is a layer on top, never the only one.

Path parameters

Field	Type	Description
`id`required	`cuid`

Request body

Field	Type	Description
`confirm`required	`"APAGAR TENANT"`	Exactly `APAGAR TENANT`.

Request

curl -s -X DELETE http://localhost:3000/api/tenants/cmttg1vbw000slf01380evq0t \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "confirm": "APAGAR TENANT" }'

Response200

{
  "deleted": true,
  "name": "Rascunho Docs",
  "cards": 1,
  "projects": 1
}

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 is not an admin. This prefix requires `ADMIN` in every method, reading included.
`404`	The resource does not exist, or has already been deleted.
`422`	One workspace always remains: the last one is not deleted.
`422`	The confirmation phrase is missing, or came different. A destructive route requires the exact phrase in the body.

The last workspace is not deleted, and the check happens INSIDE the transaction, so two simultaneous requests do not both get through.

PATCH/api/tenants/order

Role: Admin

Reorders the workspaces: a subset, like epics.

Request body

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

Request

curl -s -X PATCH http://localhost:3000/api/tenants/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantIds": [
      "tenant-pessoal",
      "cmsp4djx60002p801o7ybpkv7"
    ]
  }'

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`	The account is not an admin. This prefix requires `ADMIN` in every method, reading included.
`404`	The resource does not exist, or has already been deleted.
`422`	The body did not pass the schema. The `details` field carries zod's `fieldErrors` and `formErrors`, field by field.