{"openapi":"3.0.0","info":{"title":"FlowOS Documents Management API","version":"1.0.0","description":"API for managing documents, folders, versions, tags, and sharing in FlowOS"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Document":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the document"},"organizationId":{"type":"string","format":"uuid","description":"UUID of the organization that owns this document"},"folderId":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the parent folder"},"title":{"type":"string","description":"Title of the document"},"description":{"type":"string","nullable":true,"description":"Description of the document"},"mimeType":{"type":"string","description":"MIME type of the document"},"fileSize":{"type":"integer","format":"int64","description":"Size of the document in bytes"},"s3Key":{"type":"string","description":"S3 key for the document storage"},"s3Bucket":{"type":"string","description":"S3 bucket name"},"isArchived":{"type":"boolean","description":"Whether the document is archived"},"isDeleted":{"type":"boolean","description":"Whether the document is deleted"},"retentionPolicy":{"type":"string","enum":["none","legal_hold","compliance"],"description":"Retention policy for the document"},"classification":{"type":"string","enum":["public","internal","confidential","restricted"],"description":"Security classification of the document"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the document was created"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the document was last updated"},"createdBy":{"type":"string","format":"uuid","description":"UUID of the user who created the document"},"updatedBy":{"type":"string","format":"uuid","description":"UUID of the user who last updated the document"}},"required":["id","organizationId","title","mimeType","fileSize"]},"Folder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the folder"},"organizationId":{"type":"string","format":"uuid","description":"UUID of the organization that owns this folder"},"parentId":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the parent folder"},"name":{"type":"string","description":"Name of the folder"},"description":{"type":"string","nullable":true,"description":"Description of the folder"},"isDeleted":{"type":"boolean","description":"Whether the folder is deleted"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the folder was created"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the folder was last updated"},"createdBy":{"type":"string","format":"uuid","description":"UUID of the user who created the folder"},"updatedBy":{"type":"string","format":"uuid","description":"UUID of the user who last updated the folder"}},"required":["id","organizationId","name"]},"DocumentVersion":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the document version"},"documentId":{"type":"string","format":"uuid","description":"UUID of the parent document"},"versionNumber":{"type":"integer","description":"Version number"},"fileSize":{"type":"integer","format":"int64","description":"Size of this version in bytes"},"s3Key":{"type":"string","description":"S3 key for this version"},"checksum":{"type":"string","description":"Checksum of the file"},"isCurrent":{"type":"boolean","description":"Whether this is the current version"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when this version was created"},"createdBy":{"type":"string","format":"uuid","description":"UUID of the user who created this version"}},"required":["id","documentId","versionNumber","fileSize","isCurrent"]},"Tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the tag"},"organizationId":{"type":"string","format":"uuid","description":"UUID of the organization that owns this tag"},"name":{"type":"string","description":"Name of the tag"},"color":{"type":"string","description":"Color code for the tag"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the tag was created"},"createdBy":{"type":"string","format":"uuid","description":"UUID of the user who created the tag"}},"required":["id","organizationId","name"]},"Share":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the share"},"organizationId":{"type":"string","format":"uuid","description":"UUID of the organization that owns this share"},"documentId":{"type":"string","format":"uuid","description":"UUID of the shared document"},"sharedBy":{"type":"string","format":"uuid","description":"UUID of the user who created the share"},"sharedWithEmail":{"type":"string","format":"email","nullable":true,"description":"Email address the document was shared with"},"sharedWithUserId":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the user the document was shared with"},"permissions":{"type":"array","items":{"type":"string","enum":["read","write","delete"]},"description":"Permissions granted to the share recipient"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Expiration timestamp for the share"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the share was created"}},"required":["id","organizationId","documentId","sharedBy","permissions"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}},"paths":{"/documents":{"get":{"summary":"List documents","description":"Get a paginated list of documents in the organization","tags":["Documents"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"folderId","schema":{"type":"string","format":"uuid"},"description":"Filter by folder UUID"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search term for document title or description"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Number of items per page"},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of items to skip"},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["title","createdAt","updatedAt","fileSize"],"default":"createdAt"},"description":"Field to sort by"},{"in":"query","name":"sortOrder","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort order"}],"responses":{"200":{"description":"List of documents","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create document","description":"Create a new document with initial upload","tags":["Documents"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Title of the document"},"description":{"type":"string","description":"Description of the document"},"folderId":{"type":"string","format":"uuid","description":"UUID of the parent folder"},"mimeType":{"type":"string","description":"MIME type of the document"},"fileName":{"type":"string","description":"Original filename"},"sensitivity":{"type":"string","enum":["public","internal","confidential","restricted"],"description":"Security classification"},"metadata":{"type":"object","description":"Additional metadata"}},"required":["title"]}}}},"responses":{"201":{"description":"Document created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"$ref":"#/components/schemas/Document"},"uploadUrl":{"type":"string","description":"Presigned URL for file upload"}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{uuid}":{"get":{"summary":"Get document by UUID","description":"Get detailed information about a specific document","tags":["Documents"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"uuid","required":true,"schema":{"type":"string","format":"uuid"},"description":"Document UUID"}],"responses":{"200":{"description":"Document details with versions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"tags":[],"servers":[{"url":"https://flowos.scrumdesk.com/api/flowos-documents-management","description":"Production (third parties — use in Postman)"},{"url":"http://localhost:3013/api/flowos-documents-management","description":"Local module backend (direct on module port)"}]}