Update Department

PATCH /clients/{client_id}/departments/{department_id}

Updates a department's name or description. All fields are optional -- only include fields you want to change.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization
department_id	string (uuid)	Unique identifier for the department

Request Body

Field	Type	Description
name	string	New department name. Must be unique within the client.
description	string | null	New description. Send null to clear the description.

Fields not updatable via API

Field	Reason
id	Immutable identifier
member_count	Computed from membership, not directly settable
created_at	Immutable audit timestamp

Response

Returns the updated Department object with status 200 OK.

Example Requests

Update name only

curl -X PATCH "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments/d1a2b3c4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering & DevOps"
  }'

Update description only

curl -X PATCH "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments/d1a2b3c4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Software development, infrastructure, and DevOps teams"
  }'

Clear description

curl -X PATCH "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments/d1a2b3c4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": null
  }'

Example Response

{
  "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "name": "Engineering & DevOps",
  "description": "Software development, infrastructure, and DevOps teams",
  "member_count": 45,
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-02-24T22:00:00.000Z"
}

Partial update behaviour

Omitted fields are left unchanged. Only the fields you send are updated.

Scenario	Request body	Result
Rename only	{ "name": "New Name" }	Name changes, description unchanged
Update description	{ "description": "New desc" }	Description changes, name unchanged
Clear description	{ "description": null }	Description set to null, name unchanged

Error Responses

Status	Description
400	Invalid request body (e.g. empty string for name)
401	Authentication required
403	Insufficient permissions for this client
404	Department or client not found
409	A department with the new name already exists in this client
500	Server error

404 -- department not found

{
  "error": {
    "code": "not_found",
    "message": "Department not found",
    "details": {
      "department_id": "ffffffff-ffff-ffff-ffff-ffffffffffff"
    }
  }
}

409 -- name conflict

{
  "error": {
    "code": "conflict",
    "message": "A department with this name already exists",
    "details": {
      "name": "Engineering & DevOps"
    }
  }
}

Related Endpoints

• Get Department - View current department state
• List Departments - Browse all departments
• Create Department - Create a new department
• Delete Department - Remove a department