Update Project

This endpoint updates an existing project by ID. Only the fields you send are changed.

Endpoint

PUT /v1/projects/projects/:id

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

projects:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID to update.

Request Body

Send a JSON body. A request with no body returns 500. You cannot change clientId with this endpoint.

Field	Type	Required	Description
name	string	No	New project name. Also renames the default task.
description	string | null	No	New project description.
endCustomerId	string | null	No	New related end customer ID. Use null to clear the end customer. An unknown ID returns 500.
isArchived	boolean	No	New archive state.
completed	boolean	No	New completion state.
autoAssign	boolean	No	New auto-assign state. See Behavior for the effect on tasks.
billingCategory	"BILLABLE" | "NON_BILLABLE" | null	No	New billing category. Use null to clear it. The value is also applied to all of the project’s tasks. Any other string returns 500.
customFields	Record<string, string>	No	New custom fields. The object replaces the existing custom fields. It is not merged.

Example Request Body

{
  "description": "Updated project description",
  "completed": true,
  "autoAssign": false,
  "billingCategory": "NON_BILLABLE"
}

Example Request

cURL

curl -X PUT "https://api.crewsum.com/v1/projects/projects/project-mno123pqr4567890" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated project description",
    "completed": true,
    "autoAssign": false,
    "billingCategory": "NON_BILLABLE"
  }'

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/projects/projects/project-mno123pqr4567890",
  {
    method: "PUT",
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "Updated project description",
      completed: true,
      autoAssign: false,
      billingCategory: "NON_BILLABLE",
    }),
  },
);
const result = await response.json();

HTTP

PUT /v1/projects/projects/project-mno123pqr4567890 HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "description": "Updated project description",
  "completed": true,
  "autoAssign": false,
  "billingCategory": "NON_BILLABLE"
}

Response

On success, the API returns HTTP 200 OK.

Example Response

{
  "message": "Successfully updated project: project-mno123pqr4567890"
}

Behavior

• Billing category: sending billingCategory, including null, sets the same value on every task in the project. While a project has a billing category, its tasks cannot set their own.
• Auto-assign: setting autoAssign to true also turns on auto-assign for the default task. Changing autoAssign from true to false turns off auto-assign for every task in the project. Existing user assignments are not removed.
• Name: changing name also renames the default task and sets its description to Default task for: <name>.
• Archive: setting isArchived to true also archives the default task. Setting isArchived to false does not unarchive the default task unless you also send name in the same request.
• If no project exists for the ID, the API still returns 200 and changes nothing. No webhook is sent in that case.
• After the project is updated, Crewsum emits the projects.updated webhook event. A webhook delivery failure does not change the API response. Changes that cascade to tasks do not emit tasks.updated events.

Error Responses

Status	Meaning
400	The project ID was missing from the route.
500	Crewsum could not update the project. This includes an invalid billingCategory, an unknown endCustomerId, and a request with no JSON body.

Authentication and scope failures are described in Errors.

Related Webhooks

projects.updated View webhook event details.