Projects API

The Projects module provides project and task management — create projects, break them into tasks, assign team members, track milestones, and log timesheets. It integrates with Employees, Invoices (billable timesheets), and Helpdesk (ticket-to-task conversion).

---

Endpoints

Method	Path	Description
GET	/api/projects	List projects
POST	/api/projects	Create a project
GET	/api/projects/:id	Get a project
PATCH	/api/projects/:id	Update a project
DELETE	/api/projects/:id	Archive a project
GET	/api/projects/:id/tasks	List tasks for a project
POST	/api/projects/:id/tasks	Create a task
GET	/api/projects/:id/tasks/:taskId	Get a task
PATCH	/api/projects/:id/tasks/:taskId	Update a task
POST	/api/projects/:id/tasks/:taskId/timesheets	Log time on a task
GET	/api/projects/:id/timesheets	Project timesheet summary
GET	/api/projects/:id/milestones	List milestones
POST	/api/projects/:id/milestones	Create a milestone

---

Projects

List Projects

GET /api/projects?status=active&page=1&limit=20

Query Parameters

Parameter	Type	Description
status	active | on_hold | done | cancelled	Project status
contactId	string	Filter by customer contact
managerId	string	Filter by project manager
search	string	Search by project name

Response

{
  "data": [
    {
      "id": "018e4444-abcd-7000-8000-000000000001",
      "name": "Odoo Implementation — Acme Corp",
      "status": "active",
      "contact": { "id": "...", "name": "Acme Corp" },
      "manager": { "id": "...", "name": "Jane PM" },
      "startDate": "2026-03-01",
      "endDate": "2026-06-30",
      "progress": 38,
      "tasksTotal": 48,
      "tasksDone": 18,
      "hoursLogged": 142.5,
      "hoursBudget": 400
    }
  ],
  "meta": { "total": 12, "page": 1, "limit": 20, "totalPages": 1 }
}

Create a Project

POST /api/projects
Content-Type: application/json

{
  "name": "Power BI Dashboard — Globex",
  "contactId": "018e1234-abcd-7000-8000-000000000099",
  "managerId": "018ecccc-abcd-7000-8000-000000000001",
  "startDate": "2026-04-01",
  "endDate": "2026-05-31",
  "hoursBudget": 120,
  "billable": true
}

---

Tasks

List Tasks

GET /api/projects/018e4444-abcd-7000-8000-000000000001/tasks?status=in_progress&assigneeId=018e...

Task statuses: todo, in_progress, in_review, done, blocked

Response

{
  "data": [
    {
      "id": "018e4444-bbbb-7000-8000-000000000001",
      "title": "Configure product catalog sync",
      "status": "in_progress",
      "assignee": { "id": "...", "name": "Dev Alice" },
      "priority": "high",
      "dueDate": "2026-03-28T00:00:00Z",
      "hoursLogged": 8.5,
      "hoursEstimate": 12,
      "tags": ["backend", "integration"]
    }
  ],
  "meta": { "total": 30, "page": 1, "limit": 20, "totalPages": 2 }
}

Create a Task

POST /api/projects/018e4444-abcd-7000-8000-000000000001/tasks
Content-Type: application/json

{
  "title": "Set up Odoo database",
  "description": "Install PostgreSQL, configure parameters, restore demo data.",
  "assigneeId": "018ecccc-abcd-7000-8000-000000000001",
  "priority": "high",
  "dueDate": "2026-04-05T00:00:00Z",
  "hoursEstimate": 4,
  "tags": ["setup", "database"]
}

---

Timesheets

Log Time

POST /api/projects/018e4444-abcd-7000-8000-000000000001/tasks/018e4444-bbbb-7000-8000-000000000001/timesheets
Content-Type: application/json

{
  "employeeId": "018ecccc-abcd-7000-8000-000000000001",
  "date": "2026-03-20",
  "hours": 3.5,
  "description": "Implemented product sync endpoint"
}

Project Timesheet Summary

GET /api/projects/018e4444-abcd-7000-8000-000000000001/timesheets?from=2026-03-01&to=2026-03-31

{
  "totalHours": 142.5,
  "billableHours": 130,
  "budget": 400,
  "utilizationPercent": 35.6,
  "byEmployee": [
    { "employeeId": "...", "name": "Dev Alice", "hours": 65 },
    { "employeeId": "...", "name": "PM Jane", "hours": 77.5 }
  ]
}

---

Milestones

POST /api/projects/018e4444-abcd-7000-8000-000000000001/milestones
Content-Type: application/json

{
  "name": "Phase 1 — Setup Complete",
  "targetDate": "2026-04-15T00:00:00Z"
}

Mark as reached:

PATCH /api/projects/018e4444-abcd-7000-8000-000000000001/milestones/MILESTONE_ID
Content-Type: application/json

{ "reached": true, "reachedDate": "2026-04-14T00:00:00Z" }

---

Status Codes

Code	Scenario
200	Get or list succeeded
201	Project, task, timesheet, or milestone created
204	Project archived
400	Hours logged exceed daily limit (24 hours)
404	Project or task not found
422	Invalid date range or missing required field