Projects API

Manage projects and their associated milestones and tasks.

List Projects

GET /projects

Query Parameters:

  • page (number, optional): Page number (default: 1)
  • limit (number, optional): Items per page (default: 20)
  • search (string, optional): Search term for project name
  • status (string, optional): Filter by status (active, completed, archived)

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Website Redesign",
      "description": "Complete redesign of company website",
      "status": "active",
      "customer_id": "550e8400-e29b-41d4-a716-446655440001",
      "start_date": "2024-01-15",
      "end_date": "2024-03-15",
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-10T10:00:00Z"
    }
  ],
  "count": 1,
  "page": 1,
  "limit": 20
}

Get Project

GET /projects/{id}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Website Redesign",
  "description": "Complete redesign of company website",
  "status": "active",
  "customer_id": "550e8400-e29b-41d4-a716-446655440001",
  "start_date": "2024-01-15",
  "end_date": "2024-03-15",
  "created_at": "2024-01-10T10:00:00Z",
  "updated_at": "2024-01-10T10:00:00Z"
}

Create Project

POST /projects

Request body:

{
  "name": "Website Redesign",
  "description": "Complete redesign of company website",
  "customer_id": "550e8400-e29b-41d4-a716-446655440001",
  "start_date": "2024-01-15",
  "end_date": "2024-03-15"
}

Update Project

PUT /projects/{id}

Request body: Same as create project

Delete Project

DELETE /projects/{id}

Milestones API

Manage milestones within projects.

List Milestones

GET /projects/{projectId}/milestones

Query Parameters:

  • page (number, optional): Page number (default: 1)
  • limit (number, optional): Items per page (default: 20)
  • status (string, optional): Filter by status (planned, in_progress, completed, cancelled)

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Design Phase",
      "description": "Create mockups and design concepts",
      "status": "completed",
      "due_date": "2024-02-01",
      "order": 1,
      "task_count": 5,
      "completed_task_count": 5,
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-25T15:30:00Z"
    }
  ],
  "count": 1,
  "page": 1,
  "limit": 20
}

Get Milestone

GET /projects/{projectId}/milestones/{id}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Design Phase",
  "description": "Create mockups and design concepts",
  "status": "completed",
  "due_date": "2024-02-01",
  "order": 1,
  "task_count": 5,
  "completed_task_count": 5,
  "created_at": "2024-01-10T10:00:00Z",
  "updated_at": "2024-01-25T15:30:00Z"
}

Create Milestone

POST /projects/{projectId}/milestones

Request body:

{
  "name": "Development Phase",
  "description": "Implement the approved design",
  "status": "planned",
  "due_date": "2024-02-15",
  "order": 2
}

Update Milestone

PUT /projects/{projectId}/milestones/{id}

Request body: Same as create milestone

Delete Milestone

DELETE /projects/{projectId}/milestones/{id}

Reorder Milestones

PATCH /projects/{projectId}/milestones/reorder

Request body:

{
  "milestones": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "order": 1
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "order": 2
    }
  ]
}

Status Values

Project Status

  • active: Currently active project
  • completed: Project finished successfully
  • archived: Project archived but preserved

Milestone Status

  • planned: Milestone is planned but not started
  • in_progress: Milestone is currently being worked on
  • completed: Milestone is finished
  • cancelled: Milestone was cancelled

Error Responses

All endpoints may return these errors:

  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation errors

Example error response:

{
  "error": {
    "message": "Validation failed",
    "details": {
      "name": "Name is required",
      "due_date": "Due date must be in the future"
    }
  }
}