Projects
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/projects | List all projects |
| POST | /api/projects | Create a project |
| GET | /api/projects/:id | Get a single project |
| PUT | /api/projects/:id | Update a project |
| DELETE | /api/projects/:id | Soft-delete a project |
All endpoints require authentication.
List Projects
GET /api/projects
Return all projects, ordered alphabetically by name.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| includeDeleted | boolean | Include soft-deleted projects. Default: false |
Response: 200 OK
{
"data": [
{
"id": "proj-1",
"name": "Backend",
"color": "#3b82f6",
"description": "Server and API work",
"createdAt": "2025-01-05T08:00:00.000Z"
},
{
"id": "proj-2",
"name": "Frontend",
"color": "#10b981",
"description": null,
"createdAt": "2025-01-06T09:00:00.000Z"
}
]
}
Create Project
POST /api/projects
Create a new project.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Project name (trimmed) |
| color | string | Yes | Hex color code (e.g., #3b82f6) |
| description | string | No | Project description |
The color field must be a valid 6-digit hex color with a leading #. Examples: #3b82f6, #10b981, #ef4444.
Response: 200 OK
{
"data": {
"id": "proj-3",
"name": "Documentation",
"color": "#f59e0b",
"description": "Docs and guides",
"createdAt": "2025-01-07T10:00:00.000Z"
}
}
Get Project
GET /api/projects/:id
Return a single project by ID.
Response: 200 OK
{
"data": {
"id": "proj-1",
"name": "Backend",
"color": "#3b82f6",
"description": "Server and API work",
"createdAt": "2025-01-05T08:00:00.000Z"
}
}
Returns 404 if the project does not exist.
Update Project
PUT /api/projects/:id
Update one or more fields on a project. Only provided fields are changed.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | No | New name |
| color | string | No | New hex color |
| description | string | No | New description (set null to clear) |
Response: 200 OK
{
"data": {
"id": "proj-1",
"name": "Backend API",
"color": "#3b82f6",
"description": "Server and API work",
"modifiedAt": "2025-01-07T14:00:00.000Z"
}
}
Delete Project
DELETE /api/projects/:id
Soft-delete a project by setting deletedAt. The project is excluded from list results unless ?includeDeleted=true is passed.
Deleting a project does not delete or unlink associated tasks and documents. They retain their projectId reference but the project will not appear in filtered lists.
Response: 200 OK
{
"data": {
"id": "proj-1",
"name": "Backend",
"deletedAt": "2025-01-07T16:00:00.000Z"
}
}