# Projects

Project management operations

## List all projects

> Returns a list of projects accessible to the authenticated user.\
> \- Admins and consultants see all projects within their organization\
> \- Regular users see only projects they own<br>

```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project 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":{"ProjectWithTags":{"allOf":[{"$ref":"#/components/schemas/Project"},{"type":"object","properties":{"owner_username":{"type":"string","description":"Username of the project owner"},"tags":{"type":"array","description":"Tags associated with the project","items":{"type":"object","properties":{"tagId":{"type":"integer"},"tag":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"isGlobal":{"type":"boolean"},"categoryId":{"type":"integer","nullable":true}}}}}}}}]},"Project":{"type":"object","required":["id","title","description","status","ownerId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique project identifier"},"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Current project status"},"ownerId":{"type":"integer","description":"User ID of the project owner"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID the project was created from"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID associated with the project"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date"},"metadata":{"type":"object","nullable":true,"description":"Additional project metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/projects":{"get":{"tags":["Projects"],"summary":"List all projects","description":"Returns a list of projects accessible to the authenticated user.\n- Admins and consultants see all projects within their organization\n- Regular users see only projects they own\n","operationId":"listProjects","responses":{"200":{"description":"List of projects","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectWithTags"}}}}},"401":{"description":"Not authenticated","content":{"text/plain":{"schema":{"type":"string"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a new project

> Creates a new project within the authenticated user's organization

```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project 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":{"ProjectCreate":{"type":"object","required":["title","description","status"],"properties":{"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Initial project status"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID to base the project on"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID to associate"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date (ISO 8601 format)"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date (ISO 8601 format)"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata"}}},"Project":{"type":"object","required":["id","title","description","status","ownerId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique project identifier"},"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Current project status"},"ownerId":{"type":"integer","description":"User ID of the project owner"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID the project was created from"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID associated with the project"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date"},"metadata":{"type":"object","nullable":true,"description":"Additional project metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/projects":{"post":{"tags":["Projects"],"summary":"Create a new project","description":"Creates a new project within the authenticated user's organization","operationId":"createProject","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreate"}}}},"responses":{"200":{"description":"Project created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Validation error","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```

## Delete a project

> Deletes a project. Only project owners or users with delete\_projects permission can delete.\
> Projects with related items (tasks, documents, activities) cannot be deleted until those items are removed.<br>

```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project 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":{"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/projects/{id}":{"delete":{"tags":["Projects"],"summary":"Delete a project","description":"Deletes a project. Only project owners or users with delete_projects permission can delete.\nProjects with related items (tasks, documents, activities) cannot be deleted until those items are removed.\n","operationId":"deleteProject","parameters":[{"name":"id","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Project deleted successfully"},"400":{"description":"Cannot delete project with related items","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Server error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```

## Update a project

> Updates an existing project. Only project owners or users with edit\_projects permission can update.

```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project 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":{"ProjectUpdate":{"type":"object","properties":{"title":{"type":"string","description":"Updated project title"},"description":{"type":"string","description":"Updated project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Updated project status"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Updated start date (ISO 8601 format or empty string to clear)"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Updated due date (ISO 8601 format or empty string to clear)"},"templateId":{"type":"string","nullable":true},"playbookId":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}}},"Project":{"type":"object","required":["id","title","description","status","ownerId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique project identifier"},"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Current project status"},"ownerId":{"type":"integer","description":"User ID of the project owner"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID the project was created from"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID associated with the project"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date"},"metadata":{"type":"object","nullable":true,"description":"Additional project metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/projects/{id}":{"patch":{"tags":["Projects"],"summary":"Update a project","description":"Updates an existing project. Only project owners or users with edit_projects permission can update.","operationId":"updateProject","parameters":[{"name":"id","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUpdate"}}}},"responses":{"200":{"description":"Project updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid date format or validation error","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Server error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```

## Duplicate a project

> Creates a copy of an existing project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project 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":{"Project":{"type":"object","required":["id","title","description","status","ownerId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique project identifier"},"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Current project status"},"ownerId":{"type":"integer","description":"User ID of the project owner"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID the project was created from"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID associated with the project"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date"},"metadata":{"type":"object","nullable":true,"description":"Additional project metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/projects/{id}/duplicate":{"post":{"tags":["Projects"],"summary":"Duplicate a project","description":"Creates a copy of an existing project","operationId":"duplicateProject","parameters":[{"name":"id","in":"path","required":true,"description":"Project ID to duplicate","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"New title for the duplicated project"}}}}}},"responses":{"200":{"description":"Project duplicated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}}}}
```