ReferenceProjects API

Categories & tags

Categories and tags for grouping work.

Method	Path	Summary
GET	`/v1/app/project/projects/:id/categories`	List a project's work-package categories
POST	`/v1/app/project/projects/:id/categories`	Create a work-package category
PATCH	`/v1/app/project/projects/:id/categories/:catId`	Update a work-package category
DELETE	`/v1/app/project/projects/:id/categories/:catId`	Delete a work-package category
GET	`/v1/app/project/projects/:id/tags`	List a project's tags
POST	`/v1/app/project/projects/:id/tags`	Create a work-package tag
PATCH	`/v1/app/project/projects/:id/tags/:tagId`	Rename or recolor a tag
DELETE	`/v1/app/project/projects/:id/tags/:tagId`	Delete a tag. Requires at least member role on the project

#List a project's work-package categories

GET/v1/app/project/projects/:id/categories

List a project's work-package categories. Requires at least viewer role on the project.

Address: https://<your-org>.brambleit.cloud/api/v1/app/project/projects/:id/categories
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Projects.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`categories`	array of object
`categories[].id`	integer
`categories[].project_id`	integer
`categories[].name`	string
`categories[].color`	string
`categories[].created_at`	string (date-time)

Example response

JSON

{
  "categories": [
    {
      "id": 42,
      "project_id": 7,
      "name": "Example name",
      "color": "#2563eb",
      "created_at": "2026-11-12T09:30:00.000Z"
    }
  ]
}

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories' -Headers $headers

#Create a work-package category

POST/v1/app/project/projects/:id/categories

Create a work-package category. Requires at least member role on the project.

Address: https://<your-org>.brambleit.cloud/api/v1/app/project/projects/:id/categories
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Projects.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`name`required	string
`color`required	any

Response 201

Field	Type	Description
`category`	any

Example response

JSON

{
  "category": null
}

Errors

Status	Message
400	name is required
400	color must be a #rrggbb hex value

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example name","color":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"Example name","color":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"name":"Example name","color":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"name":"Example name","color":"…"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories' -Headers $headers -ContentType 'application/json' -Body $body

#Update a work-package category

PATCH/v1/app/project/projects/:id/categories/:catId

Update a work-package category. Requires at least member role on the project.

Address: https://<your-org>.brambleit.cloud/api/v1/app/project/projects/:id/categories/:catId
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Projects.

Path parameters

Name	Type	Description
`id`required	integer
`catId`required	integer

Request body JSON

Name	Type	Description
`name`	string
`color`required	any

Response 200

Field	Type	Description
`category`	any

Example response

JSON

{
  "category": null
}

Errors

Status	Message
400	color must be a #rrggbb hex value

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories/1' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example name","color":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories/1', {
  method: 'PATCH',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"Example name","color":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories/1",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"name":"Example name","color":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"name":"Example name","color":"…"}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories/1' -Headers $headers -ContentType 'application/json' -Body $body

#Delete a work-package category

DELETE/v1/app/project/projects/:id/categories/:catId

Delete a work-package category. Requires at least member role on the project.

Address: https://<your-org>.brambleit.cloud/api/v1/app/project/projects/:id/categories/:catId
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Projects.

Path parameters

Name	Type	Description
`id`required	integer
`catId`required	integer

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Example request

Bash

curl -X DELETE 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories/1' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories/1', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.delete(
    "https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories/1",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method DELETE -Uri 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/categories/1' -Headers $headers

#List a project's tags

GET/v1/app/project/projects/:id/tags

List a project's tags. Requires at least viewer role on the project.

Address: https://<your-org>.brambleit.cloud/api/v1/app/project/projects/:id/tags
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Projects.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`tags`	array of object
`tags[].id`	integer
`tags[].project_id`	integer
`tags[].name`	string
`tags[].color`	string
`tags[].created_at`	string (date-time)

Example response

JSON

{
  "tags": [
    {
      "id": 42,
      "project_id": 7,
      "name": "Example name",
      "color": "#2563eb",
      "created_at": "2026-11-12T09:30:00.000Z"
    }
  ]
}

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags' -Headers $headers

#Create a work-package tag

POST/v1/app/project/projects/:id/tags

Create a work-package tag. Requires at least member role on the project.

Address: https://<your-org>.brambleit.cloud/api/v1/app/project/projects/:id/tags
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Projects.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`name`required	string
`color`required	any

Response 201

Field	Type	Description
`tag`	any

Example response

JSON

{
  "tag": null
}

Errors

Status	Message
400	name is required
400	color must be a #rrggbb hex value

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example name","color":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"Example name","color":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"name":"Example name","color":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"name":"Example name","color":"…"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags' -Headers $headers -ContentType 'application/json' -Body $body

#Rename or recolor a tag

PATCH/v1/app/project/projects/:id/tags/:tagId

Rename or recolor a tag. Requires at least member role on the project.

Address: https://<your-org>.brambleit.cloud/api/v1/app/project/projects/:id/tags/:tagId
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Projects.

Path parameters

Name	Type	Description
`id`required	integer
`tagId`required	integer

Request body JSON

Name	Type	Description
`name`	string
`color`required	any

Response 200

Field	Type	Description
`tag`	any

Example response

JSON

{
  "tag": null
}

Errors

Status	Message
400	color must be a #rrggbb hex value

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags/1' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example name","color":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags/1', {
  method: 'PATCH',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"Example name","color":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags/1",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"name":"Example name","color":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"name":"Example name","color":"…"}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags/1' -Headers $headers -ContentType 'application/json' -Body $body

#Delete a tag. Requires at least member role on the project

DELETE/v1/app/project/projects/:id/tags/:tagId

Delete a tag. Requires at least member role on the project. Also removes it from every work package it's attached to (no FK cascade — see the migration file's comment on why).

Address: https://<your-org>.brambleit.cloud/api/v1/app/project/projects/:id/tags/:tagId
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Projects.

Path parameters

Name	Type	Description
`id`required	integer
`tagId`required	integer

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Example request

Bash

curl -X DELETE 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags/1' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags/1', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.delete(
    "https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags/1",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method DELETE -Uri 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/tags/1' -Headers $headers

Was this page helpful?