# Milestones

Milestone management operations

## Create a new milestone

> Creates a new milestone within a project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"MilestoneCreate":{"type":"object","required":["title","projectId"],"properties":{"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Project to create milestone in"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Start date (ISO 8601 format)"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Due date (ISO 8601 format)"},"status":{"type":"string","enum":["pending","in_progress","completed"],"default":"pending"}}},"Milestone":{"type":"object","required":["id","title","projectId","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique milestone identifier"},"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Associated project ID"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone due date"},"status":{"type":"string","enum":["pending","in_progress","completed"],"description":"Milestone status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/milestones":{"post":{"tags":["Milestones"],"summary":"Create a new milestone","description":"Creates a new milestone within a project","operationId":"createMilestone","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneCreate"}}}},"responses":{"200":{"description":"Milestone created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Milestone"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```

## Get a milestone

> Returns a specific milestone with its tasks

```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"MilestoneWithTasks":{"allOf":[{"$ref":"#/components/schemas/Milestone"},{"type":"object","properties":{"tasks":{"type":"array","description":"Tasks associated with this milestone","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"}}}}}}]},"Milestone":{"type":"object","required":["id","title","projectId","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique milestone identifier"},"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Associated project ID"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone due date"},"status":{"type":"string","enum":["pending","in_progress","completed"],"description":"Milestone status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/milestones/{id}":{"get":{"tags":["Milestones"],"summary":"Get a milestone","description":"Returns a specific milestone with its tasks","operationId":"getMilestone","parameters":[{"name":"id","in":"path","required":true,"description":"Milestone ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Milestone details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneWithTasks"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Milestone not found"},"500":{"description":"Server error"}}}}}}
```

## Update a milestone

> Updates an existing milestone

```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"MilestoneUpdate":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"dueDate":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["pending","in_progress","completed"]}}},"Milestone":{"type":"object","required":["id","title","projectId","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique milestone identifier"},"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Associated project ID"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone due date"},"status":{"type":"string","enum":["pending","in_progress","completed"],"description":"Milestone status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/milestones/{id}":{"put":{"tags":["Milestones"],"summary":"Update a milestone","description":"Updates an existing milestone","operationId":"updateMilestone","parameters":[{"name":"id","in":"path","required":true,"description":"Milestone ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneUpdate"}}}},"responses":{"200":{"description":"Milestone updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Milestone"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Milestone not found"},"500":{"description":"Server error"}}}}}}
```

## Delete a milestone

> Deletes a milestone. Tasks associated with the milestone will be unlinked.

```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/milestones/{id}":{"delete":{"tags":["Milestones"],"summary":"Delete a milestone","description":"Deletes a milestone. Tasks associated with the milestone will be unlinked.","operationId":"deleteMilestone","parameters":[{"name":"id","in":"path","required":true,"description":"Milestone ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Milestone deleted successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Milestone not found"},"500":{"description":"Server error"}}}}}}
```

## List milestones for a project

> Returns all milestones associated with a specific project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"MilestoneWithTasks":{"allOf":[{"$ref":"#/components/schemas/Milestone"},{"type":"object","properties":{"tasks":{"type":"array","description":"Tasks associated with this milestone","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"}}}}}}]},"Milestone":{"type":"object","required":["id","title","projectId","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique milestone identifier"},"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Associated project ID"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone due date"},"status":{"type":"string","enum":["pending","in_progress","completed"],"description":"Milestone status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/projects/{projectId}/milestones":{"get":{"tags":["Milestones"],"summary":"List milestones for a project","description":"Returns all milestones associated with a specific project","operationId":"listProjectMilestones","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of project milestones","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MilestoneWithTasks"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}}}}
```