Project Mutations

Every endpoint on this page requires projects:write.

POST /v1/projects

Creates a project.

Request body

Field	Type	Required
projectName	string	yes
projectKey	string	yes
summary	string	yes
description	string	yes
teamId	string	yes
leadUserAccountId	string	no
priority	integer	yes
projectStatusId	string	no
targetDate	datetime	no
iconCss	string	yes
color	string	yes

Example

curl -X POST "$API_BASE_URL/v1/projects" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "Public API Docs",
    "projectKey": "DOCS",
    "summary": "Ship the first complete public API reference.",
    "description": "Documentation work for the public API rollout.",
    "teamId": "team_platform",
    "leadUserAccountId": "usr_01EXAMPLE",
    "priority": 2,
    "projectStatusId": "proj-status_in-progress",
    "targetDate": "2025-03-15T00:00:00Z",
    "iconCss": "fa-regular fa-book-open",
    "color": "#0f766e"
  }'

Response 201 Created:

{
  "id": "proj_docs",
  "workspaceId": "ws_01EXAMPLE",
  "name": "Public API Docs",
  "slug": "public-api-docs",
  "key": "DOCS",
  "summary": "Ship the first complete public API reference.",
  "description": "Documentation work for the public API rollout.",
  "iconCss": "fa-regular fa-book-open",
  "color": "#0f766e",
  "state": "active",
  "statusId": "proj-status_in-progress",
  "priority": 2,
  "teamId": "team_platform",
  "leadUserAccountId": "usr_01EXAMPLE",
  "memberUserAccountIds": [],
  "labelIds": [],
  "startUtc": null,
  "targetUtc": "2025-03-15T00:00:00Z",
  "progressPercent": 0,
  "linkCount": 0
}

PATCH /v1/projects/{projectKey}

Updates a project.

Request body

All fields are optional, but at least one writable field must be provided.

Field	Type	Notes
name	string	Update project name
summary	string	Update summary
description	string	Plain text description
state	string	planned, active, paused, completed, or archived
projectStatusId	string	Update status ID
priority	integer	Update priority
teamId	string	Reassign team
leadUserAccountId	string	Set lead
clearLead	boolean	Clear lead
memberUserAccountIds	string array	Replace members
labelIds	string array	Replace labels
iconCss	string	Update icon
color	string	Update color
startDate	datetime	Set start date
clearStartDate	boolean	Clear start date
targetDate	datetime	Set target date
clearTargetDate	boolean	Clear target date

Validation rules

• leadUserAccountId and clearLead cannot be combined
• startDate and clearStartDate cannot be combined
• targetDate and clearTargetDate cannot be combined

Example

curl -X PATCH "$API_BASE_URL/v1/projects/DOCS" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Ship complete public API docs with deployment guidance.",
    "priority": 1,
    "memberUserAccountIds": [
      "usr_01EXAMPLE",
      "usr_01SAM"
    ],
    "labelIds": [
      "label_docs"
    ],
    "targetDate": "2025-03-20T00:00:00Z"
  }'

Response 200 OK:

{
  "id": "proj_docs",
  "workspaceId": "ws_01EXAMPLE",
  "name": "Public API Docs",
  "slug": "public-api-docs",
  "key": "DOCS",
  "summary": "Ship complete public API docs with deployment guidance.",
  "description": "Documentation work for the public API rollout.",
  "iconCss": "fa-regular fa-book-open",
  "color": "#0f766e",
  "state": "active",
  "statusId": "proj-status_in-progress",
  "priority": 1,
  "teamId": "team_platform",
  "leadUserAccountId": "usr_01EXAMPLE",
  "memberUserAccountIds": [
    "usr_01EXAMPLE",
    "usr_01SAM"
  ],
  "labelIds": [
    "label_docs"
  ],
  "startUtc": "2025-02-01T00:00:00Z",
  "targetUtc": "2025-03-20T00:00:00Z",
  "progressPercent": 55,
  "linkCount": 2
}

DELETE /v1/projects/{projectKey}

Deletes a project.

curl -X DELETE "$API_BASE_URL/v1/projects/DOCS" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 204 No Content.

POST /v1/projects/{projectKey}/links

Creates a project link.

Request body

Field	Type	Required
url	string	yes
title	string	yes

Example

curl -X POST "$API_BASE_URL/v1/projects/DOCS/links" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/tracking",
    "title": "Tracking issue"
  }'

Response 201 Created:

{
  "linkId": "plink_tracking",
  "url": "https://example.com/tracking",
  "title": "Tracking issue",
  "createdUtc": "2025-02-24T15:04:05Z",
  "createdByUserAccountId": "usr_01EXAMPLE"
}

If an equivalent link already exists, the API returns the existing link with 200 OK.

DELETE /v1/projects/{projectKey}/links/{linkId}

Deletes a project link.

curl -X DELETE "$API_BASE_URL/v1/projects/DOCS/links/plink_tracking" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 204 No Content.

Error notes

• Unknown project keys return 404 not_found
• Duplicate project keys return 409 conflict
• Invalid payloads return 400 validation_failed