BrambleHelp
ReferenceProjects API

Work packages

The tasks in a project, with relations between them and their history.

MethodPathSummary
GET/v1/app/project/projects/:id/versionsList a project's versions (Roadmap)
POST/v1/app/project/projects/:id/versionsCreate a version/roadmap milestone
PATCH/v1/app/project/projects/:id/versions/:versionIdUpdate a version/roadmap milestone
DELETE/v1/app/project/projects/:id/versions/:versionIdDelete a version/roadmap milestone
GET/v1/app/project/projects/:id/work-packagesList a project's work packages
POST/v1/app/project/projects/:id/work-packagesCreate a work package
GET/v1/app/project/projects/:id/work-packages/:wpIdGet a single work package
PATCH/v1/app/project/projects/:id/work-packages/:wpIdUpdate a work package
PATCH/v1/app/project/projects/:id/work-packages/:wpId/moveMove a work package between statuses/positions (Board drag-drop / reorder)
DELETE/v1/app/project/projects/:id/work-packages/:wpIdDelete a work package (soft delete)
GET/v1/app/project/projects/:id/relationsList every work-package relation edge in the project
GET/v1/app/project/projects/:id/work-packages/:wpId/relationsList a single work package's relations
POST/v1/app/project/projects/:id/work-packages/:wpId/relationsCreate a relation between two work packages
DELETE/v1/app/project/projects/:id/work-packages/:wpId/relations/:relIdDelete a work-package relation
GET/v1/app/project/projects/:id/work-packages/:wpId/commentsList a work package's comments
POST/v1/app/project/projects/:id/work-packages/:wpId/commentsAdd a comment to a work package
PATCH/v1/app/project/projects/:id/work-packages/:wpId/comments/:commentIdEdit a work-package comment
DELETE/v1/app/project/projects/:id/work-packages/:wpId/comments/:commentIdDelete a work-package comment (soft delete)

#List a project's versions (Roadmap)

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

List a project's versions (Roadmap). Requires at least viewer role on the project. Each version includes open_count/closed_count of its work packages.

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

Path parameters

NameTypeDescription
idrequiredinteger

Response 200

FieldTypeDescription
versionsarray of object
versions[].idinteger
versions[].project_idinteger
versions[].namestring
versions[].descriptionstring, or null
versions[].start_datestring (date), or null
versions[].due_datestring (date), or null
versions[].statusstring: "open" | "locked" | "closed"
versions[].positioninteger
versions[].created_atstring (date-time)
versions[].open_countnumber
versions[].closed_countnumber
Example response
JSON
{
  "versions": [
    {
      "id": 42,
      "project_id": 7,
      "name": "Example name",
      "description": "string",
      "start_date": "2026-11-12",
      "due_date": "2026-11-12",
      "status": "open",
      "position": 1,
      "created_at": "2026-11-12T09:30:00.000Z",
      "open_count": 12.5,
      "closed_count": 12.5
    }
  ]
}

Example request

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

#Create a version/roadmap milestone

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

Create a version/roadmap milestone. Requires at least admin role on the project.

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

Path parameters

NameTypeDescription
idrequiredinteger

Request body JSON

NameTypeDescription
namerequiredstring
descriptionstring
start_datestring (date)
due_datestring (date)
statusstring

Response 201

FieldTypeDescription
versionany
Example response
JSON
{
  "version": null
}

Errors

StatusMessage
400name is required
400Invalid status

Example request

Bash
curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/versions' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example name","description":"string","start_date":"2026-11-12","due_date":"2026-11-12","status":"active"}'

#Update a version/roadmap milestone

PATCH/v1/app/project/projects/:id/versions/:versionId

Update a version/roadmap milestone. Requires at least admin role on the project.

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

Path parameters

NameTypeDescription
idrequiredinteger
versionIdrequiredinteger

Request body JSON

NameTypeDescription
namestring
descriptionstring
start_datestring (date)
due_datestring (date)
statusstring
positioninteger

Response 200

FieldTypeDescription
versionany
Example response
JSON
{
  "version": null
}

Errors

StatusMessage
400Invalid status

Example request

Bash
curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/versions/1' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example name","description":"string","start_date":"2026-11-12","due_date":"2026-11-12","status":"active","position":1}'

#Delete a version/roadmap milestone

DELETE/v1/app/project/projects/:id/versions/:versionId

Delete a version/roadmap milestone. Requires at least admin role on the project. Work packages referencing this version are unset (version_id set to null), not deleted.

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

Path parameters

NameTypeDescription
idrequiredinteger
versionIdrequiredinteger

Response 200

FieldTypeDescription
okboolean
Example response
JSON
{
  "ok": true
}

Example request

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

#List a project's work packages

GET/v1/app/project/projects/:id/work-packages

List a project's work packages. Requires at least viewer role on the project. Shared by the Board, Work Packages table, and Gantt views. Supports filtering.

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

Path parameters

NameTypeDescription
idrequiredinteger

Query parameters

NameTypeDescription
status_idinteger
category_idinteger
type_idinteger
version_idinteger
priorityany
assigneeany
qstring

Response 200

FieldTypeDescription
work_packagesarray of object
work_packages[].idinteger
work_packages[].project_idinteger
work_packages[].type_idinteger
work_packages[].status_idinteger
work_packages[].parent_idinteger, or null
work_packages[].version_idinteger, or null
work_packages[].category_idinteger, or null
work_packages[].subjectstring
work_packages[].descriptionstring, or null
work_packages[].prioritystring: "low" | "medium" | "high" | "urgent"
work_packages[].start_datestring (date), or null
work_packages[].due_datestring (date), or null
work_packages[].percent_doneinteger
work_packages[].positioninteger
work_packages[].created_byinteger
work_packages[].created_atstring (date-time)
work_packages[].updated_atstring (date-time)
work_packages[].completed_atstring (date-time), or null
work_packages[].deleted_atstring (date-time), or null
Example response
JSON
{
  "work_packages": [
    {
      "id": 42,
      "project_id": 7,
      "type_id": 7,
      "status_id": 7,
      "parent_id": 7,
      "version_id": 7,
      "category_id": 7,
      "subject": "Example subject",
      "description": "string",
      "priority": "low",
      "start_date": "2026-11-12",
      "due_date": "2026-11-12",
      "percent_done": 1,
      "position": 1,
      "created_by": 1,
      "created_at": "2026-11-12T09:30:00.000Z",
      "updated_at": "2026-11-12T09:30:00.000Z",
      "completed_at": "2026-11-12T09:30:00.000Z",
      "deleted_at": "2026-11-12T09:30:00.000Z"
    }
  ]
}

Example request

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

#Create a work package

POST/v1/app/project/projects/:id/work-packages

Create a work package. Requires at least member role on the project. Falls back to the project's first non-milestone type and default status if not specified.

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

Path parameters

NameTypeDescription
idrequiredinteger

Request body JSON

NameTypeDescription
subjectrequiredstring
descriptionstring
type_idinteger
status_idinteger
parent_idinteger
version_idinteger
category_idinteger
priorityany
start_datestring (date)
due_datestring (date)
percent_donenumber
assignee_idsarray of any
tag_idsarray of any

Response 201

FieldTypeDescription
work_packageobject
work_package.tag_idsarray of integer
work_package.assignee_idsarray of integer
Example response
JSON
{
  "work_package": {
    "…rows[0]": "…",
    "tag_ids": [
      7
    ],
    "assignee_ids": [
      7
    ]
  }
}

Errors

StatusMessage
400subject is required
400Invalid priority
400percent_done must be between 0 and 100
400Project has no types or statuses configured
400Invalid parent work package

Example request

Bash
curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/work-packages' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Example subject","description":"string","type_id":7,"status_id":7,"parent_id":7,"version_id":7,"category_id":7,"priority":"…","start_date":"2026-11-12","due_date":"2026-11-12","percent_done":12.5,"assignee_ids":[],"tag_ids":[]}'

#Get a single work package

GET/v1/app/project/projects/:id/work-packages/:wpId

Get a single work package. Requires at least viewer role on the project.

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger

Response 200

FieldTypeDescription
work_packageobject
work_package.assignee_idsarray of integer
work_package.tag_idsarray of integer
Example response
JSON
{
  "work_package": {
    "…rows[0]": "…",
    "assignee_ids": [
      7
    ],
    "tag_ids": [
      7
    ]
  }
}

Errors

StatusMessage
404Work package not found

Example request

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

#Update a work package

PATCH/v1/app/project/projects/:id/work-packages/:wpId

Update a work package. Requires at least member role on the project. Reassigning triggers "assigned" notifications for newly-added assignees; changing status_id notifies current assignees of the status change. Rejects a parent_id change that would create a circular hierarchy.

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger

Request body JSON

NameTypeDescription
subjectany
descriptionstring
type_idinteger
status_idinteger
category_idinteger
version_idinteger
priorityany
start_datestring (date)
due_datestring (date)
percent_donenumber
assignee_idsarray of any
tag_idsarray of any
completedany
parent_idinteger

Response 200

FieldTypeDescription
work_packageany
Example response
JSON
{
  "work_package": null
}

Errors

StatusMessage
400Invalid priority
400percent_done must be between 0 and 100
400Invalid parent work package
400That would create a circular hierarchy

Example request

Bash
curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/work-packages/1' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"…","description":"string","type_id":7,"status_id":7,"category_id":7,"version_id":7,"priority":"…","start_date":"2026-11-12","due_date":"2026-11-12","percent_done":12.5,"assignee_ids":[],"tag_ids":[],"completed":"…","parent_id":7}'

#Move a work package between statuses/positions (Board drag-drop / reorder)

PATCH/v1/app/project/projects/:id/work-packages/:wpId/move

Move a work package between statuses/positions (Board drag-drop / reorder). Requires at least member role on the project. Notifies current assignees of the status change.

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger

Request body JSON

NameTypeDescription
status_idrequiredinteger
positionrequiredinteger
orderarray of any

Response 200

FieldTypeDescription
okboolean
Example response
JSON
{
  "ok": true
}

Errors

StatusMessage
400status_id and position are required

Example request

Bash
curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/work-packages/1/move' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status_id":7,"position":1,"order":[]}'

#Delete a work package (soft delete)

DELETE/v1/app/project/projects/:id/work-packages/:wpId

Delete a work package (soft delete). Requires at least member role on the project. Children are reparented to top-level first.

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger

Response 200

FieldTypeDescription
okboolean
Example response
JSON
{
  "ok": true
}

Example request

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

#List every work-package relation edge in the project

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

List every work-package relation edge in the project. Requires at least viewer role on the project. Used by the Gantt view to draw dependency arrows without an N+1 fetch per work package.

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

Path parameters

NameTypeDescription
idrequiredinteger

Response 200

FieldTypeDescription
relationsarray of object
relations[].work_package_idinteger
relations[].related_work_package_idinteger
relations[].relation_typestring: "relates" | "blocks" | "blocked_by" | "precedes" | "follows" | "duplicates" | "duplicated_by"
Example response
JSON
{
  "relations": [
    {
      "work_package_id": 7,
      "related_work_package_id": 7,
      "relation_type": "relates"
    }
  ]
}

Example request

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

#List a single work package's relations

GET/v1/app/project/projects/:id/work-packages/:wpId/relations

List a single work package's relations. Requires at least viewer role on the project.

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger

Response 200

FieldTypeDescription
relationsarray of object
relations[].idinteger
relations[].project_idinteger
relations[].work_package_idinteger
relations[].related_work_package_idinteger
relations[].relation_typestring: "relates" | "blocks" | "blocked_by" | "precedes" | "follows" | "duplicates" | "duplicated_by"
relations[].created_byinteger
relations[].created_atstring (date-time)
relations[].related_subjectstring
relations[].related_status_idinteger
relations[].related_type_idinteger
Example response
JSON
{
  "relations": [
    {
      "id": 42,
      "project_id": 7,
      "work_package_id": 7,
      "related_work_package_id": 7,
      "relation_type": "relates",
      "created_by": 1,
      "created_at": "2026-11-12T09:30:00.000Z",
      "related_subject": "Example related subject",
      "related_status_id": 7,
      "related_type_id": 7
    }
  ]
}

Example request

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

#Create a relation between two work packages

POST/v1/app/project/projects/:id/work-packages/:wpId/relations

Create a relation between two work packages. Requires at least member role on the project. Also creates the inverse relation on the related work package (e.g. blocks/blocked_by).

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredstring

Request body JSON

NameTypeDescription
related_idrequiredstring
relation_typestring

Response 201

FieldTypeDescription
okboolean
Example response
JSON
{
  "ok": true
}

Errors

StatusMessage
400related_id is required and must differ from the work package
400Invalid relation_type
404Related work package not found
409That relation already exists

Example request

Bash
curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/work-packages/string/relations' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"related_id":"string","relation_type":"string"}'

#Delete a work-package relation

DELETE/v1/app/project/projects/:id/work-packages/:wpId/relations/:relId

Delete a work-package relation. Requires at least member role on the project. Also deletes the corresponding inverse relation.

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger
relIdrequiredinteger

Response 200

FieldTypeDescription
okboolean
Example response
JSON
{
  "ok": true
}

Errors

StatusMessage
404Relation not found

Example request

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

#List a work package's comments

GET/v1/app/project/projects/:id/work-packages/:wpId/comments

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

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger

Response 200

FieldTypeDescription
commentsarray of any
Example response
JSON
{
  "comments": []
}

Example request

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

#Add a comment to a work package

POST/v1/app/project/projects/:id/work-packages/:wpId/comments

Add a comment to a work package. Requires at least member role on the project. Notifies assignees/creator ("comment") and any valid @mentioned project members ("mention", which takes priority).

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger

Request body JSON

NameTypeDescription
bodyrequiredstring
mentioned_user_idsarray of any

Response 201

FieldTypeDescription
commentobject
comment.userany
Example response
JSON
{
  "comment": {
    "…rows[0]": "…",
    "user": null
  }
}

Errors

StatusMessage
400body is required
404Work package not found

Example request

Bash
curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/work-packages/1/comments' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"<p>…</p>","mentioned_user_ids":[]}'

#Edit a work-package comment

PATCH/v1/app/project/projects/:id/work-packages/:wpId/comments/:commentId

Edit a work-package comment. Requires at least viewer role on the project to reach the check, but only the comment's author may actually edit it.

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger
commentIdrequiredinteger

Request body JSON

NameTypeDescription
bodyrequiredstring

Response 200

FieldTypeDescription
commentany
Example response
JSON
{
  "comment": null
}

Errors

StatusMessage
400body is required
404Comment not found
403You can only edit your own comments

Example request

Bash
curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/app/project/projects/42/work-packages/1/comments/1' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"<p>…</p>"}'

#Delete a work-package comment (soft delete)

DELETE/v1/app/project/projects/:id/work-packages/:wpId/comments/:commentId

Delete a work-package comment (soft delete). Requires at least viewer role on the project to reach the check; the comment's author or an admin+ may delete it.

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

Path parameters

NameTypeDescription
idrequiredinteger
wpIdrequiredinteger
commentIdrequiredinteger

Response 200

FieldTypeDescription
okboolean
Example response
JSON
{
  "ok": true
}

Errors

StatusMessage
404Comment not found
403Insufficient permissions

Example request

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