# Documents

Document management operations

## List all documents

> Returns all documents accessible to the authenticated user within their organization

```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document 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":{"DocumentWithRelations":{"allOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"uploader":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}},"projects":{"type":"array","description":"Projects this document is linked to","items":{"type":"object","properties":{"documentId":{"type":"integer"},"projectId":{"type":"integer"},"project":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}}}}]},"Document":{"type":"object","required":["id","name","type","url","uploaderId","createdAt"],"properties":{"id":{"type":"integer","description":"Unique document identifier"},"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to access the document"},"uploaderId":{"type":"integer","description":"User ID who uploaded the document"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"createdAt":{"type":"string","format":"date-time","description":"Upload timestamp"}}}}},"paths":{"/documents":{"get":{"tags":["Documents"],"summary":"List all documents","description":"Returns all documents accessible to the authenticated user within their organization","operationId":"listDocuments","responses":{"200":{"description":"List of documents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```

## Create a new document

> Creates a new document record

```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document 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":{"DocumentCreate":{"type":"object","required":["name","type","url"],"properties":{"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to the document"},"organizationId":{"type":"integer","nullable":true,"description":"Organization to associate with"},"projectId":{"type":"integer","nullable":true,"description":"Project to link document to"}}},"Document":{"type":"object","required":["id","name","type","url","uploaderId","createdAt"],"properties":{"id":{"type":"integer","description":"Unique document identifier"},"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to access the document"},"uploaderId":{"type":"integer","description":"User ID who uploaded the document"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"createdAt":{"type":"string","format":"date-time","description":"Upload timestamp"}}}}},"paths":{"/documents":{"post":{"tags":["Documents"],"summary":"Create a new document","description":"Creates a new document record","operationId":"createDocument","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCreate"}}}},"responses":{"200":{"description":"Document created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```

## Update a document

> Updates an existing document's metadata

```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document 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":{"DocumentUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"url":{"type":"string"}}},"Document":{"type":"object","required":["id","name","type","url","uploaderId","createdAt"],"properties":{"id":{"type":"integer","description":"Unique document identifier"},"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to access the document"},"uploaderId":{"type":"integer","description":"User ID who uploaded the document"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"createdAt":{"type":"string","format":"date-time","description":"Upload timestamp"}}}}},"paths":{"/documents/{id}":{"patch":{"tags":["Documents"],"summary":"Update a document","description":"Updates an existing document's metadata","operationId":"updateDocument","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdate"}}}},"responses":{"200":{"description":"Document updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Document not found"},"500":{"description":"Server error"}}}}}}
```

## List documents for a project

> Returns all documents associated with a specific project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document 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":{"DocumentWithRelations":{"allOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"uploader":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}},"projects":{"type":"array","description":"Projects this document is linked to","items":{"type":"object","properties":{"documentId":{"type":"integer"},"projectId":{"type":"integer"},"project":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}}}}]},"Document":{"type":"object","required":["id","name","type","url","uploaderId","createdAt"],"properties":{"id":{"type":"integer","description":"Unique document identifier"},"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to access the document"},"uploaderId":{"type":"integer","description":"User ID who uploaded the document"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"createdAt":{"type":"string","format":"date-time","description":"Upload timestamp"}}}}},"paths":{"/documents/{projectId}":{"get":{"tags":["Documents"],"summary":"List documents for a project","description":"Returns all documents associated with a specific project","operationId":"listProjectDocuments","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of project documents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```

## Link document to project

> Associates a document with a project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document 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":{"/documents/{documentId}/projects/{projectId}":{"post":{"tags":["Documents"],"summary":"Link document to project","description":"Associates a document with a project","operationId":"linkDocumentToProject","parameters":[{"name":"documentId","in":"path","required":true,"description":"Document ID","schema":{"type":"integer"}},{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Document linked to project successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Document or project not found"},"500":{"description":"Server error"}}}}}}
```

## Unlink document from project

> Removes the association between a document and a project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document 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":{"/documents/{documentId}/projects/{projectId}":{"delete":{"tags":["Documents"],"summary":"Unlink document from project","description":"Removes the association between a document and a project","operationId":"unlinkDocumentFromProject","parameters":[{"name":"documentId","in":"path","required":true,"description":"Document ID","schema":{"type":"integer"}},{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Document unlinked from project successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Association not found"},"500":{"description":"Server error"}}}}}}
```

## Upload a file

> Uploads a file and returns the file URL

```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document 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":{"/upload":{"post":{"tags":["Documents"],"summary":"Upload a file","description":"Uploads a file and returns the file URL","operationId":"uploadFile","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file to upload"}}}}}},"responses":{"200":{"description":"File uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"URL of the uploaded file"}}}}}},"400":{"description":"No file uploaded"},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```