{"openapi":"3.0.0","info":{"title":"OpenCap API Documentation","version":"1.0.0","description":"OpenCap Financial Management System","license":{"name":"ISC","url":"https://opensource.org/licenses/ISC"},"contact":{"name":"OpenCap Support","url":"https://github.com/Open-Cap-Stack/opencap","email":"support@opencap.com"}},"servers":[{"url":"/api","description":"Default API server"},{"url":"/api/v1","description":"Version 1 API server"}],"components":{"parameters":{"PageParam":{"name":"page","in":"query","description":"Page number for pagination","schema":{"type":"integer","minimum":1,"default":1}},"LimitParam":{"name":"limit","in":"query","description":"Number of items per page","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"SortParam":{"name":"sort","in":"query","description":"Sort field and direction (e.g., createdAt:desc)","schema":{"type":"string"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"stack":{"type":"string","description":"Error stack trace (development only)"},"details":{"type":"string","description":"Additional error details if available"}}},"User":{"type":"object","properties":{"_id":{"type":"string","description":"User ID"},"name":{"type":"string","description":"User's full name"},"email":{"type":"string","format":"email","description":"User's email address","example":"john.doe@example.com"},"role":{"type":"string","enum":["user","admin","super_admin"],"description":"User's role","example":"admin"},"emailVerified":{"type":"boolean","description":"Whether the user's email has been verified"},"createdAt":{"type":"string","format":"date-time","description":"User creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"User last update timestamp"},"userId":{"type":"string","example":"usr_12345"},"firstName":{"type":"string","example":"John"},"lastName":{"type":"string","example":"Doe"},"permissions":{"type":"array","items":{"type":"string","example":"read:users"}},"status":{"type":"string","enum":["active","pending","inactive","suspended"],"example":"active"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of records"},"page":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Number of records per page"},"pages":{"type":"integer","description":"Total number of pages"}}},"ShareClass":{"type":"object","properties":{"_id":{"type":"string","description":"Share class unique identifier"},"name":{"type":"string","description":"Share class name"},"companyId":{"type":"string","description":"Associated company ID"},"classification":{"type":"string","description":"Share class classification (e.g., Common, Preferred)"},"authorizedShares":{"type":"number","description":"Number of authorized shares"},"parValue":{"type":"number","description":"Par value per share"},"votingRights":{"type":"boolean","description":"Whether this share class has voting rights"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ShareClassInput":{"type":"object","required":["name","companyId","classification"],"properties":{"name":{"type":"string","description":"Share class name"},"companyId":{"type":"string","description":"Associated company ID"},"classification":{"type":"string","description":"Share class classification (e.g., Common, Preferred)"},"authorizedShares":{"type":"number","description":"Number of authorized shares"},"parValue":{"type":"number","description":"Par value per share"},"votingRights":{"type":"boolean","description":"Whether this share class has voting rights"}}},"FinancialReport":{"type":"object","properties":{"_id":{"type":"string","description":"Financial report unique identifier"},"title":{"type":"string","description":"Report title"},"reportType":{"type":"string","description":"Type of financial report"},"period":{"type":"string","description":"Reporting period"},"companyId":{"type":"string","description":"Associated company ID"},"authorId":{"type":"string","description":"ID of the user who created the report"},"data":{"type":"object","description":"Financial data contained in the report"},"status":{"type":"string","enum":["draft","submitted","approved","rejected"],"description":"Current status of the report"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"FinancialReportInput":{"type":"object","required":["title","reportType","period","companyId"],"properties":{"title":{"type":"string","description":"Report title"},"reportType":{"type":"string","description":"Type of financial report"},"period":{"type":"string","description":"Reporting period"},"companyId":{"type":"string","description":"Associated company ID"},"data":{"type":"object","description":"Financial data contained in the report"},"status":{"type":"string","enum":["draft","submitted","approved","rejected"],"description":"Current status of the report","default":"draft"}}},"FileUploadResponse":{"type":"object","properties":{"id":{"type":"string"},"fileName":{"type":"string"},"size":{"type":"integer"},"contentType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"FileMetadata":{"type":"object","properties":{"id":{"type":"string"},"fileName":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer"},"metadata":{"type":"object"},"createdAt":{"type":"string","format":"date-time"}}},"StorageUsage":{"type":"object","properties":{"totalBytes":{"type":"integer"},"fileCount":{"type":"integer"},"quotaUsedPercent":{"type":"number"}}},"SecurityIssuance":{"type":"object","required":["issuanceId","companyId","securityType","stakeholderId","numberOfShares","pricePerShare","issuanceDate"],"properties":{"issuanceId":{"type":"string","description":"Unique identifier for the issuance"},"companyId":{"type":"string","description":"Company ID"},"securityType":{"type":"string","enum":["common_stock","preferred_stock","convertible_note","safe","warrant","option","restricted_stock","rsu"]},"shareClassId":{"type":"string","description":"Share class ID"},"stakeholderId":{"type":"string","description":"Stakeholder receiving the securities"},"numberOfShares":{"type":"number","description":"Number of shares issued"},"pricePerShare":{"type":"number","description":"Price per share"},"issuanceDate":{"type":"string","format":"date","description":"Date of issuance"},"status":{"type":"string","enum":["pending","issued","cancelled","transferred","exercised","converted"]},"exemptionType":{"type":"string","enum":["rule_701","regulation_d_506b","regulation_d_506c","regulation_a","regulation_cf","section_4a2","intrastate","other"]},"complianceStatus":{"type":"string","enum":["compliant","pending_review","non_compliant","remediation_required"]}}},"StateFiling":{"type":"object","required":["stateCode"],"properties":{"stateCode":{"type":"string","description":"Two-letter state code (e.g., CA, NY)"},"filingStatus":{"type":"string","enum":["not_required","pending","filed","overdue","exempt"]},"filingDeadline":{"type":"string","format":"date"},"filingDate":{"type":"string","format":"date"},"exemptionClaimed":{"type":"string"}}},"Document":{"type":"object","properties":{"_id":{"type":"string","description":"Document unique identifier"},"name":{"type":"string","description":"Document name"},"type":{"type":"string","enum":["contract","report","legal","tax","other"],"description":"Document type"},"description":{"type":"string","description":"Document description"},"fileUrl":{"type":"string","format":"uri","description":"URL to access the document file"},"fileSize":{"type":"integer","description":"File size in bytes"},"fileType":{"type":"string","description":"MIME type of the file"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags categorizing the document"},"entityId":{"type":"string","description":"ID of the related entity"},"entityType":{"type":"string","enum":["company","spv","investor","employee","other"],"description":"Type of the related entity"},"uploadedBy":{"type":"string","description":"ID of the user who uploaded the document"},"hasEmbeddings":{"type":"boolean","description":"Whether vector embeddings have been generated"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ProfitabilityMetrics":{"type":"object","properties":{"companyId":{"type":"string","description":"Unique identifier of the company"},"period":{"type":"string","description":"Reporting period in format YYYY-QX or YYYY-full"},"grossProfitMargin":{"type":"number","format":"float","description":"Gross profit divided by revenue"},"operatingProfitMargin":{"type":"number","format":"float","description":"Operating profit divided by revenue"},"netProfitMargin":{"type":"number","format":"float","description":"Net profit divided by revenue"},"revenue":{"type":"number","description":"Revenue for the period"},"grossProfit":{"type":"number","description":"Gross profit for the period"},"operatingProfit":{"type":"number","description":"Operating profit for the period"},"netProfit":{"type":"number","description":"Net profit for the period"}}},"LiquidityMetrics":{"type":"object","properties":{"companyId":{"type":"string","description":"Unique identifier of the company"},"period":{"type":"string","description":"Reporting period in format YYYY-QX or YYYY-full"},"currentRatio":{"type":"number","format":"float","description":"Current assets divided by current liabilities"},"quickRatio":{"type":"number","format":"float","description":"(Current assets - inventory) divided by current liabilities"},"cashRatio":{"type":"number","format":"float","description":"Cash and cash equivalents divided by current liabilities"},"currentAssets":{"type":"number","description":"Current assets for the period"},"inventory":{"type":"number","description":"Inventory for the period"},"cashAndCashEquivalents":{"type":"number","description":"Cash and cash equivalents for the period"},"currentLiabilities":{"type":"number","description":"Current liabilities for the period"}}},"SolvencyMetrics":{"type":"object","properties":{"companyId":{"type":"string","description":"Unique identifier of the company"},"period":{"type":"string","description":"Reporting period in format YYYY-QX or YYYY-full"},"debtToEquityRatio":{"type":"number","format":"float","description":"Total liabilities divided by equity"},"debtToAssetRatio":{"type":"number","format":"float","description":"Total liabilities divided by total assets"},"longTermDebtToEquityRatio":{"type":"number","format":"float","description":"Long-term debt divided by equity"},"interestCoverageRatio":{"type":"number","format":"float","description":"Operating income divided by interest expense"},"totalLiabilities":{"type":"number","description":"Total liabilities for the period"},"longTermDebt":{"type":"number","description":"Long-term debt for the period"},"equity":{"type":"number","description":"Equity for the period"},"totalAssets":{"type":"number","description":"Total assets for the period"}}},"EfficiencyMetrics":{"type":"object","properties":{"companyId":{"type":"string","description":"Unique identifier of the company"},"period":{"type":"string","description":"Reporting period in format YYYY-QX or YYYY-full"},"assetTurnoverRatio":{"type":"number","format":"float","description":"Revenue divided by average total assets"},"inventoryTurnoverRatio":{"type":"number","format":"float","description":"Cost of goods sold divided by average inventory"},"receivablesTurnoverRatio":{"type":"number","format":"float","description":"Revenue divided by average accounts receivable"},"daysInventoryOutstanding":{"type":"number","format":"float","description":"365 divided by inventory turnover ratio"},"daysReceivablesOutstanding":{"type":"number","format":"float","description":"365 divided by receivables turnover ratio"}}},"GrowthMetrics":{"type":"object","properties":{"companyId":{"type":"string","description":"Unique identifier of the company"},"currentPeriod":{"type":"string","description":"Current reporting period"},"comparisonPeriod":{"type":"string","description":"Period being compared to"},"revenueGrowth":{"type":"number","format":"float","description":"Percentage growth in revenue"},"netIncomeGrowth":{"type":"number","format":"float","description":"Percentage growth in net income"},"ebitdaGrowth":{"type":"number","format":"float","description":"Percentage growth in EBITDA"},"totalAssetsGrowth":{"type":"number","format":"float","description":"Percentage growth in total assets"},"equityGrowth":{"type":"number","format":"float","description":"Percentage growth in equity"}}},"ValuationMetrics":{"type":"object","properties":{"companyId":{"type":"string","description":"Unique identifier of the company"},"period":{"type":"string","description":"Reporting period in format YYYY-QX or YYYY-full"},"earningsPerShare":{"type":"number","format":"float","description":"Net income divided by shares outstanding"},"priceToEarningsRatio":{"type":"number","format":"float","description":"Stock price divided by earnings per share"},"enterpriseValue":{"type":"number","description":"Market cap plus debt minus cash"},"evToEbitda":{"type":"number","format":"float","description":"Enterprise value divided by EBITDA"},"evToRevenue":{"type":"number","format":"float","description":"Enterprise value divided by revenue"},"priceToBookRatio":{"type":"number","format":"float","description":"Market cap divided by equity"},"bookValuePerShare":{"type":"number","format":"float","description":"Equity divided by shares outstanding"}}},"MetricsDashboard":{"type":"object","properties":{"companyId":{"type":"string","description":"Unique identifier of the company"},"period":{"type":"string","description":"Reporting period in format YYYY-QX or YYYY-full"},"generatedAt":{"type":"string","format":"date-time","description":"Timestamp when the dashboard was generated"},"profitability":{"$ref":"#/components/schemas/ProfitabilityMetrics"},"liquidity":{"$ref":"#/components/schemas/LiquidityMetrics"},"solvency":{"$ref":"#/components/schemas/SolvencyMetrics"},"efficiency":{"$ref":"#/components/schemas/EfficiencyMetrics"},"growth":{"$ref":"#/components/schemas/GrowthMetrics"},"valuation":{"$ref":"#/components/schemas/ValuationMetrics"}}},"Role":{"type":"object","properties":{"name":{"type":"string","example":"admin"},"description":{"type":"string","example":"Administrator with full system access"},"defaultPermissions":{"type":"array","items":{"type":"string","example":"admin:all"}}}},"Permission":{"type":"object","properties":{"name":{"type":"string","example":"read:users"},"description":{"type":"string","example":"Allows reading user data"},"resource":{"type":"string","example":"users"},"action":{"type":"string","example":"read"}}},"SPV":{"type":"object","properties":{"_id":{"type":"string","description":"SPV unique identifier"},"name":{"type":"string","description":"Name of the SPV"},"status":{"type":"string","enum":["Active","Pending","Closed"],"description":"Operational status of the SPV"},"complianceStatus":{"type":"string","enum":["Compliant","NonCompliant","PendingReview"],"description":"Regulatory compliance status"},"parentCompany":{"type":"string","description":"ID of the parent company managing this SPV"},"formation":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Formation date of the SPV"},"state":{"type":"string","description":"State where the SPV was formed"},"ein":{"type":"string","description":"Employer Identification Number"}}},"fundingGoal":{"type":"number","format":"float","description":"Target funding amount"},"currentFunding":{"type":"number","format":"float","description":"Current amount raised"},"investors":{"type":"array","items":{"type":"string"},"description":"IDs of investors in this SPV"},"assets":{"type":"array","items":{"type":"string"},"description":"IDs of assets owned by this SPV"},"documents":{"type":"array","items":{"type":"string"},"description":"IDs of documents related to this SPV"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"SPVInput":{"type":"object","required":["name","status","complianceStatus","parentCompany"],"properties":{"name":{"type":"string","description":"Name of the SPV"},"status":{"type":"string","enum":["Active","Pending","Closed"],"description":"Operational status of the SPV"},"complianceStatus":{"type":"string","enum":["Compliant","NonCompliant","PendingReview"],"description":"Regulatory compliance status"},"parentCompany":{"type":"string","description":"ID of the parent company managing this SPV"},"formation":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Formation date of the SPV"},"state":{"type":"string","description":"State where the SPV was formed"},"ein":{"type":"string","description":"Employer Identification Number"}}},"fundingGoal":{"type":"number","format":"float","description":"Target funding amount"},"currentFunding":{"type":"number","format":"float","description":"Current amount raised"},"investors":{"type":"array","items":{"type":"string"},"description":"IDs of investors in this SPV"},"assets":{"type":"array","items":{"type":"string"},"description":"IDs of assets owned by this SPV"},"documents":{"type":"array","items":{"type":"string"},"description":"IDs of documents related to this SPV"}}}},"responses":{"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Authentication is required to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"The request contains invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"An internal server error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnauthorizedError":{"description":"Authentication information is missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Authentication required"}}}}}},"ForbiddenError":{"description":"The server understood the request but refuses to authorize it","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Access denied: Insufficient permissions"}}}}}},"NotFoundError":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Resource not found"}}}}}},"BadRequestError":{"description":"The server could not understand the request due to invalid syntax","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Invalid request"}}}}}},"ServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Internal server error"}}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"security":[{"bearerAuth":[]}],"paths":{"/auth/login":{"post":{"tags":["Authentication"],"summary":"Login a user","operationId":"loginUser","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","format":"password"}},"required":["email","password"]}}},"required":true},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"userId":{"type":"string"},"name":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Authenticate a user with email and password"}},"/auth/register":{"post":{"tags":["Authentication"],"summary":"Register a new user","operationId":"registerUser","responses":{"201":{"description":"User created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"message":{"type":"string"},"token":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"description":"Email already in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Create a new user account with email and password","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","name"],"properties":{"email":{"type":"string","format":"email","description":"User's email address"},"password":{"type":"string","format":"password","description":"User's password"},"name":{"type":"string","description":"User's full name"}}}}}}}},"/api/spvs":{"get":{"tags":["SPV Management"],"summary":"Get all SPVs","operationId":"getAllSPVs","responses":{"200":{"description":"A list of SPVs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SPV","type":"object","properties":{"_id":{"type":"string","description":"SPV unique identifier"},"name":{"type":"string","description":"Name of the SPV"},"description":{"type":"string","description":"Description of the SPV"},"legalEntityType":{"type":"string","enum":["llc","lp","corporation","trust"],"description":"Legal entity type"},"managerId":{"type":"string","description":"ID of the managing user or company"},"adminIds":{"type":"array","description":"IDs of administrators","items":{"type":"string"}},"targetCompanyId":{"type":"string","description":"ID of the company this SPV invests in"},"status":{"type":"string","enum":["draft","active","closed","liquidated"],"description":"Current status of the SPV"},"investmentTarget":{"type":"number","description":"Target investment amount"},"investmentMinimum":{"type":"number","description":"Minimum investment amount"},"investmentMaximum":{"type":"number","description":"Maximum investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)"},"legalFormationDate":{"type":"string","format":"date","description":"Date of legal formation"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"description":"Returns a paginated list of all Special Purpose Vehicles","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":10},"description":"Maximum number of records to return","$ref":"#/components/parameters/PageParam"},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Page number for pagination","$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}]},"post":{"tags":["SPV Management"],"summary":"Create a new SPV","description":"Creates a new Special Purpose Vehicle","operationId":"createSPV","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SPVInput","type":"object","required":["name","legalEntityType","managerId"],"properties":{"name":{"type":"string","description":"Name of the SPV"},"description":{"type":"string","description":"Description of the SPV"},"legalEntityType":{"type":"string","enum":["llc","lp","corporation","trust"],"description":"Legal entity type"},"managerId":{"type":"string","description":"ID of the managing user or company"},"adminIds":{"type":"array","description":"IDs of administrators","items":{"type":"string"}},"targetCompanyId":{"type":"string","description":"ID of the company this SPV invests in"},"status":{"type":"string","enum":["draft","active","closed","liquidated"],"description":"Current status of the SPV","default":"draft"},"investmentTarget":{"type":"number","description":"Target investment amount"},"investmentMinimum":{"type":"number","description":"Minimum investment amount"},"investmentMaximum":{"type":"number","description":"Maximum investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)","default":"USD"},"legalFormationDate":{"type":"string","format":"date","description":"Date of legal formation"},"fees":{"type":"object","description":"Fee structure","properties":{"managementFee":{"type":"number","description":"Management fee percentage"},"carriedInterest":{"type":"number","description":"Carried interest percentage"},"establishmentFee":{"type":"number","description":"One-time establishment fee"}}},"legalDocuments":{"type":"array","description":"Associated legal documents","items":{"type":"object","properties":{"documentType":{"type":"string","enum":["operating_agreement","subscription_agreement","ppm","term_sheet"],"description":"Type of document"},"documentId":{"type":"string","description":"Document ID in storage"}}}}}}}}},"responses":{"201":{"description":"SPV created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SPV","type":"object","properties":{"_id":{"type":"string","description":"SPV unique identifier"},"name":{"type":"string","description":"Name of the SPV"},"legalEntityType":{"type":"string","enum":["llc","lp","corporation","trust"],"description":"Legal entity type"},"managerId":{"type":"string","description":"ID of the managing user or company"},"status":{"type":"string","enum":["draft","active","closed","liquidated"],"description":"Current status of the SPV"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/documents":{"get":{"tags":["Document Management"],"summary":"Get all documents","operationId":"getDocuments","responses":{"200":{"description":"List of documents retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"description":"Retrieve a list of all documents the user has access to","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":10},"description":"Maximum number of records to return"},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Page number for pagination"},{"in":"query","name":"type","schema":{"type":"string","enum":["contract","report","legal","tax","other"]},"description":"Filter by document type"}]},"post":{"tags":["Document Management"],"summary":"Upload a new document","description":"Upload a new document with metadata","operationId":"uploadDocument","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","name","type"],"properties":{"file":{"type":"string","format":"binary","description":"Document file to upload"},"name":{"type":"string","description":"Document name"},"type":{"type":"string","enum":["contract","report","legal","tax","other"],"description":"Document type"},"description":{"type":"string","description":"Document description"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags to categorize the document"},"entityId":{"type":"string","description":"ID of the related entity (e.g., company, SPV, investor)"},"entityType":{"type":"string","enum":["company","spv","investor","employee","other"],"description":"Type of the related entity"}}}}}},"responses":{"201":{"description":"Document uploaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"description":"File too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/ai/documents/extract":{"post":{"summary":"Extract text from document content","description":"Extracts text from various document formats (PDF, DOCX, images, etc.)","tags":["AI Document Processing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content","mimeType"],"properties":{"content":{"type":"string","description":"Document content (base64 for binary files)"},"mimeType":{"type":"string","description":"MIME type of the document"}}}}}},"responses":{"200":{"description":"Extracted text with metadata"},"400":{"description":"Invalid request"},"500":{"description":"Server error"}}}},"/api/v1/ai/documents/preprocess":{"post":{"summary":"Preprocess text","description":"Clean and normalize text for further processing","tags":["AI Document Processing"]}},"/api/v1/ai/documents/detect-language":{"post":{"summary":"Detect document language","description":"Detect the language of document text","tags":["AI Document Processing"]}},"/api/v1/ai/documents/extract-entities":{"post":{"summary":"Extract named entities","description":"Extract companies, people, dates, money, and other entities","tags":["AI Document Processing"]}},"/api/v1/ai/documents/batch":{"post":{"summary":"Process documents in batch","description":"Process multiple documents at once","tags":["AI Document Processing"]}},"/api/v1/ai/documents/supported-types":{"get":{"summary":"Get supported MIME types","description":"Returns list of supported document MIME types","tags":["AI Document Processing"]}},"/api/v1/ai/classify":{"post":{"summary":"Classify document","description":"Classify document type (contract, financial, legal, etc.)","tags":["AI Document Classification"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"Document text to classify"},"options":{"type":"object","properties":{"topN":{"type":"integer","description":"Number of top classifications to return"}}}}}}}},"responses":{"200":{"description":"Classification result"}}}},"/api/v1/ai/classify/confidence":{"post":{"summary":"Get classification confidence","description":"Get confidence score for a specific classification type","tags":["AI Document Classification"]}},"/api/v1/ai/classify/train":{"post":{"summary":"Train classifier","description":"Train/update classifier with new examples","tags":["AI Document Classification"]}},"/api/v1/ai/classify/stats":{"get":{"summary":"Get classification statistics","description":"Get accuracy and usage statistics","tags":["AI Document Classification"]}},"/api/v1/ai/classify/batch":{"post":{"summary":"Classify documents in batch","description":"Classify multiple documents at once","tags":["AI Document Classification"]}},"/api/v1/ai/classify/feedback":{"post":{"summary":"Submit classification feedback","description":"Submit correction for a classification","tags":["AI Document Classification"]}},"/api/v1/ai/classify/types":{"get":{"summary":"Get supported classification types","description":"Returns list of supported document types","tags":["AI Document Classification"]}},"/api/v1/ai/classify/training-history":{"get":{"summary":"Get training history","description":"Returns history of classifier training","tags":["AI Document Classification"]}},"/api/v1/ai/summarize":{"post":{"summary":"Generate document summary","description":"Generate a summary from document text","tags":["AI Document Summarization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"Document text to summarize"},"options":{"type":"object","properties":{"maxLength":{"type":"integer","description":"Maximum summary length"},"style":{"type":"string","enum":["extractive","abstractive"]}}}}}}}},"responses":{"200":{"description":"Summary result"}}}},"/api/v1/ai/summarize/key-points":{"post":{"summary":"Extract key points","description":"Extract key points from document","tags":["AI Document Summarization"]}},"/api/v1/ai/summarize/executive":{"post":{"summary":"Generate executive summary","description":"Generate a short executive summary","tags":["AI Document Summarization"]}},"/api/v1/ai/summarize/multiple":{"post":{"summary":"Summarize multiple documents","description":"Create unified summary from multiple documents","tags":["AI Document Summarization"]}},"/api/v1/ai/summarize/batch":{"post":{"summary":"Summarize documents in batch","description":"Summarize multiple documents individually","tags":["AI Document Summarization"]}},"/api/v1/ai/analyze":{"post":{"summary":"Comprehensive document analysis","description":"Perform full analysis including sentiment, risks, and financial data","tags":["AI Document Analysis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"Document text to analyze"}}}}}},"responses":{"200":{"description":"Analysis result"}}}},"/api/v1/ai/analyze/sentiment":{"post":{"summary":"Analyze sentiment","description":"Analyze document sentiment (positive, negative, neutral)","tags":["AI Document Analysis"]}},"/api/v1/ai/analyze/risks":{"post":{"summary":"Detect risks","description":"Identify risk indicators in document","tags":["AI Document Analysis"]}},"/api/v1/ai/analyze/financial":{"post":{"summary":"Extract financial data","description":"Extract revenue, profit, expenses, and other financial figures","tags":["AI Document Analysis"]}},"/api/v1/ai/analyze/insights":{"post":{"summary":"Generate insights","description":"Generate AI-powered insights from document","tags":["AI Document Analysis"]}},"/api/v1/ai/analyze/batch":{"post":{"summary":"Analyze documents in batch","description":"Analyze multiple documents at once","tags":["AI Document Analysis"]}},"/api/v1/metrics/dashboard":{"get":{"summary":"Get metrics dashboard data","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"startTime","schema":{"type":"integer"},"description":"Start time filter (Unix timestamp)"},{"in":"query","name":"endTime","schema":{"type":"integer"},"description":"End time filter (Unix timestamp)"}],"responses":{"200":{"description":"Dashboard metrics data"}}}},"/api/v1/metrics/report":{"get":{"summary":"Get comprehensive performance report","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"startTime","schema":{"type":"integer"},"description":"Start time filter (Unix timestamp)"},{"in":"query","name":"endTime","schema":{"type":"integer"},"description":"End time filter (Unix timestamp)"},{"in":"query","name":"format","schema":{"type":"string","enum":["json","csv"]},"description":"Response format"}],"responses":{"200":{"description":"Performance report"}}}},"/api/v1/metrics/endpoints/{endpoint}":{"get":{"summary":"Get metrics for a specific endpoint","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"endpoint","required":true,"schema":{"type":"string"},"description":"URL-encoded endpoint path"},{"in":"query","name":"method","schema":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"description":"HTTP method filter"}],"responses":{"200":{"description":"Endpoint metrics"},"400":{"description":"Missing endpoint parameter"}}}},"/api/v1/metrics/endpoints/{endpoint}/percentiles":{"get":{"summary":"Get percentile data for an endpoint","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"endpoint","required":true,"schema":{"type":"string"},"description":"URL-encoded endpoint path"},{"in":"query","name":"percentiles","schema":{"type":"string"},"description":"Comma-separated list of percentiles (e.g., \"50,75,90,95,99\")"}],"responses":{"200":{"description":"Percentile data"}}}},"/api/v1/metrics/endpoints/{endpoint}/histogram":{"get":{"summary":"Get response time histogram for an endpoint","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"endpoint","required":true,"schema":{"type":"string"},"description":"URL-encoded endpoint path"},{"in":"query","name":"buckets","schema":{"type":"string"},"description":"Comma-separated bucket boundaries (e.g., \"50,100,200,500,1000\")"}],"responses":{"200":{"description":"Histogram data"}}}},"/api/v1/metrics/errors":{"get":{"summary":"Get error rates for all endpoints","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"minErrorRate","schema":{"type":"number"},"description":"Minimum error rate filter (0-1)"}],"responses":{"200":{"description":"Error rates by endpoint"}}}},"/api/v1/metrics/throughput":{"get":{"summary":"Get throughput data","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"windowMs","schema":{"type":"integer"},"description":"Window size in milliseconds"}],"responses":{"200":{"description":"Throughput data by endpoint"}}}},"/api/v1/metrics/slowest":{"get":{"summary":"Get slowest endpoints","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer"},"description":"Number of endpoints to return (default 10)"}],"responses":{"200":{"description":"List of slowest endpoints"}}}},"/api/v1/metrics/health":{"get":{"summary":"Get health status based on metrics","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Health status"}}}},"/api/v1/metrics/reset":{"post":{"summary":"Reset metrics (admin only)","tags":["API Metrics"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Specific endpoint to reset (optional, resets all if not provided)"}}}}}},"responses":{"200":{"description":"Metrics reset successfully"},"403":{"description":"Admin access required"}}}},"/api/v1/cache/stats":{"get":{"summary":"Get cache statistics","tags":["Cache"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Cache statistics"}}}},"/api/v1/cache/flush":{"post":{"summary":"Flush all cache (admin only)","tags":["Cache"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Cache flushed successfully"},"403":{"description":"Insufficient permissions"}}}},"/api/v1/cache/invalidate":{"post":{"summary":"Invalidate cache by pattern","tags":["Cache"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pattern":{"type":"string","description":"Pattern to invalidate (supports wildcards)"},"patterns":{"type":"array","items":{"type":"string"},"description":"Multiple patterns to invalidate"}}}}}},"responses":{"200":{"description":"Cache invalidated successfully"}}}},"/api/v1/cache/keys":{"get":{"summary":"List all cache keys","tags":["Cache"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"pattern","schema":{"type":"string"},"description":"Filter pattern"},{"in":"query","name":"limit","schema":{"type":"integer","default":100}},{"in":"query","name":"offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"List of cache keys"}}},"post":{"summary":"Set a cache key","tags":["Cache"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"any"},"ttl":{"type":"integer","description":"Time to live in milliseconds"}}}}}},"responses":{"201":{"description":"Cache key set successfully"}}}},"/api/v1/cache/keys/{key}":{"get":{"summary":"Get value for a specific cache key","tags":["Cache"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string"},"description":"Cache key (URL encoded)"}],"responses":{"200":{"description":"Cache key value"}}},"delete":{"summary":"Delete a specific cache key","tags":["Cache"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string"},"description":"Cache key (URL encoded)"}],"responses":{"200":{"description":"Cache key deleted"},"404":{"description":"Key not found"}}}},"/api/v1/cache/query-stats":{"get":{"summary":"Get query cache statistics","tags":["Cache"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Query cache statistics"}}}},"/api/v1/cache/warm":{"post":{"summary":"Warm cache for specified queries (admin only)","tags":["Cache"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["queries"],"properties":{"queries":{"type":"array","items":{"type":"object","properties":{"collection":{"type":"string"},"filter":{"type":"object"}}}}}}}}},"responses":{"200":{"description":"Cache warming results"},"403":{"description":"Insufficient permissions"}}}},"/api/v1/cache/metrics":{"get":{"summary":"Get database metrics","tags":["Cache"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Database metrics"}}}},"/api/v1/cache/performance-report":{"get":{"summary":"Generate performance report (admin only)","tags":["Cache"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"startTime","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"endTime","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"format","schema":{"type":"string","enum":["json","text"],"default":"json"}}],"responses":{"200":{"description":"Performance report"},"403":{"description":"Insufficient permissions"}}}},"/api/v1/cache/health":{"get":{"summary":"Get database health status","tags":["Cache"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Database is healthy"},"503":{"description":"Database is unhealthy"}}}},"/api/v1/data-processing/etl/run":{"post":{"summary":"Run an ETL pipeline","tags":["Data Processing - ETL"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","extract","load"],"properties":{"name":{"type":"string"},"extract":{"type":"object"},"transform":{"type":"object"},"load":{"type":"object"},"dryRun":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Pipeline executed successfully"},"400":{"description":"Invalid configuration"},"500":{"description":"Pipeline execution failed"}}}},"/api/v1/data-processing/etl/running":{"get":{"summary":"List all running ETL pipelines","tags":["Data Processing - ETL"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of running pipelines"}}}},"/api/v1/data-processing/etl/{pipelineId}/status":{"get":{"summary":"Get ETL pipeline status","tags":["Data Processing - ETL"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"pipelineId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pipeline status"},"404":{"description":"Pipeline not found"}}}},"/api/v1/data-processing/etl/{pipelineId}/cancel":{"post":{"summary":"Cancel a running ETL pipeline","tags":["Data Processing - ETL"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"pipelineId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pipeline cancelled"},"400":{"description":"Cannot cancel pipeline"}}}},"/api/v1/data-processing/batch/schedule":{"post":{"summary":"Schedule a batch processing job","tags":["Data Processing - Batch"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","data","schedule"],"properties":{"name":{"type":"string"},"data":{"type":"array"},"schedule":{"type":"object"},"priority":{"type":"string","enum":["low","normal","high"]}}}}}},"responses":{"201":{"description":"Job scheduled successfully"},"400":{"description":"Invalid job configuration"}}}},"/api/v1/data-processing/batch/jobs":{"get":{"summary":"List all batch jobs","tags":["Data Processing - Batch"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["scheduled","running","completed","failed","cancelled"]}}],"responses":{"200":{"description":"List of batch jobs"}}}},"/api/v1/data-processing/batch/stats":{"get":{"summary":"Get batch processing queue statistics","tags":["Data Processing - Batch"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Queue statistics"}}}},"/api/v1/data-processing/batch/{jobId}/status":{"get":{"summary":"Get batch job status","tags":["Data Processing - Batch"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status"},"404":{"description":"Job not found"}}}},"/api/v1/data-processing/batch/{jobId}/cancel":{"post":{"summary":"Cancel a batch job","tags":["Data Processing - Batch"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancelFutureExecutions":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Job cancelled"},"400":{"description":"Cannot cancel job"}}}},"/api/v1/data-processing/batch/queue/{action}":{"post":{"summary":"Pause or resume the batch processing queue","tags":["Data Processing - Batch"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"action","required":true,"schema":{"type":"string","enum":["pause","resume"]}}],"responses":{"200":{"description":"Queue action performed"},"400":{"description":"Invalid action"}}}},"/api/v1/data-processing/quality/validate":{"post":{"summary":"Validate data against a schema","tags":["Data Processing - Quality"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data","schema"],"properties":{"data":{"type":"array"},"schema":{"type":"object"}}}}}},"responses":{"200":{"description":"Validation results"},"400":{"description":"Invalid input"}}}},"/api/v1/data-processing/quality/completeness":{"post":{"summary":"Check data completeness","tags":["Data Processing - Quality"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array"},"options":{"type":"object"}}}}}},"responses":{"200":{"description":"Completeness results"},"400":{"description":"Invalid input"}}}},"/api/v1/data-processing/quality/anomalies":{"post":{"summary":"Detect anomalies in data","tags":["Data Processing - Quality"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data","config"],"properties":{"data":{"type":"array"},"config":{"type":"object","properties":{"method":{"type":"string","enum":["zscore","iqr","pattern","null_detection","business_rules"]},"fields":{"type":"array"},"threshold":{"type":"number"}}}}}}}},"responses":{"200":{"description":"Anomaly detection results"},"400":{"description":"Invalid input"}}}},"/api/v1/data-processing/quality/report":{"post":{"summary":"Generate comprehensive data quality report","tags":["Data Processing - Quality"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array"},"config":{"type":"object"}}}}}},"responses":{"200":{"description":"Quality report"},"400":{"description":"Invalid input"}}}},"/api/v1/data-processing/quality/profile":{"post":{"summary":"Profile data to understand its structure and characteristics","tags":["Data Processing - Quality"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array"}}}}}},"responses":{"200":{"description":"Data profile"},"400":{"description":"Invalid input"}}}},"/api/v1/data-processing/stream/metrics":{"get":{"summary":"Get stream processing metrics","tags":["Data Processing - Stream"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Stream processing metrics"}}}},"/api/v1/data-processing/stream/dlq":{"get":{"summary":"Get dead letter queue contents","tags":["Data Processing - Stream"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Dead letter queue events"}}}},"/api/v1/email-tracking":{"post":{"summary":"Create email tracking record","tags":["Email Tracking"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messageId","recipientEmail","senderEmail","subject"],"properties":{"messageId":{"type":"string"},"recipientEmail":{"type":"string"},"senderEmail":{"type":"string"},"subject":{"type":"string"},"templateId":{"type":"string"},"companyId":{"type":"string"}}}}}},"responses":{"201":{"description":"Tracking record created"},"400":{"description":"Invalid input"}}},"get":{"summary":"List email tracking records","tags":["Email Tracking"],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["queued","sent","delivered","opened","clicked","bounced","failed","spam","unsubscribed"]}},{"in":"query","name":"templateId","schema":{"type":"string"}},{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of tracking records"}}}},"/api/v1/email-tracking/analytics":{"get":{"summary":"Get email analytics","tags":["Email Tracking"],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"}},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"}},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"}},{"in":"query","name":"groupBy","schema":{"type":"string","enum":["template","date"]}}],"responses":{"200":{"description":"Email analytics data"}}}},"/api/v1/email-tracking/engagement":{"get":{"summary":"Get engagement report","tags":["Email Tracking"],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"}}],"responses":{"200":{"description":"Engagement report"}}}},"/api/v1/email-tracking/bounced":{"get":{"summary":"Get bounced emails","tags":["Email Tracking"],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"}}],"responses":{"200":{"description":"List of bounced emails"}}}},"/api/v1/email-tracking/suppressed":{"get":{"summary":"Get suppressed emails","tags":["Email Tracking"],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"}}],"responses":{"200":{"description":"List of suppressed emails"}}}},"/api/v1/email-tracking/suppression/{email}":{"get":{"summary":"Check if email is suppressed","tags":["Email Tracking"],"parameters":[{"in":"path","name":"email","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Suppression status"}}},"delete":{"summary":"Remove email from suppression list","tags":["Email Tracking"],"parameters":[{"in":"path","name":"email","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Suppression removed"},"404":{"description":"Email not found in suppression list"}}}},"/api/v1/email-tracking/pixel/{trackingId}":{"get":{"summary":"Tracking pixel endpoint (records email open)","tags":["Email Tracking"],"parameters":[{"in":"path","name":"trackingId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns 1x1 transparent GIF","content":{"image/gif":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v1/email-tracking/click/{trackingId}":{"get":{"summary":"Click tracking endpoint (records click and redirects)","tags":["Email Tracking"],"parameters":[{"in":"path","name":"trackingId","required":true,"schema":{"type":"string"}},{"in":"query","name":"url","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Redirects to original URL"},"400":{"description":"Missing URL parameter"}}}},"/api/v1/email-tracking/webhook/{provider}":{"post":{"summary":"Webhook endpoint for email providers","tags":["Email Tracking"],"parameters":[{"in":"path","name":"provider","required":true,"schema":{"type":"string","enum":["sendgrid","mailgun","ses","postmark","sparkpost"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Webhook processed"},"400":{"description":"Unsupported provider"}}}},"/api/v1/email-tracking/message/{messageId}":{"get":{"summary":"Get tracking record by message ID","tags":["Email Tracking"],"parameters":[{"in":"path","name":"messageId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tracking record"},"404":{"description":"Record not found"}}}},"/api/v1/email-tracking/{id}":{"get":{"summary":"Get tracking record by ID","tags":["Email Tracking"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tracking record"},"404":{"description":"Record not found"}}}},"/api/v1/files":{"post":{"summary":"Upload a file","tags":["Files"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"category":{"type":"string"},"metadata":{"type":"string"}}}}}},"responses":{"201":{"description":"File uploaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadResponse"}}}},"400":{"description":"Bad request - no file or invalid file"},"500":{"description":"Server error"}}},"get":{"summary":"List files","tags":["Files"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"limit","schema":{"type":"integer"}},{"in":"query","name":"contentType","schema":{"type":"string"}}],"responses":{"200":{"description":"List of files with pagination"}}}},"/api/v1/files/batch":{"post":{"summary":"Upload multiple files","tags":["Files"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"string","format":"binary"}}}}}}},"responses":{"201":{"description":"All files uploaded successfully"},"207":{"description":"Partial success - some files failed"}}}},"/api/v1/files/search":{"post":{"summary":"Search files by metadata","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"criteria":{"type":"object"},"skip":{"type":"integer"},"limit":{"type":"integer"}}}}}},"responses":{"200":{"description":"Search results"}}}},"/api/v1/files/usage":{"get":{"summary":"Get storage usage statistics","tags":["Files"],"responses":{"200":{"description":"Storage usage statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUsage"}}}}}}},"/api/v1/files/{id}/download":{"get":{"summary":"Download a file","tags":["Files"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File content"},"404":{"description":"File not found"}}}},"/api/v1/files/{id}/url":{"get":{"summary":"Get presigned URL for file","tags":["Files"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"expiresIn","schema":{"type":"integer","description":"URL expiration time in seconds"}}],"responses":{"200":{"description":"Presigned URL"}}}},"/api/v1/files/{id}/metadata":{"get":{"summary":"Get file metadata","tags":["Files"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileMetadata"}}}},"404":{"description":"File not found"}}},"patch":{"summary":"Update file metadata","tags":["Files"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object"},"merge":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated metadata"},"404":{"description":"File not found"}}}},"/api/v1/files/{id}/versions":{"get":{"summary":"Get version history","tags":["Files"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Version history"}}},"post":{"summary":"Create new version of file","tags":["Files"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"preserveMetadata":{"type":"boolean"}}}}}},"responses":{"201":{"description":"New version created"}}}},"/api/v1/files/{id}/restore":{"post":{"summary":"Restore a previous version","tags":["Files"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"integer"}}}}}},"responses":{"200":{"description":"Version restored"}}}},"/api/v1/files/{id}":{"delete":{"summary":"Delete a file","tags":["Files"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"soft","schema":{"type":"boolean","description":"Soft delete (mark as deleted but don't remove)"}}],"responses":{"200":{"description":"File deleted"},"404":{"description":"File not found"}}}},"/api/v1/financial-data/import":{"post":{"tags":["Financial Data"],"summary":"Import financial data","description":"Import financial data from CSV, Excel, or JSON files","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to import"},"importType":{"type":"string","enum":["transactions","financial_reports","spv_data","chart_of_accounts"],"description":"Type of data being imported"},"companyId":{"type":"string","description":"Company ID for the imported data"},"format":{"type":"string","enum":["csv","json","xlsx"],"description":"File format"}}}}}},"responses":{"200":{"description":"Import completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"recordsProcessed":{"type":"integer"},"recordsSuccessful":{"type":"integer"},"recordsFailed":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Invalid request or validation errors"},"403":{"description":"Insufficient permissions"}}}},"/api/v1/financial-data/export":{"get":{"tags":["Financial Data"],"summary":"Export financial data","description":"Export financial data in various formats","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"exportType","required":true,"schema":{"type":"string","enum":["transactions","financial_reports","spv_performance","compliance_report"]},"description":"Type of data to export"},{"in":"query","name":"format","required":true,"schema":{"type":"string","enum":["csv","json","xlsx","pdf"]},"description":"Export format"},{"in":"query","name":"companyId","schema":{"type":"string"},"description":"Filter by company ID"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"},"description":"Start date for date range filter"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"},"description":"End date for date range filter"},{"in":"query","name":"limit","schema":{"type":"integer","default":10000},"description":"Maximum number of records to export"}],"responses":{"200":{"description":"Export completed successfully","content":{"text/csv":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid export parameters"},"403":{"description":"Insufficient permissions"}}}},"/api/v1/financial-data/templates/{importType}":{"get":{"tags":["Financial Data"],"summary":"Get import template","description":"Download a template file for importing specific data types","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"importType","required":true,"schema":{"type":"string","enum":["transactions","financial_reports","spv_data","chart_of_accounts"]},"description":"Type of import template"},{"in":"query","name":"format","schema":{"type":"string","enum":["csv","json"],"default":"csv"},"description":"Template format"}],"responses":{"200":{"description":"Template file downloaded successfully"},"400":{"description":"Invalid import type"}}}},"/api/v1/financial-data/import-status/{importId}":{"get":{"tags":["Financial Data"],"summary":"Get import status","description":"Check the status of a long-running import operation","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"importId","required":true,"schema":{"type":"string"},"description":"Import operation ID"}],"responses":{"200":{"description":"Import status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"importId":{"type":"string"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"progress":{"type":"number","minimum":0,"maximum":100},"recordsProcessed":{"type":"integer"},"totalRecords":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}}}}}}},"404":{"description":"Import operation not found"}}}},"/api/v1/financial-data/validate":{"post":{"tags":["Financial Data"],"summary":"Validate import data","description":"Validate import data without actually importing it","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"importType":{"type":"string","enum":["transactions","financial_reports","spv_data","chart_of_accounts"]},"format":{"type":"string","enum":["csv","json","xlsx"]}}}}}},"responses":{"200":{"description":"Validation completed","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"totalRecords":{"type":"integer"},"validRecords":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Validation failed"}}}},"/api/v1/metrics/companies/{companyId}/metrics/profitability":{"get":{"tags":["Financial Metrics"],"summary":"Calculate profitability metrics for a company","description":"Calculates gross profit margin, operating profit margin, and net profit margin","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","schema":{"type":"string"},"required":true,"description":"Unique ID of the company"},{"in":"query","name":"period","schema":{"type":"string"},"required":true,"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Profitability metrics calculated successfully"},"400":{"description":"Invalid input parameters"},"401":{"description":"Unauthorized - Missing or invalid authentication"},"403":{"description":"Forbidden - Insufficient permissions"},"404":{"description":"No financial data found for the specified period"},"500":{"description":"Server error while calculating metrics"}}}},"/api/v1/metrics/companies/{companyId}/metrics/liquidity":{"get":{"tags":["Financial Metrics"],"summary":"Calculate liquidity metrics for a company","description":"Calculates current ratio, quick ratio, and cash ratio","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","schema":{"type":"string"},"required":true,"description":"Unique ID of the company"},{"in":"query","name":"period","schema":{"type":"string"},"required":true,"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Liquidity metrics calculated successfully"},"400":{"description":"Invalid input parameters"},"401":{"description":"Unauthorized - Missing or invalid authentication"},"403":{"description":"Forbidden - Insufficient permissions"},"404":{"description":"No financial data found for the specified period"},"500":{"description":"Server error while calculating metrics"}}}},"/api/v1/metrics/companies/{companyId}/metrics/solvency":{"get":{"tags":["Financial Metrics"],"summary":"Calculate solvency metrics for a company","description":"Calculates debt-to-equity ratio, debt-to-asset ratio, and interest coverage ratio","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","schema":{"type":"string"},"required":true,"description":"Unique ID of the company"},{"in":"query","name":"period","schema":{"type":"string"},"required":true,"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Solvency metrics calculated successfully"},"400":{"description":"Invalid input parameters"},"401":{"description":"Unauthorized - Missing or invalid authentication"},"403":{"description":"Forbidden - Insufficient permissions"},"404":{"description":"No financial data found for the specified period"},"500":{"description":"Server error while calculating metrics"}}}},"/api/v1/metrics/companies/{companyId}/metrics/efficiency":{"get":{"tags":["Financial Metrics"],"summary":"Calculate efficiency metrics for a company","description":"Calculates asset turnover, inventory turnover, and receivables turnover ratios","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","schema":{"type":"string"},"required":true,"description":"Unique ID of the company"},{"in":"query","name":"period","schema":{"type":"string"},"required":true,"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Efficiency metrics calculated successfully"},"400":{"description":"Invalid input parameters"},"401":{"description":"Unauthorized - Missing or invalid authentication"},"403":{"description":"Forbidden - Insufficient permissions"},"404":{"description":"No financial data found for the specified period"},"500":{"description":"Server error while calculating metrics"}}}},"/api/v1/metrics/companies/{companyId}/metrics/dashboard":{"get":{"tags":["Financial Metrics"],"summary":"Get financial metrics dashboard","description":"Returns a comprehensive dashboard of all financial metrics","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","schema":{"type":"string"},"required":true,"description":"Unique ID of the company"}],"responses":{"200":{"description":"Financial metrics dashboard retrieved successfully"},"401":{"description":"Unauthorized - Missing or invalid authentication"},"403":{"description":"Forbidden - Insufficient permissions"},"500":{"description":"Server error while retrieving dashboard"}}}},"/api/v1/material-events":{"post":{"summary":"Create a new material event","tags":["Material Events"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId","eventType","description"],"properties":{"companyId":{"type":"string"},"eventType":{"type":"string","enum":["fundraising_round","significant_transaction","key_employee_departure","key_employee_hire","acquisition_offer","merger_discussion","major_customer_change","major_product_launch","significant_revenue_change","litigation","regulatory_change","market_condition_change","ipo_preparation","secondary_transaction","other"]},"eventDate":{"type":"string","format":"date"},"description":{"type":"string"},"triggersValuation":{"type":"boolean"},"impactSeverity":{"type":"string","enum":["low","medium","high","critical"]}}}}}},"responses":{"201":{"description":"Event created"},"400":{"description":"Invalid input"}}}},"/api/v1/material-events/action-required":{"get":{"summary":"Get events requiring action","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"},"description":"Filter by company (optional)"}],"responses":{"200":{"description":"List of events requiring action"}}}},"/api/v1/material-events/valuation-triggers":{"get":{"summary":"Get events that trigger 409A valuation","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"},"description":"Filter by company (optional)"}],"responses":{"200":{"description":"List of valuation trigger events"}}}},"/api/v1/material-events/detect/fundraising-round":{"post":{"summary":"Auto-detect material event from fundraising round","tags":["Material Events"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId"],"properties":{"companyId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"amount":{"type":"number"},"closedDate":{"type":"string","format":"date"}}}}}},"responses":{"201":{"description":"Event detected and created"}}}},"/api/v1/material-events/detect/employee-change":{"post":{"summary":"Auto-detect material event from employee change","tags":["Material Events"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["employeeData","changeType"],"properties":{"employeeData":{"type":"object","properties":{"companyId":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"}}},"changeType":{"type":"string","enum":["departure","hire"]}}}}}},"responses":{"201":{"description":"Event detected and created"}}}},"/api/v1/material-events/company/{companyId}":{"get":{"summary":"Get all material events for a company","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"eventType","schema":{"type":"string"}},{"in":"query","name":"triggersValuation","schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of material events"}}}},"/api/v1/material-events/company/{companyId}/summary":{"get":{"summary":"Get material event summary for a company","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event summary"}}}},"/api/v1/material-events/company/{companyId}/compliance-dashboard":{"get":{"summary":"Get compliance dashboard data for a company","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Compliance dashboard data"}}}},"/api/v1/material-events/{eventId}":{"get":{"summary":"Get a specific material event","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event details"},"404":{"description":"Event not found"}}},"put":{"summary":"Update a material event","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event updated"}}}},"/api/v1/material-events/{eventId}/acknowledge":{"post":{"summary":"Acknowledge a material event","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event acknowledged"}}}},"/api/v1/material-events/{eventId}/action-required":{"post":{"summary":"Mark event as action required","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"actionItems":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"assignedTo":{"type":"string"},"dueDate":{"type":"string","format":"date"}}}},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Event marked as action required"}}}},"/api/v1/material-events/{eventId}/resolve":{"post":{"summary":"Resolve a material event","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string"},"valuationRequestId":{"type":"string"}}}}}},"responses":{"200":{"description":"Event resolved"}}}},"/api/v1/material-events/{eventId}/dismiss":{"post":{"summary":"Dismiss a material event","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Event dismissed"}}}},"/api/v1/material-events/{eventId}/action-items":{"post":{"summary":"Add action item to event","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string"},"assignedTo":{"type":"string"},"dueDate":{"type":"string","format":"date"}}}}}},"responses":{"200":{"description":"Action item added"}}}},"/api/v1/material-events/{eventId}/action-items/{actionItemId}/complete":{"post":{"summary":"Complete an action item","tags":["Material Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}},{"in":"path","name":"actionItemId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Action item completed"}}}},"/api/v1/search":{"get":{"summary":"Global multi-entity search","description":"Search across multiple entity types including stakeholders, documents, tasks,\ncompanies, share classes, 409A valuations, and messages. Returns unified results\nwith relevance scores for each entity type.\n","tags":["Search"],"parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string","minLength":2,"maxLength":500},"description":"Search query (2-500 characters)","example":"john doe investment"},{"in":"query","name":"types","required":false,"schema":{"type":"string"},"description":"Comma-separated list of entity types to search.\nIf not specified, searches all types.\nValid types: stakeholders, documents, tasks, companies, share_classes, valuations, messages\n","example":"stakeholders,documents"},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Maximum number of results per entity type","example":10},{"in":"query","name":"offset","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Pagination offset for results","example":0}],"responses":{"200":{"description":"Search results successfully retrieved","headers":{"X-Search-Time-Ms":{"description":"Search execution time in milliseconds","schema":{"type":"integer"}},"X-Total-Count":{"description":"Total number of results across all entity types","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"query":{"type":"string","example":"john doe investment"},"results":{"type":"object","properties":{"stakeholders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"relevance":{"type":"number","minimum":0,"maximum":1},"entityType":{"type":"string","enum":["stakeholder"]}}}},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"type":{"type":"string"},"relevance":{"type":"number","minimum":0,"maximum":1},"entityType":{"type":"string","enum":["document"]}}}},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"assignee":{"type":"string"},"relevance":{"type":"number","minimum":0,"maximum":1},"entityType":{"type":"string","enum":["task"]}}}},"companies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"relevance":{"type":"number","minimum":0,"maximum":1},"entityType":{"type":"string","enum":["company"]}}}},"share_classes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"relevance":{"type":"number","minimum":0,"maximum":1},"entityType":{"type":"string","enum":["share_class"]}}}},"valuations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"valuationId":{"type":"string"},"firm":{"type":"string"},"status":{"type":"string"},"fairMarketValue":{"type":"number"},"effectiveDate":{"type":"string","format":"date"},"relevance":{"type":"number","minimum":0,"maximum":1},"entityType":{"type":"string","enum":["valuation"]}}}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"sender":{"type":"string"},"recipient":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"relevance":{"type":"number","minimum":0,"maximum":1},"entityType":{"type":"string","enum":["message"]}}}}}},"totalResults":{"type":"integer","example":45},"metadata":{"type":"object","properties":{"limit":{"type":"integer","example":10},"offset":{"type":"integer","example":0},"searchTimeMs":{"type":"integer","example":127},"timedOut":{"type":"boolean","example":false}}}}},"examples":{"allTypes":{"summary":"Search all entity types","value":{"success":true,"query":"john doe","results":{"stakeholders":[{"id":"123","name":"John Doe","email":"john@example.com","role":"investor","relevance":0.95,"entityType":"stakeholder"}],"documents":[{"id":"456","name":"Investment Agreement - John Doe","title":"Investment Agreement","type":"contract","relevance":0.87,"entityType":"document"}],"tasks":[{"id":"789","title":"Follow up with John Doe","description":"Schedule meeting","status":"pending","assignee":"user456","relevance":0.75,"entityType":"task"}]},"totalResults":3,"metadata":{"limit":10,"offset":0,"searchTimeMs":127,"timedOut":false}}},"filteredTypes":{"summary":"Search specific entity types","value":{"success":true,"query":"acme corp","results":{"companies":[{"id":"comp123","name":"Acme Corporation","type":"startup","relevance":0.92,"entityType":"company"}]},"totalResults":1,"metadata":{"limit":10,"offset":0,"searchTimeMs":45,"timedOut":false}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}},"examples":{"missingQuery":{"summary":"Missing query parameter","value":{"success":false,"error":"Query parameter \"q\" is required"}},"invalidType":{"summary":"Invalid entity type","value":{"success":false,"error":"Invalid entity type: invalid_type. Valid types are: stakeholders, documents, tasks, companies, share_classes, valuations, messages"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"An error occurred while processing your search request"}}}}}}}}},"/api/v1/search/suggestions":{"get":{"summary":"Get search suggestions for autocomplete","description":"Returns search suggestions based on partial query input.\nUseful for implementing autocomplete functionality in search interfaces.\nLimits results to 10 suggestions across all entity types.\n","tags":["Search"],"parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string","minLength":1},"description":"Partial search query","example":"john"}],"responses":{"200":{"description":"Search suggestions successfully retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"suggestions":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Suggestion text to display"},"type":{"type":"string","description":"Type of entity for UI display"},"entityType":{"type":"string","description":"Entity type for routing"},"id":{"type":"string","description":"Entity ID for direct navigation"}}}}}},"example":{"success":true,"suggestions":[{"text":"John Doe","type":"stakeholder","entityType":"stakeholder","id":"123"},{"text":"Johnson Corporation","type":"company","entityType":"company","id":"456"}]}}}},"400":{"description":"Missing query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Query parameter \"q\" is required"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Failed to get search suggestions"}}}}}}}}},"/api/v1/security-audits":{"get":{"tags":["Security Audits"],"summary":"Get security audit logs","description":"Retrieve security audit logs with filtering and pagination","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"eventType","schema":{"type":"string"},"description":"Filter by event type"},{"in":"query","name":"level","schema":{"type":"string","enum":["low","medium","high","critical"]},"description":"Filter by security level"},{"in":"query","name":"userId","schema":{"type":"string"},"description":"Filter by user ID"},{"in":"query","name":"days","schema":{"type":"integer","default":7},"description":"Number of days to look back"},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Page number"},{"in":"query","name":"limit","schema":{"type":"integer","default":50},"description":"Items per page"},{"in":"query","name":"reviewed","schema":{"type":"boolean"},"description":"Filter by review status"}],"responses":{"200":{"description":"Security audit logs retrieved successfully"},"403":{"description":"Access denied"}}}},"/api/v1/security-audits/summary":{"get":{"tags":["Security Audits"],"summary":"Get security audit summary","description":"Get aggregated statistics of security events","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":7},"description":"Number of days to analyze"}],"responses":{"200":{"description":"Security audit summary retrieved successfully"}}}},"/api/v1/security-audits/suspicious":{"get":{"tags":["Security Audits"],"summary":"Get suspicious activity","description":"Retrieve recent suspicious security events","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":1},"description":"Number of days to look back"}],"responses":{"200":{"description":"Suspicious activities retrieved successfully"}}}},"/api/v1/security-audits/{id}/review":{"patch":{"tags":["Security Audits"],"summary":"Mark audit log as reviewed","description":"Mark a security audit log entry as reviewed","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Audit log ID"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","description":"Review notes"}}}}}},"responses":{"200":{"description":"Audit log marked as reviewed"},"404":{"description":"Audit log not found"}}}},"/api/v1/security-audits/user/{userId}":{"get":{"tags":["Security Audits"],"summary":"Get user-specific audit logs","description":"Retrieve security audit logs for a specific user","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"userId","required":true,"schema":{"type":"string"},"description":"User ID"},{"in":"query","name":"days","schema":{"type":"integer","default":30},"description":"Number of days to look back"}],"responses":{"200":{"description":"User audit logs retrieved successfully"}}}},"/api/v1/security-audits/export":{"get":{"tags":["Security Audits"],"summary":"Export audit logs","description":"Export security audit logs in CSV format","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":30},"description":"Number of days to export"},{"in":"query","name":"level","schema":{"type":"string"},"description":"Filter by security level"}],"responses":{"200":{"description":"Audit logs exported successfully","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/api/v1/security-issuances":{"get":{"summary":"Get all security issuances","tags":["Security Issuances"],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"},"description":"Filter by company ID"},{"in":"query","name":"securityType","schema":{"type":"string"},"description":"Filter by security type"},{"in":"query","name":"exemptionType","schema":{"type":"string"},"description":"Filter by exemption type"}],"responses":{"200":{"description":"List of security issuances"}}},"post":{"summary":"Create a new security issuance","tags":["Security Issuances"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecurityIssuance"}}}},"responses":{"201":{"description":"Security issuance created successfully"},"400":{"description":"Invalid input"}}}},"/api/v1/security-issuances/compliance":{"get":{"summary":"Get compliance status for a company's issuances","tags":["Security Issuances"],"parameters":[{"in":"query","name":"companyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Compliance status summary"}}}},"/api/v1/security-issuances/overdue":{"get":{"summary":"Get overdue filings","tags":["Security Issuances"],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"}}],"responses":{"200":{"description":"List of overdue filings"}}}},"/api/v1/security-issuances/deadlines":{"get":{"summary":"Get upcoming filing deadlines","tags":["Security Issuances"],"parameters":[{"in":"query","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"daysAhead","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"List of upcoming deadlines"}}}},"/api/v1/security-issuances/exemption/{exemptionType}":{"get":{"summary":"Get issuances by exemption type","tags":["Security Issuances"],"parameters":[{"in":"query","name":"exemptionType","required":true,"schema":{"type":"string"}},{"in":"query","name":"companyId","schema":{"type":"string"}}],"responses":{"200":{"description":"List of issuances"}}}},"/api/v1/security-issuances/state-requirements":{"get":{"summary":"Get state filing requirements","tags":["Security Issuances"],"parameters":[{"in":"query","name":"exemptionType","required":true,"schema":{"type":"string"}},{"in":"query","name":"states","schema":{"type":"string"},"description":"Comma-separated list of state codes"}],"responses":{"200":{"description":"State filing requirements"}}}},"/api/v1/security-issuances/{id}":{"get":{"summary":"Get security issuance by ID","tags":["Security Issuances"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Security issuance details"},"404":{"description":"Security issuance not found"}}},"put":{"summary":"Update security issuance","tags":["Security Issuances"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecurityIssuance"}}}},"responses":{"200":{"description":"Security issuance updated"},"404":{"description":"Security issuance not found"}}},"delete":{"summary":"Delete security issuance","tags":["Security Issuances"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Security issuance deleted"},"404":{"description":"Security issuance not found"}}}},"/api/v1/security-issuances/{id}/state-filings":{"post":{"summary":"Add state filing to an issuance","tags":["Security Issuances"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateFiling"}}}},"responses":{"200":{"description":"State filing added"},"404":{"description":"Security issuance not found"}}}},"/api/v1/security-issuances/{id}/state-filings/{stateCode}":{"put":{"summary":"Update state filing","tags":["Security Issuances"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"stateCode","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateFiling"}}}},"responses":{"200":{"description":"State filing updated"},"404":{"description":"Security issuance or state filing not found"}}}},"/api/v1/documents/search":{"post":{"summary":"Search documents using semantic search","description":"Performs natural language search across indexed documents using vector similarity","tags":["Semantic Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Natural language search query","minLength":2,"maxLength":1000,"example":"stock options vesting schedule"},"filters":{"type":"object","properties":{"companyId":{"type":"string","description":"Filter by company ID"},"category":{"type":"string","description":"Filter by document category"},"categories":{"type":"array","items":{"type":"string"},"description":"Filter by multiple categories"},"dateRange":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}}},"status":{"type":"string","enum":["draft","active","archived","deleted"]},"tags":{"type":"array","items":{"type":"string"}}}},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"pageSize":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per page"},"minRelevance":{"type":"number","minimum":0,"maximum":1,"default":0,"description":"Minimum relevance score threshold"},"highlight":{"type":"boolean","default":false,"description":"Include highlighted excerpts in results"},"includeContent":{"type":"boolean","default":false,"description":"Include full document content in results"}}}}}},"responses":{"200":{"description":"Search results"},"400":{"description":"Invalid request parameters"},"500":{"description":"Search service error"}}}},"/api/v1/documents/search/suggestions":{"get":{"summary":"Get search suggestions","description":"Returns autocomplete suggestions based on partial query","tags":["Semantic Search"],"parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"},"description":"Partial search query"},{"in":"query","name":"limit","schema":{"type":"integer","default":10},"description":"Maximum number of suggestions"}],"responses":{"200":{"description":"Search suggestions"},"400":{"description":"Missing query parameter"},"500":{"description":"Service error"}}}},"/api/v1/documents/search/analytics":{"get":{"summary":"Get search analytics","description":"Returns analytics about search usage","tags":["Semantic Search"],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"},"description":"Filter analytics by company"}],"responses":{"200":{"description":"Search analytics data"},"500":{"description":"Service error"}}}},"/api/v1/stakeholders/{id}/reports":{"get":{"summary":"Get all reports for a stakeholder","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"},{"in":"query","name":"reportType","schema":{"type":"string","enum":["holdings","transactions","valuations","tax","summary"]},"description":"Filter by report type"},{"in":"query","name":"status","schema":{"type":"string","enum":["pending","generating","completed","failed","delivered"]},"description":"Filter by status"}],"responses":{"200":{"description":"List of reports"},"400":{"description":"Invalid request"},"500":{"description":"Server error"}}}},"/api/v1/stakeholders/{id}/reports/holdings":{"post":{"summary":"Generate holdings report for a stakeholder","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId"],"properties":{"companyId":{"type":"string","description":"Company ID"},"format":{"type":"string","enum":["pdf","excel","csv","json"],"default":"pdf"}}}}}},"responses":{"201":{"description":"Report generated successfully"},"400":{"description":"Invalid request"},"404":{"description":"Stakeholder not found"},"500":{"description":"Server error"}}}},"/api/v1/stakeholders/{id}/reports/transactions":{"post":{"summary":"Generate transaction history report for a stakeholder","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId"],"properties":{"companyId":{"type":"string","description":"Company ID"},"startDate":{"type":"string","format":"date","description":"Start date filter"},"endDate":{"type":"string","format":"date","description":"End date filter"},"format":{"type":"string","enum":["pdf","excel","csv","json"],"default":"pdf"}}}}}},"responses":{"201":{"description":"Report generated successfully"},"400":{"description":"Invalid request"},"404":{"description":"Stakeholder not found"},"500":{"description":"Server error"}}}},"/api/v1/stakeholders/{id}/reports/valuations":{"post":{"summary":"Generate valuation report for a stakeholder","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId"],"properties":{"companyId":{"type":"string","description":"Company ID"},"format":{"type":"string","enum":["pdf","excel","csv","json"],"default":"pdf"}}}}}},"responses":{"201":{"description":"Report generated successfully"},"400":{"description":"Invalid request"},"404":{"description":"Stakeholder not found"},"500":{"description":"Server error"}}}},"/api/v1/stakeholders/{id}/reports/tax":{"post":{"summary":"Generate tax document report for a stakeholder","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId","taxYear"],"properties":{"companyId":{"type":"string","description":"Company ID"},"taxYear":{"type":"integer","description":"Tax year (e.g., 2023)"},"format":{"type":"string","enum":["pdf","excel","csv","json"],"default":"pdf"}}}}}},"responses":{"201":{"description":"Report generated successfully"},"400":{"description":"Invalid request or invalid tax year"},"404":{"description":"Stakeholder not found"},"500":{"description":"Server error"}}}},"/api/v1/stakeholders/{id}/reports/schedule":{"post":{"summary":"Schedule automated report delivery","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId","reportType","schedule","recipients"],"properties":{"companyId":{"type":"string","description":"Company ID"},"reportType":{"type":"string","enum":["holdings","transactions","valuations","tax","summary"],"description":"Type of report to schedule"},"schedule":{"type":"string","description":"Cron expression (e.g., \"0 9 1 * *\" for first of month at 9 AM)"},"recipients":{"type":"array","items":{"type":"string","format":"email"},"description":"Email recipients for automated delivery"},"format":{"type":"string","enum":["pdf","excel","csv","json"],"default":"pdf"}}}}}},"responses":{"201":{"description":"Schedule created successfully"},"400":{"description":"Invalid request, schedule format, or email format"},"500":{"description":"Server error"}}}},"/api/v1/stakeholders/{id}/reports/{reportId}/email":{"post":{"summary":"Email a report to specified recipients","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"},{"in":"path","name":"reportId","required":true,"schema":{"type":"string"},"description":"Report ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string","format":"email","description":"Recipient email address"},"subject":{"type":"string","description":"Email subject"},"message":{"type":"string","description":"Email message body"}}}}}},"responses":{"200":{"description":"Email sent successfully"},"400":{"description":"Invalid request or report not ready"},"404":{"description":"Report not found"},"500":{"description":"Server error"}}}},"/api/v1/stakeholders/{id}/reports/{reportId}":{"get":{"summary":"Get a specific report by ID","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"},{"in":"path","name":"reportId","required":true,"schema":{"type":"string"},"description":"Report ID"}],"responses":{"200":{"description":"Report details"},"400":{"description":"Invalid request"},"404":{"description":"Report not found"},"500":{"description":"Server error"}}}},"/api/v1/stakeholders/{id}/reports/{reportId}/download":{"get":{"summary":"Download a report","tags":["StakeholderReports"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Stakeholder ID"},{"in":"path","name":"reportId","required":true,"schema":{"type":"string"},"description":"Report ID"}],"responses":{"200":{"description":"Download URL"},"400":{"description":"Report not ready for download"},"404":{"description":"Report not found"},"500":{"description":"Server error"}}}},"/terminations":{"post":{"summary":"Create a new termination record","tags":["Terminations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["employeeId","companyId","terminationDate","terminationType"],"properties":{"employeeId":{"type":"string"},"companyId":{"type":"string"},"terminationDate":{"type":"string","format":"date"},"terminationType":{"type":"string","enum":["voluntary","involuntary","for_cause","layoff","retirement","death","disability"]},"grants":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"201":{"description":"Termination created successfully"},"400":{"description":"Invalid request"}}},"get":{"summary":"Get all terminations for a company","tags":["Terminations"],"parameters":[{"in":"query","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"terminationType","schema":{"type":"string"}}],"responses":{"200":{"description":"List of terminations"}}}},"/terminations/calculate-vesting":{"post":{"summary":"Calculate vesting for given parameters (preview)","tags":["Terminations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grantDate","terminationDate","totalGrantedShares","vestingSchedule"]}}}},"responses":{"200":{"description":"Vesting calculation result"}}}},"/terminations/expiring-windows":{"get":{"summary":"Get terminations with expiring exercise windows","tags":["Terminations"],"parameters":[{"in":"query","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"daysUntilExpiry","schema":{"type":"integer","default":7}}],"responses":{"200":{"description":"List of terminations with expiring windows"}}}},"/terminations/{id}":{"get":{"summary":"Get a termination by ID","tags":["Terminations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Termination details"},"404":{"description":"Termination not found"}}},"put":{"summary":"Update a termination record","tags":["Terminations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Termination updated"},"404":{"description":"Termination not found"}}},"delete":{"summary":"Delete a termination record","tags":["Terminations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Termination deleted"},"404":{"description":"Termination not found"}}}},"/terminations/{id}/exercise-window":{"get":{"summary":"Get exercise window status","tags":["Terminations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Exercise window status"}}}},"/terminations/{id}/extend-window":{"post":{"summary":"Extend exercise window","tags":["Terminations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["additionalDays"],"properties":{"additionalDays":{"type":"integer"},"reason":{"type":"string"},"approvedBy":{"type":"string"}}}}}},"responses":{"200":{"description":"Exercise window extended"},"400":{"description":"Cannot extend expired window"}}}},"/terminations/{id}/exercise":{"post":{"summary":"Record share exercise","tags":["Terminations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shares","exercisePrice"],"properties":{"shares":{"type":"integer"},"exercisePrice":{"type":"number"},"fmvAtExercise":{"type":"number"}}}}}},"responses":{"200":{"description":"Exercise recorded"},"400":{"description":"Exercise window expired or insufficient shares"}}}},"/terminations/{id}/documents":{"post":{"summary":"Generate termination documents","tags":["Terminations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Documents generated"},"404":{"description":"Termination not found"}}}},"/terminations/{id}/update-status":{"post":{"summary":"Update termination status (check for expired windows)","tags":["Terminations"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Status updated"},"404":{"description":"Termination not found"}}}},"/api/v1/users/profile/photo":{"post":{"summary":"Upload user profile photo","description":"Upload a profile photo for the authenticated user. Automatically generates a 200x200px thumbnail. Maximum file size 5MB. Supported formats - JPEG, PNG, GIF, WebP.","tags":["Users"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["photo"],"properties":{"photo":{"type":"string","format":"binary","description":"Profile photo image file (JPEG, PNG, GIF, or WebP)"}}}}}},"responses":{"200":{"description":"Profile photo uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"photoUrl":{"type":"string","format":"uri","description":"Presigned URL for the uploaded photo","example":"https://storage.example.com/photos/profile-user_123-1234567890.jpg"},"thumbnailUrl":{"type":"string","format":"uri","description":"Presigned URL for the 200x200px thumbnail","example":"https://storage.example.com/photos/profile-thumb-user_123-1234567890.jpg"},"message":{"type":"string","example":"Profile photo uploaded successfully"}}}}}},"400":{"description":"Bad request - invalid file type, size, or missing file","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"File size exceeds maximum allowed size of 5MB"}}}}}},"401":{"description":"Unauthorized - authentication required"},"404":{"description":"User not found"},"500":{"description":"Internal server error"}}},"delete":{"summary":"Delete user profile photo","description":"Delete the profile photo for the authenticated user. Removes both the original photo and thumbnail from storage.","tags":["Users"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Profile photo deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Profile photo deleted successfully"}}}}}},"401":{"description":"Unauthorized - authentication required"},"404":{"description":"User not found or no profile photo to delete","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"No profile photo to delete"}}}}}},"500":{"description":"Internal server error"}}}},"/api/v1/valuations/export/requirements":{"get":{"summary":"Get export requirements checklist","tags":["409A Export"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Export requirements and data checklist"}}}},"/api/v1/valuations/export/validate":{"post":{"summary":"Validate data completeness before export","tags":["409A Export"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company_id"],"properties":{"company_id":{"type":"string","description":"Company ID to validate"}}}}}},"responses":{"200":{"description":"Validation result with completeness score"},"400":{"description":"Missing company_id"},"404":{"description":"Company not found"}}}},"/api/v1/valuations/export":{"post":{"summary":"Generate full 409A export package","tags":["409A Export"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company_id"],"properties":{"company_id":{"type":"string","description":"Company ID to export"},"effective_date":{"type":"string","format":"date","description":"Effective date for the export"},"export_format":{"type":"string","enum":["JSON"],"default":"JSON"},"include_sections":{"type":"array","items":{"type":"string"},"default":["all"]},"recipient":{"type":"object","properties":{"firm_name":{"type":"string"},"contact_email":{"type":"string"}}},"password_protect":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Export package created successfully"},"400":{"description":"Missing required fields"},"404":{"description":"Company not found"}}}},"/api/v1/valuations/export/{exportId}":{"get":{"summary":"Get export metadata by ID","tags":["409A Export"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"exportId","required":true,"schema":{"type":"string"},"description":"Export ID"}],"responses":{"200":{"description":"Export metadata"},"404":{"description":"Export not found"}}}},"/api/v1/valuations/export/{exportId}/download":{"get":{"summary":"Download export package","tags":["409A Export"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"exportId","required":true,"schema":{"type":"string"},"description":"Export ID"}],"responses":{"200":{"description":"Export download initiated"},"404":{"description":"Export not found"},"410":{"description":"Export has expired"}}}},"/api/v1/valuations/export/{companyId}/cap-table":{"get":{"summary":"Export cap table summary","tags":["409A Export"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Company ID"},{"in":"query","name":"effectiveDate","schema":{"type":"string","format":"date"},"description":"Effective date for the export"}],"responses":{"200":{"description":"Cap table export data"},"404":{"description":"Company not found"}}}},"/api/v1/valuations/export/{companyId}/financials":{"get":{"summary":"Export financial highlights","tags":["409A Export"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Company ID"},{"in":"query","name":"fiscalYear","schema":{"type":"integer"},"description":"Fiscal year for the export"}],"responses":{"200":{"description":"Financial highlights export data"},"404":{"description":"Company not found"}}}},"/api/v1/valuations/export/{companyId}/transactions":{"get":{"summary":"Export transaction history","tags":["409A Export"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Company ID"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"},"description":"Start date for transaction range"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"},"description":"End date for transaction range"}],"responses":{"200":{"description":"Transaction history export data"},"404":{"description":"Company not found"}}}},"/api/v1/valuations/latest":{"get":{"summary":"Get latest valuation for a company","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"companyId","required":true,"schema":{"type":"string"},"description":"The company ID to get the latest valuation for"}],"responses":{"200":{"description":"Latest valuation or null if none exists"},"400":{"description":"Missing companyId parameter"}}}},"/api/v1/valuations":{"post":{"summary":"Create a new 409A valuation request","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId","reason"],"properties":{"companyId":{"type":"string"},"reason":{"type":"string","enum":["annual_valuation","fundraising_round","material_event","option_grant","board_request","audit_requirement","other"]},"reasonDetails":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Valuation request created"},"400":{"description":"Invalid input"}}}},"/api/v1/valuations/expiring":{"get":{"summary":"Get valuations expiring soon","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":60},"description":"Number of days threshold"}],"responses":{"200":{"description":"List of expiring valuations"}}}},"/api/v1/valuations/process-expired":{"post":{"summary":"Process and mark expired valuations","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Expired valuations processed"}}}},"/api/v1/valuations/company/{companyId}":{"get":{"summary":"Get all valuations for a company","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of valuations"}}}},"/api/v1/valuations/company/{companyId}/current":{"get":{"summary":"Get current active valuation for a company","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current valuation"},"404":{"description":"No current valuation found"}}}},"/api/v1/valuations/company/{companyId}/history":{"get":{"summary":"Get valuation history for a company","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Valuation history"}}}},"/api/v1/valuations/company/{companyId}/summary":{"get":{"summary":"Get valuation summary for a company","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Valuation summary"}}}},"/api/v1/valuations/{valuationId}":{"get":{"summary":"Get a specific valuation","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Valuation details"},"404":{"description":"Valuation not found"}}},"put":{"summary":"Update a valuation request","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Valuation updated"},"400":{"description":"Cannot update valuation in current status"}}}},"/api/v1/valuations/{valuationId}/assign-firm":{"post":{"summary":"Assign a valuation firm","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string"},"phone":{"type":"string"}}}}}},"responses":{"200":{"description":"Firm assigned"}}}},"/api/v1/valuations/{valuationId}/receive-draft":{"post":{"summary":"Record receipt of draft valuation report","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fairMarketValue":{"type":"number"},"valuationMethod":{"type":"string","enum":["income","market","asset","hybrid","other"]},"effectiveDate":{"type":"string","format":"date"}}}}}},"responses":{"200":{"description":"Draft received"}}}},"/api/v1/valuations/{valuationId}/start-review":{"post":{"summary":"Start review of draft valuation","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Review started"}}}},"/api/v1/valuations/{valuationId}/approve":{"post":{"summary":"Approve a valuation","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Valuation approved"}}}},"/api/v1/valuations/{valuationId}/cancel":{"post":{"summary":"Cancel a valuation request","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Valuation cancelled"}}}},"/api/v1/valuations/{valuationId}/documents":{"post":{"summary":"Add a document to a valuation","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["documentId","type"],"properties":{"documentId":{"type":"string"},"type":{"type":"string","enum":["valuation_report","draft_report","supporting_data","board_approval","other"]},"name":{"type":"string"}}}}}},"responses":{"200":{"description":"Document added"}}}},"/api/v1/valuations/{valuationId}/audit-trail":{"get":{"summary":"Get complete audit trail for a valuation","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"valuationId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Complete audit trail with timeline, documents, and status history"},"404":{"description":"Valuation not found"}}}},"/api/v1/valuations/company/{companyId}/compliance/irs":{"get":{"summary":"Generate IRS 409A compliance report","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"fiscalYear","schema":{"type":"integer"},"description":"Fiscal year for the report (defaults to current year)"}],"responses":{"200":{"description":"IRS compliance report with requirement checklist"}}}},"/api/v1/valuations/company/{companyId}/compliance/gaap":{"get":{"summary":"Generate GAAP ASC 718 compliance report","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"fiscalYear","schema":{"type":"integer"},"description":"Fiscal year for the report (defaults to current year)"}],"responses":{"200":{"description":"GAAP compliance report"}}}},"/api/v1/valuations/company/{companyId}/audit-report":{"get":{"summary":"Generate comprehensive audit report","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"fiscalYear","schema":{"type":"integer"}},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"}},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Comprehensive audit report with IRS, GAAP compliance and history"}}}},"/api/v1/valuations/company/{companyId}/audit-export":{"get":{"summary":"Export audit data for external systems","tags":["409A Valuations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"format","schema":{"type":"string","enum":["json"]},"description":"Export format (defaults to json)"}],"responses":{"200":{"description":"Exported audit data"}}}},"/api/v1/valuation-partners":{"post":{"summary":"Create a new valuation partner","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"companyId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["valuation_firm","accounting_firm","independent_appraiser","consulting_firm"]},"contacts":{"type":"array"},"qualifications":{"type":"object"}}}}}},"responses":{"201":{"description":"Partner created"}}},"get":{"summary":"Get all valuation partners","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"companyId","schema":{"type":"string"}},{"in":"query","name":"type","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}}],"responses":{"200":{"description":"List of partners"}}}},"/api/v1/valuation-partners/search":{"get":{"summary":"Search valuation partners","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"type","schema":{"type":"string"}},{"in":"query","name":"minRating","schema":{"type":"number"}},{"in":"query","name":"specialization","schema":{"type":"string"}},{"in":"query","name":"maxTurnaround","schema":{"type":"integer"}}],"responses":{"200":{"description":"Search results"}}}},"/api/v1/valuation-partners/company/{companyId}/active":{"get":{"summary":"Get active partners for a company","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of active partners"}}}},"/api/v1/valuation-partners/{partnerId}":{"get":{"summary":"Get a specific partner","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Partner details"}}},"put":{"summary":"Update a partner","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Partner updated"}}}},"/api/v1/valuation-partners/{partnerId}/summary":{"get":{"summary":"Get partner summary with metrics","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Partner summary"}}}},"/api/v1/valuation-partners/{partnerId}/activate":{"post":{"summary":"Activate a partner","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Partner activated"}}}},"/api/v1/valuation-partners/{partnerId}/deactivate":{"post":{"summary":"Deactivate a partner","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Partner deactivated"}}}},"/api/v1/valuation-partners/{partnerId}/contacts":{"post":{"summary":"Add contact to partner","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"title":{"type":"string"}}}}}},"responses":{"200":{"description":"Contact added"}}}},"/api/v1/valuation-partners/{partnerId}/contacts/{contactId}/primary":{"post":{"summary":"Set primary contact","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}},{"in":"path","name":"contactId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Primary contact set"}}}},"/api/v1/valuation-partners/{partnerId}/calls":{"post":{"summary":"Schedule a call with partner","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","scheduledAt"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"duration":{"type":"integer"},"participants":{"type":"array"},"agenda":{"type":"string"}}}}}},"responses":{"201":{"description":"Call scheduled"}}}},"/api/v1/valuation-partners/{partnerId}/calls/upcoming":{"get":{"summary":"Get upcoming calls","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of upcoming calls"}}}},"/api/v1/valuation-partners/{partnerId}/calls/{callId}/status":{"put":{"summary":"Update call status","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}},{"in":"path","name":"callId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["confirmed","completed","cancelled","rescheduled"]},"meetingLink":{"type":"string"},"notes":{"type":"string"},"reason":{"type":"string"},"newTime":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Call status updated"}}}},"/api/v1/valuation-partners/{partnerId}/communications":{"post":{"summary":"Add communication record","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["email","call","meeting","message","document_shared"]},"subject":{"type":"string"},"content":{"type":"string"},"outcome":{"type":"string"}}}}}},"responses":{"200":{"description":"Communication added"}}},"get":{"summary":"Get communication history","tags":["Valuation Partners"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"partnerId","required":true,"schema":{"type":"string"}},{"in":"query","name":"type","schema":{"type":"string"}}],"responses":{"200":{"description":"Communication history"}}}},"/api/analytics/dashboard":{"get":{"tags":["Analytics"],"summary":"Get dashboard analytics","description":"Returns summarized analytics data for dashboard views","operationId":"getDashboardAnalytics","parameters":[{"name":"companyId","in":"query","description":"Filter by company ID","schema":{"type":"string"}},{"name":"period","in":"query","description":"Time period for analytics","schema":{"type":"string","enum":["day","week","month","quarter","year","custom"],"default":"month"}},{"name":"startDate","in":"query","description":"Start date for custom period (ISO format)","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"End date for custom period (ISO format)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Dashboard analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"investments":{"type":"object","description":"Investment analytics","properties":{"total":{"type":"number","description":"Total investment amount"},"count":{"type":"integer","description":"Number of investments"},"byType":{"type":"object","description":"Breakdown by investment type","additionalProperties":{"type":"number"}},"trend":{"type":"array","description":"Time-series data for investment trends","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"amount":{"type":"number"}}}}}},"shareholderActivity":{"type":"object","description":"Shareholder activity metrics","properties":{"totalShareholders":{"type":"integer","description":"Total number of shareholders"},"newShareholders":{"type":"integer","description":"New shareholders in the period"},"activePercentage":{"type":"number","description":"Percentage of active shareholders"},"distribution":{"type":"object","description":"Distribution by investor type","additionalProperties":{"type":"integer"}}}},"equityMetrics":{"type":"object","description":"Equity-related metrics","properties":{"outstandingShares":{"type":"number","description":"Total outstanding shares"},"fullyDilutedShares":{"type":"number","description":"Fully diluted shares"},"byShareClass":{"type":"array","description":"Breakdown by share class","items":{"type":"object","properties":{"shareClass":{"type":"string"},"shares":{"type":"number"},"percentage":{"type":"number"}}}}}},"documentActivity":{"type":"object","description":"Document activity metrics","properties":{"totalDocuments":{"type":"integer","description":"Total number of documents"},"newDocuments":{"type":"integer","description":"New documents in the period"},"byType":{"type":"object","description":"Breakdown by document type","additionalProperties":{"type":"integer"}}}},"complianceStatus":{"type":"object","description":"Compliance status metrics","properties":{"compliantPercentage":{"type":"number","description":"Percentage of compliant entities"},"pendingReview":{"type":"integer","description":"Number of entities pending review"},"byCheckType":{"type":"object","description":"Compliance by check type","additionalProperties":{"type":"object","properties":{"passed":{"type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/analytics/investments":{"get":{"tags":["Analytics"],"summary":"Get investment analytics","description":"Returns detailed analytics for investments","operationId":"getInvestmentAnalytics","parameters":[{"name":"companyId","in":"query","description":"Filter by company ID","schema":{"type":"string"}},{"name":"period","in":"query","description":"Time period for analytics","schema":{"type":"string","enum":["day","week","month","quarter","year","custom"],"default":"month"}},{"name":"startDate","in":"query","description":"Start date for custom period (ISO format)","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"End date for custom period (ISO format)","schema":{"type":"string","format":"date"}},{"name":"groupBy","in":"query","description":"Group results by dimension","schema":{"type":"string","enum":["type","status","investor","date"],"default":"date"}}],"responses":{"200":{"description":"Investment analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","description":"Summary metrics","properties":{"totalAmount":{"type":"number","description":"Total investment amount"},"totalCount":{"type":"integer","description":"Total number of investments"},"averageAmount":{"type":"number","description":"Average investment amount"},"medianAmount":{"type":"number","description":"Median investment amount"}}},"byType":{"type":"array","description":"Breakdown by investment type","items":{"type":"object","properties":{"type":{"type":"string","description":"Investment type"},"amount":{"type":"number","description":"Total amount"},"count":{"type":"integer","description":"Number of investments"},"percentage":{"type":"number","description":"Percentage of total"}}}},"byStatus":{"type":"array","description":"Breakdown by investment status","items":{"type":"object","properties":{"status":{"type":"string","description":"Investment status"},"amount":{"type":"number","description":"Total amount"},"count":{"type":"integer","description":"Number of investments"},"percentage":{"type":"number","description":"Percentage of total"}}}},"timeSeries":{"type":"array","description":"Time-series data","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"amount":{"type":"number"},"count":{"type":"integer"}}}},"topInvestors":{"type":"array","description":"Top investors by amount","items":{"type":"object","properties":{"investorId":{"type":"string"},"investorName":{"type":"string"},"amount":{"type":"number"},"count":{"type":"integer"},"percentage":{"type":"number"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/analytics/equity":{"get":{"tags":["Analytics"],"summary":"Get equity analytics","description":"Returns detailed analytics for equity ownership and plans","operationId":"getEquityAnalytics","parameters":[{"name":"companyId","in":"query","description":"Filter by company ID","schema":{"type":"string"}},{"name":"includeHistorical","in":"query","description":"Include historical equity data","schema":{"type":"boolean","default":false}},{"name":"asOfDate","in":"query","description":"Calculate equity as of this date (ISO format)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Equity analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","description":"Summary metrics","properties":{"authorizedShares":{"type":"number","description":"Total authorized shares"},"issuedShares":{"type":"number","description":"Total issued shares"},"reservedShares":{"type":"number","description":"Total reserved shares"},"availableShares":{"type":"number","description":"Available shares"},"fullyDilutedShares":{"type":"number","description":"Fully diluted shares"}}},"capitalizationTable":{"type":"object","description":"Capitalization table data","properties":{"shareClasses":{"type":"array","description":"Share classes","items":{"type":"object","properties":{"shareClassId":{"type":"string"},"name":{"type":"string"},"issuedShares":{"type":"number"},"percentageOwnership":{"type":"number"}}}},"shareholders":{"type":"array","description":"Shareholders","items":{"type":"object","properties":{"shareholderId":{"type":"string"},"name":{"type":"string"},"shareholderType":{"type":"string"},"shares":{"type":"number"},"percentageOwnership":{"type":"number"},"shareClasses":{"type":"array","items":{"type":"object","properties":{"shareClassId":{"type":"string"},"name":{"type":"string"},"shares":{"type":"number"}}}}}}}}},"equityPlans":{"type":"array","description":"Equity plans analytics","items":{"type":"object","properties":{"planId":{"type":"string"},"name":{"type":"string"},"totalShares":{"type":"number"},"allocatedShares":{"type":"number"},"availableShares":{"type":"number"},"percentageAllocated":{"type":"number"}}}},"dilutionAnalysis":{"type":"object","description":"Dilution analysis","properties":{"currentDilution":{"type":"object","additionalProperties":{"type":"number"}},"projectedDilution":{"type":"object","additionalProperties":{"type":"number"}}}},"valuation":{"type":"object","description":"Valuation metrics","properties":{"currentValuation":{"type":"number","description":"Current company valuation"},"sharePrice":{"type":"number","description":"Current share price"},"historicalValuations":{"type":"array","description":"Historical valuations","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"valuation":{"type":"number"},"sharePrice":{"type":"number"},"event":{"type":"string"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/analytics/compliance":{"get":{"tags":["Analytics"],"summary":"Get compliance analytics","description":"Returns analytics for compliance activities and status","operationId":"getComplianceAnalytics","parameters":[{"name":"companyId","in":"query","description":"Filter by company ID","schema":{"type":"string"}},{"name":"period","in":"query","description":"Time period for analytics","schema":{"type":"string","enum":["day","week","month","quarter","year","custom"],"default":"month"}},{"name":"startDate","in":"query","description":"Start date for custom period (ISO format)","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"End date for custom period (ISO format)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Compliance analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","description":"Summary metrics","properties":{"totalChecks":{"type":"integer","description":"Total compliance checks"},"passedChecks":{"type":"integer","description":"Number of passed checks"},"failedChecks":{"type":"integer","description":"Number of failed checks"},"pendingChecks":{"type":"integer","description":"Number of pending checks"},"complianceRate":{"type":"number","description":"Overall compliance rate"}}},"byCheckType":{"type":"array","description":"Breakdown by check type","items":{"type":"object","properties":{"checkType":{"type":"string","description":"Type of compliance check"},"total":{"type":"integer","description":"Total checks"},"passed":{"type":"integer","description":"Passed checks"},"failed":{"type":"integer","description":"Failed checks"},"pending":{"type":"integer","description":"Pending checks"},"complianceRate":{"type":"number","description":"Compliance rate for this type"}}}},"byEntityType":{"type":"array","description":"Breakdown by entity type","items":{"type":"object","properties":{"entityType":{"type":"string","description":"Type of entity"},"total":{"type":"integer","description":"Total entities"},"compliant":{"type":"integer","description":"Compliant entities"},"nonCompliant":{"type":"integer","description":"Non-compliant entities"},"pending":{"type":"integer","description":"Entities with pending compliance"},"complianceRate":{"type":"number","description":"Compliance rate for this entity type"}}}},"timeSeries":{"type":"array","description":"Time-series compliance data","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"complianceRate":{"type":"number"},"checkCount":{"type":"integer"}}}},"riskAnalysis":{"type":"object","description":"Risk analysis","properties":{"highRiskEntities":{"type":"integer","description":"Number of high-risk entities"},"mediumRiskEntities":{"type":"integer","description":"Number of medium-risk entities"},"lowRiskEntities":{"type":"integer","description":"Number of low-risk entities"},"riskDistribution":{"type":"object","additionalProperties":{"type":"integer"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/analytics/activity":{"get":{"tags":["Analytics"],"summary":"Get user activity analytics","description":"Returns analytics for user activity in the system","operationId":"getActivityAnalytics","parameters":[{"name":"companyId","in":"query","description":"Filter by company ID","schema":{"type":"string"}},{"name":"period","in":"query","description":"Time period for analytics","schema":{"type":"string","enum":["day","week","month","quarter","year","custom"],"default":"month"}},{"name":"startDate","in":"query","description":"Start date for custom period (ISO format)","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"End date for custom period (ISO format)","schema":{"type":"string","format":"date"}},{"name":"groupBy","in":"query","description":"Group results by dimension","schema":{"type":"string","enum":["user","action","resource","date"],"default":"date"}}],"responses":{"200":{"description":"Activity analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","description":"Summary metrics","properties":{"totalActivity":{"type":"integer","description":"Total activity count"},"uniqueUsers":{"type":"integer","description":"Number of unique active users"},"averageActivitiesPerUser":{"type":"number","description":"Average activities per user"},"mostActiveDay":{"type":"string","format":"date","description":"Most active day"}}},"byActionType":{"type":"array","description":"Breakdown by action type","items":{"type":"object","properties":{"action":{"type":"string","description":"Action type"},"count":{"type":"integer","description":"Number of actions"},"percentage":{"type":"number","description":"Percentage of total"}}}},"byResource":{"type":"array","description":"Breakdown by resource","items":{"type":"object","properties":{"resource":{"type":"string","description":"Resource type"},"count":{"type":"integer","description":"Number of activities"},"percentage":{"type":"number","description":"Percentage of total"}}}},"topUsers":{"type":"array","description":"Most active users","items":{"type":"object","properties":{"userId":{"type":"string"},"userName":{"type":"string"},"activityCount":{"type":"integer"},"lastActive":{"type":"string","format":"date-time"}}}},"timeSeries":{"type":"array","description":"Time-series activity data","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"count":{"type":"integer"},"uniqueUsers":{"type":"integer"}}}},"userEngagement":{"type":"object","description":"User engagement metrics","properties":{"dailyActiveUsers":{"type":"integer"},"weeklyActiveUsers":{"type":"integer"},"monthlyActiveUsers":{"type":"integer"},"retentionRate":{"type":"number","description":"User retention rate"},"averageSessionDuration":{"type":"number","description":"Average session duration in minutes"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/analytics/export":{"post":{"tags":["Analytics"],"summary":"Export analytics data","description":"Exports analytics data in various formats","operationId":"exportAnalyticsData","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dataType","format"],"properties":{"dataType":{"type":"string","enum":["investments","equity","compliance","activity","dashboard"],"description":"Type of data to export"},"format":{"type":"string","enum":["csv","excel","pdf","json"],"description":"Export format"},"parameters":{"type":"object","description":"Parameters for the data query","properties":{"companyId":{"type":"string"},"period":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"includeHistorical":{"type":"boolean"},"groupBy":{"type":"string"}},"additionalProperties":true}}}}}},"responses":{"200":{"description":"Analytics data exported successfully","content":{"application/json":{"schema":{"type":"object","properties":{"downloadUrl":{"type":"string","description":"URL to download the exported data"},"expiresAt":{"type":"string","format":"date-time","description":"Expiration time for the download URL"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"openapi":{"0":"3","1":".","2":"0","3":".","4":"0"},"info":{"title":"OpenCap SPV API","description":"Special Purpose Vehicle Management Endpoints","version":"1.0.0"},"/auth/oauth-login":{"post":{"tags":["Authentication"],"summary":"OAuth login","description":"Authenticate a user with OAuth provider token","operationId":"oauthLogin","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["idToken","provider"],"properties":{"idToken":{"type":"string","description":"OAuth ID token"},"provider":{"type":"string","enum":["google","github","microsoft"],"description":"OAuth provider"}}}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"token":{"type":"string"},"isNewUser":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/auth/logout":{"post":{"tags":["Authentication"],"summary":"Logout user","description":"Invalidate the user's current access token","operationId":"logoutUser","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Logout successful","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/auth/token/refresh":{"post":{"tags":["Authentication"],"summary":"Refresh access token","description":"Get a new access token using refresh token","operationId":"refreshToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refreshToken"],"properties":{"refreshToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Token refreshed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Invalid or expired refresh token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth/profile":{"get":{"tags":["User Management"],"summary":"Get user profile","description":"Get the current user's profile information","operationId":"getUserProfile","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"User profile retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"tags":["User Management"],"summary":"Update user profile","description":"Update the current user's profile information","operationId":"updateUserProfile","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"profileImage":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Profile updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/auth/password/reset-request":{"post":{"tags":["Authentication"],"summary":"Request password reset","description":"Request a password reset link via email","operationId":"requestPasswordReset","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Password reset email sent","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/auth/password/verify-token":{"post":{"tags":["Authentication"],"summary":"Verify reset token","description":"Verify that a password reset token is valid","operationId":"verifyResetToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Token is valid","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"}}}}}},"400":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"message":{"type":"string"}}}}}}}}},"/auth/password/reset":{"post":{"tags":["Authentication"],"summary":"Reset password","description":"Reset a user's password using a valid token","operationId":"resetPassword","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","password"],"properties":{"token":{"type":"string"},"password":{"type":"string","format":"password"}}}}}},"responses":{"200":{"description":"Password reset successful","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/companies":{"get":{"tags":["Company Management"],"summary":"Get all companies","description":"Returns a paginated list of all companies","operationId":"getAllCompanies","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of companies","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Company Management"],"summary":"Create a new company","description":"Creates a new company in the system","operationId":"createCompany","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","legalName","incorporationState"],"properties":{"name":{"type":"string","description":"Common name of the company"},"legalName":{"type":"string","description":"Legal registered name of the company"},"incorporationState":{"type":"string","description":"State where the company is incorporated"},"incorporationDate":{"type":"string","format":"date","description":"Date of incorporation"},"companyType":{"type":"string","enum":["C-Corp","S-Corp","LLC","Partnership"],"description":"Legal structure of the company"},"ein":{"type":"string","description":"Employer Identification Number"},"status":{"type":"string","enum":["active","inactive","pending"],"description":"Current company status"},"address":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"country":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Company created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/companies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["Company Management"],"summary":"Get company by ID","description":"Returns a single company by its ID","operationId":"getCompanyById","responses":{"200":{"description":"Company found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Company Management"],"summary":"Update company","description":"Updates an existing company","operationId":"updateCompany","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Common name of the company"},"legalName":{"type":"string","description":"Legal registered name of the company"},"incorporationState":{"type":"string","description":"State where the company is incorporated"},"incorporationDate":{"type":"string","format":"date","description":"Date of incorporation"},"companyType":{"type":"string","enum":["C-Corp","S-Corp","LLC","Partnership"],"description":"Legal structure of the company"},"ein":{"type":"string","description":"Employer Identification Number"},"status":{"type":"string","enum":["active","inactive","pending"],"description":"Current company status"},"address":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"country":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Company updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Company Management"],"summary":"Delete company","description":"Deletes a company by ID","operationId":"deleteCompany","responses":{"204":{"description":"Company deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/companies/{id}/users":{"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["Company Management"],"summary":"Get company users","description":"Returns all users associated with a specific company","operationId":"getCompanyUsers","responses":{"200":{"description":"Company users found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/companies/{id}/metrics":{"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["Company Management"],"summary":"Get company metrics","description":"Returns key performance metrics and analytics for a company","operationId":"getCompanyMetrics","parameters":[{"name":"startDate","in":"query","description":"Start date for metrics calculation","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"End date for metrics calculation","schema":{"type":"string","format":"date"}},{"name":"type","in":"query","description":"Type of metrics to retrieve","schema":{"type":"string","enum":["financial","operational","compliance","all"]}}],"responses":{"200":{"description":"Company metrics found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"description":"Company metrics data"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/compliance-checks":{"get":{"tags":["Compliance"],"summary":"Get all compliance checks","description":"Returns a paginated list of compliance checks","operationId":"getAllComplianceChecks","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of compliance checks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Compliance check unique identifier"},"companyId":{"type":"string","description":"Associated company ID"},"checkType":{"type":"string","enum":["kyc","aml","accredited_investor","reg_cf","reg_d","tax_compliance"],"description":"Type of compliance check"},"entityId":{"type":"string","description":"ID of the entity being checked (user, investor, etc)"},"entityType":{"type":"string","enum":["user","investor","company","spv"],"description":"Type of entity being checked"},"status":{"type":"string","enum":["pending","passed","failed","requires_review"],"description":"Status of the compliance check"},"results":{"type":"object","description":"Detailed results of the compliance check"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Compliance"],"summary":"Create a new compliance check","description":"Initiates a new compliance check for an entity","operationId":"createComplianceCheck","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["checkType","entityId","entityType"],"properties":{"companyId":{"type":"string","description":"Associated company ID"},"checkType":{"type":"string","enum":["kyc","aml","accredited_investor","reg_cf","reg_d","tax_compliance"],"description":"Type of compliance check"},"entityId":{"type":"string","description":"ID of the entity to check"},"entityType":{"type":"string","enum":["user","investor","company","spv"],"description":"Type of entity to check"},"additionalData":{"type":"object","description":"Additional data required for the check","additionalProperties":true}}}}}},"responses":{"201":{"description":"Compliance check initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Compliance check unique identifier"},"companyId":{"type":"string","description":"Associated company ID"},"checkType":{"type":"string","enum":["kyc","aml","accredited_investor","reg_cf","reg_d","tax_compliance"],"description":"Type of compliance check"},"entityId":{"type":"string","description":"ID of the entity being checked"},"entityType":{"type":"string","enum":["user","investor","company","spv"],"description":"Type of entity being checked"},"status":{"type":"string","enum":["pending","passed","failed","requires_review"],"description":"Status of the compliance check"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/compliance-checks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Compliance check ID","schema":{"type":"string"}}],"get":{"tags":["Compliance"],"summary":"Get compliance check by ID","description":"Returns a single compliance check by its ID","operationId":"getComplianceCheckById","responses":{"200":{"description":"Compliance check found","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Compliance check unique identifier"},"companyId":{"type":"string","description":"Associated company ID"},"checkType":{"type":"string","enum":["kyc","aml","accredited_investor","reg_cf","reg_d","tax_compliance"],"description":"Type of compliance check"},"entityId":{"type":"string","description":"ID of the entity being checked"},"entityType":{"type":"string","enum":["user","investor","company","spv"],"description":"Type of entity being checked"},"status":{"type":"string","enum":["pending","passed","failed","requires_review"],"description":"Status of the compliance check"},"results":{"type":"object","description":"Detailed results of the compliance check"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Compliance"],"summary":"Update compliance check","description":"Updates an existing compliance check (e.g., to review or manually approve)","operationId":"updateComplianceCheck","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","passed","failed","requires_review"],"description":"Status of the compliance check"},"reviewNotes":{"type":"string","description":"Notes from compliance review"},"reviewedBy":{"type":"string","description":"ID of the user who reviewed this check"},"additionalData":{"type":"object","description":"Additional data to add to the check","additionalProperties":true}}}}}},"responses":{"200":{"description":"Compliance check updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Compliance check unique identifier"},"status":{"type":"string","enum":["pending","passed","failed","requires_review"],"description":"Status of the compliance check"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Compliance"],"summary":"Delete compliance check","description":"Deletes a compliance check by ID","operationId":"deleteComplianceCheck","responses":{"204":{"description":"Compliance check deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/compliance-checks/entity/{entityType}/{entityId}":{"parameters":[{"name":"entityType","in":"path","required":true,"description":"Type of entity (user, investor, company, spv)","schema":{"type":"string","enum":["user","investor","company","spv"]}},{"name":"entityId","in":"path","required":true,"description":"Entity ID","schema":{"type":"string"}}],"get":{"tags":["Compliance"],"summary":"Get compliance checks by entity","description":"Returns all compliance checks for a specific entity","operationId":"getComplianceChecksByEntity","responses":{"200":{"description":"Compliance checks found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Compliance check unique identifier"},"checkType":{"type":"string","enum":["kyc","aml","accredited_investor","reg_cf","reg_d","tax_compliance"],"description":"Type of compliance check"},"status":{"type":"string","enum":["pending","passed","failed","requires_review"],"description":"Status of the compliance check"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/compliance-checks/bulk-verify":{"post":{"tags":["Compliance"],"summary":"Bulk verify compliance","description":"Performs bulk compliance verification for multiple entities","operationId":"bulkVerifyCompliance","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entities","checkTypes"],"properties":{"entities":{"type":"array","description":"Entities to check","items":{"type":"object","required":["entityId","entityType"],"properties":{"entityId":{"type":"string","description":"ID of the entity to check"},"entityType":{"type":"string","enum":["user","investor","company","spv"],"description":"Type of entity to check"}}}},"checkTypes":{"type":"array","description":"Types of compliance checks to perform","items":{"type":"string","enum":["kyc","aml","accredited_investor","reg_cf","reg_d","tax_compliance"]}},"companyId":{"type":"string","description":"Associated company ID"}}}}}},"responses":{"200":{"description":"Bulk compliance checks initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"batchId":{"type":"string","description":"Batch ID for the bulk operation"},"totalChecks":{"type":"integer","description":"Total number of checks initiated"},"entities":{"type":"array","description":"List of entities with check IDs","items":{"type":"object","properties":{"entityId":{"type":"string","description":"Entity ID"},"entityType":{"type":"string","description":"Entity type"},"checkIds":{"type":"array","description":"IDs of initiated checks","items":{"type":"string"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/compliance-checks/batch/{batchId}":{"parameters":[{"name":"batchId","in":"path","required":true,"description":"Batch ID for bulk compliance checks","schema":{"type":"string"}}],"get":{"tags":["Compliance"],"summary":"Get compliance check batch status","description":"Returns the status of a batch of compliance checks","operationId":"getComplianceCheckBatchStatus","responses":{"200":{"description":"Batch status found","content":{"application/json":{"schema":{"type":"object","properties":{"batchId":{"type":"string","description":"Batch ID for the bulk operation"},"status":{"type":"string","enum":["in_progress","completed","failed"],"description":"Overall batch status"},"totalChecks":{"type":"integer","description":"Total number of checks in the batch"},"completed":{"type":"integer","description":"Number of completed checks"},"passed":{"type":"integer","description":"Number of passed checks"},"failed":{"type":"integer","description":"Number of failed checks"},"requiresReview":{"type":"integer","description":"Number of checks requiring review"},"results":{"type":"array","description":"Detailed results for each entity","items":{"type":"object","properties":{"entityId":{"type":"string","description":"Entity ID"},"entityType":{"type":"string","description":"Entity type"},"checks":{"type":"array","description":"Check results","items":{"type":"object","properties":{"checkId":{"type":"string","description":"Check ID"},"checkType":{"type":"string","description":"Type of check"},"status":{"type":"string","description":"Status of check"}}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/documents/{id}":{"get":{"tags":["Document Management"],"summary":"Get document by ID","description":"Retrieve details of a specific document","operationId":"getDocumentById","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Document ID"}],"responses":{"200":{"description":"Document details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"put":{"tags":["Document Management"],"summary":"Update document metadata","description":"Update metadata of a specific document","operationId":"updateDocument","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Document ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Document name"},"type":{"type":"string","enum":["contract","report","legal","tax","other"],"description":"Document type"},"description":{"type":"string","description":"Document description"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags to categorize the document"},"entityId":{"type":"string","description":"ID of the related entity"},"entityType":{"type":"string","enum":["company","spv","investor","employee","other"],"description":"Type of the related entity"}}}}}},"responses":{"200":{"description":"Document updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"tags":["Document Management"],"summary":"Delete document","description":"Delete a specific document","operationId":"deleteDocument","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Document ID"}],"responses":{"200":{"description":"Document deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"id":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/documents/{id}/download":{"get":{"tags":["Document Management"],"summary":"Download document","description":"Download the document file","operationId":"downloadDocument","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Document ID"}],"responses":{"200":{"description":"Document file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/document-embeddings":{"post":{"tags":["Document Management"],"summary":"Generate document embeddings","description":"Generate vector embeddings for a document to enable semantic search","operationId":"generateDocumentEmbeddings","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["documentId"],"properties":{"documentId":{"type":"string","description":"ID of the document to generate embeddings for"},"forceRegenerate":{"type":"boolean","default":false,"description":"Force regeneration of existing embeddings"}}}}}},"responses":{"200":{"description":"Embeddings generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string"},"embeddingCount":{"type":"integer"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/document-embeddings/search":{"post":{"tags":["Document Management"],"summary":"Semantic search across documents","description":"Search for documents using semantic similarity","operationId":"searchDocuments","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Search query"},"limit":{"type":"integer","default":10,"description":"Maximum number of results to return"},"filters":{"type":"object","properties":{"documentTypes":{"type":"array","items":{"type":"string","enum":["contract","report","legal","tax","other"]},"description":"Filter by document types"},"tags":{"type":"array","items":{"type":"string"},"description":"Filter by tags"},"entityTypes":{"type":"array","items":{"type":"string","enum":["company","spv","investor","employee","other"]},"description":"Filter by entity types"}}}}}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"document":{"$ref":"#/components/schemas/Document"},"score":{"type":"number","format":"float","description":"Similarity score"},"relevantText":{"type":"string","description":"Relevant text excerpt"}}}},"total":{"type":"integer","description":"Total number of results"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/employees":{"get":{"tags":["Employee Management"],"summary":"Get all employees","description":"Returns a paginated list of all employees","operationId":"getAllEmployees","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of employees","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Employee unique identifier"},"userId":{"type":"string","description":"Associated user ID"},"companyId":{"type":"string","description":"Associated company ID"},"firstName":{"type":"string","description":"Employee first name"},"lastName":{"type":"string","description":"Employee last name"},"email":{"type":"string","format":"email","description":"Employee email address"},"title":{"type":"string","description":"Job title"},"department":{"type":"string","description":"Department"},"hireDate":{"type":"string","format":"date","description":"Date of hire"},"status":{"type":"string","enum":["active","terminated","on_leave"],"description":"Current employment status"},"terminationDate":{"type":"string","format":"date","description":"Date of termination (if applicable)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Employee Management"],"summary":"Create a new employee","description":"Creates a new employee record in the system","operationId":"createEmployee","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId","firstName","lastName","email"],"properties":{"companyId":{"type":"string","description":"Associated company ID"},"userId":{"type":"string","description":"Associated user ID (if exists)"},"firstName":{"type":"string","description":"Employee first name"},"lastName":{"type":"string","description":"Employee last name"},"email":{"type":"string","format":"email","description":"Employee email address"},"title":{"type":"string","description":"Job title"},"department":{"type":"string","description":"Department"},"hireDate":{"type":"string","format":"date","description":"Date of hire"},"status":{"type":"string","enum":["active","terminated","on_leave"],"description":"Current employment status","default":"active"}}}}}},"responses":{"201":{"description":"Employee created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Employee unique identifier"},"userId":{"type":"string","description":"Associated user ID"},"companyId":{"type":"string","description":"Associated company ID"},"firstName":{"type":"string","description":"Employee first name"},"lastName":{"type":"string","description":"Employee last name"},"email":{"type":"string","format":"email","description":"Employee email address"},"title":{"type":"string","description":"Job title"},"department":{"type":"string","description":"Department"},"hireDate":{"type":"string","format":"date","description":"Date of hire"},"status":{"type":"string","enum":["active","terminated","on_leave"],"description":"Current employment status"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/employees/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Employee ID","schema":{"type":"string"}}],"get":{"tags":["Employee Management"],"summary":"Get employee by ID","description":"Returns a single employee by their ID","operationId":"getEmployeeById","responses":{"200":{"description":"Employee found","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Employee unique identifier"},"userId":{"type":"string","description":"Associated user ID"},"companyId":{"type":"string","description":"Associated company ID"},"firstName":{"type":"string","description":"Employee first name"},"lastName":{"type":"string","description":"Employee last name"},"email":{"type":"string","format":"email","description":"Employee email address"},"title":{"type":"string","description":"Job title"},"department":{"type":"string","description":"Department"},"hireDate":{"type":"string","format":"date","description":"Date of hire"},"status":{"type":"string","enum":["active","terminated","on_leave"],"description":"Current employment status"},"terminationDate":{"type":"string","format":"date","description":"Date of termination (if applicable)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Employee Management"],"summary":"Update employee","description":"Updates an existing employee record","operationId":"updateEmployee","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","description":"Employee first name"},"lastName":{"type":"string","description":"Employee last name"},"email":{"type":"string","format":"email","description":"Employee email address"},"title":{"type":"string","description":"Job title"},"department":{"type":"string","description":"Department"},"hireDate":{"type":"string","format":"date","description":"Date of hire"},"status":{"type":"string","enum":["active","terminated","on_leave"],"description":"Current employment status"},"terminationDate":{"type":"string","format":"date","description":"Date of termination (if applicable)"}}}}}},"responses":{"200":{"description":"Employee updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Employee unique identifier"},"userId":{"type":"string","description":"Associated user ID"},"companyId":{"type":"string","description":"Associated company ID"},"firstName":{"type":"string","description":"Employee first name"},"lastName":{"type":"string","description":"Employee last name"},"email":{"type":"string","format":"email","description":"Employee email address"},"title":{"type":"string","description":"Job title"},"department":{"type":"string","description":"Department"},"hireDate":{"type":"string","format":"date","description":"Date of hire"},"status":{"type":"string","enum":["active","terminated","on_leave"],"description":"Current employment status"},"terminationDate":{"type":"string","format":"date","description":"Date of termination (if applicable)"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Employee Management"],"summary":"Delete employee","description":"Deletes an employee record by ID","operationId":"deleteEmployee","responses":{"204":{"description":"Employee deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/employees/company/{companyId}":{"parameters":[{"name":"companyId","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["Employee Management"],"summary":"Get employees by company","description":"Returns all employees for a specific company","operationId":"getEmployeesByCompany","responses":{"200":{"description":"Employees found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Employee unique identifier"},"firstName":{"type":"string","description":"Employee first name"},"lastName":{"type":"string","description":"Employee last name"},"email":{"type":"string","format":"email","description":"Employee email address"},"title":{"type":"string","description":"Job title"},"department":{"type":"string","description":"Department"},"status":{"type":"string","enum":["active","terminated","on_leave"],"description":"Current employment status"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/employees/{id}/equity":{"parameters":[{"name":"id","in":"path","required":true,"description":"Employee ID","schema":{"type":"string"}}],"get":{"tags":["Employee Management"],"summary":"Get employee equity grants","description":"Returns all equity grants for a specific employee","operationId":"getEmployeeEquityGrants","responses":{"200":{"description":"Employee equity grants found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Grant ID"},"planId":{"type":"string","description":"Equity plan ID"},"planName":{"type":"string","description":"Equity plan name"},"grantDate":{"type":"string","format":"date","description":"Date the grant was issued"},"sharesGranted":{"type":"number","description":"Number of shares granted"},"vestingSchedule":{"type":"object","description":"Vesting schedule details"},"status":{"type":"string","enum":["active","cancelled","exercised"],"description":"Grant status"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/equityPlans":{"get":{"tags":["Equity Plans"],"summary":"Get all equity plans","description":"Returns a paginated list of all equity plans","operationId":"getAllEquityPlans","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of equity plans","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Unique identifier for the equity plan"},"name":{"type":"string","description":"Plan name"},"companyId":{"type":"string","description":"Associated company ID"},"planType":{"type":"string","enum":["ISO","NSO","RSU","SAR","PSU"],"description":"Type of equity plan"},"shareClassId":{"type":"string","description":"Associated share class ID"},"totalShares":{"type":"number","description":"Total shares allocated to this plan"},"availableShares":{"type":"number","description":"Remaining shares available for grants"},"startDate":{"type":"string","format":"date","description":"Plan start date"},"expirationDate":{"type":"string","format":"date","description":"Plan expiration date"},"status":{"type":"string","enum":["active","expired","terminated"],"description":"Current plan status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Equity Plans"],"summary":"Create a new equity plan","description":"Creates a new equity plan in the system","operationId":"createEquityPlan","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","companyId","planType","shareClassId","totalShares"],"properties":{"name":{"type":"string","description":"Plan name"},"companyId":{"type":"string","description":"Associated company ID"},"planType":{"type":"string","enum":["ISO","NSO","RSU","SAR","PSU"],"description":"Type of equity plan"},"shareClassId":{"type":"string","description":"Associated share class ID"},"totalShares":{"type":"number","description":"Total shares allocated to this plan"},"startDate":{"type":"string","format":"date","description":"Plan start date"},"expirationDate":{"type":"string","format":"date","description":"Plan expiration date"},"documentId":{"type":"string","description":"ID of the plan document"},"status":{"type":"string","enum":["active","expired","terminated"],"description":"Current plan status","default":"active"}}}}}},"responses":{"201":{"description":"Equity plan created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Unique identifier for the equity plan"},"name":{"type":"string","description":"Plan name"},"companyId":{"type":"string","description":"Associated company ID"},"planType":{"type":"string","enum":["ISO","NSO","RSU","SAR","PSU"],"description":"Type of equity plan"},"shareClassId":{"type":"string","description":"Associated share class ID"},"totalShares":{"type":"number","description":"Total shares allocated to this plan"},"availableShares":{"type":"number","description":"Remaining shares available for grants"},"startDate":{"type":"string","format":"date","description":"Plan start date"},"expirationDate":{"type":"string","format":"date","description":"Plan expiration date"},"status":{"type":"string","enum":["active","expired","terminated"],"description":"Current plan status"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/equityPlans/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Equity plan ID","schema":{"type":"string"}}],"get":{"tags":["Equity Plans"],"summary":"Get equity plan by ID","description":"Returns a single equity plan by its ID","operationId":"getEquityPlanById","responses":{"200":{"description":"Equity plan found","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Unique identifier for the equity plan"},"name":{"type":"string","description":"Plan name"},"companyId":{"type":"string","description":"Associated company ID"},"planType":{"type":"string","enum":["ISO","NSO","RSU","SAR","PSU"],"description":"Type of equity plan"},"shareClassId":{"type":"string","description":"Associated share class ID"},"totalShares":{"type":"number","description":"Total shares allocated to this plan"},"availableShares":{"type":"number","description":"Remaining shares available for grants"},"startDate":{"type":"string","format":"date","description":"Plan start date"},"expirationDate":{"type":"string","format":"date","description":"Plan expiration date"},"status":{"type":"string","enum":["active","expired","terminated"],"description":"Current plan status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Equity Plans"],"summary":"Update equity plan","description":"Updates an existing equity plan","operationId":"updateEquityPlan","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Plan name"},"totalShares":{"type":"number","description":"Total shares allocated to this plan"},"startDate":{"type":"string","format":"date","description":"Plan start date"},"expirationDate":{"type":"string","format":"date","description":"Plan expiration date"},"documentId":{"type":"string","description":"ID of the plan document"},"status":{"type":"string","enum":["active","expired","terminated"],"description":"Current plan status"}}}}}},"responses":{"200":{"description":"Equity plan updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Unique identifier for the equity plan"},"name":{"type":"string","description":"Plan name"},"companyId":{"type":"string","description":"Associated company ID"},"planType":{"type":"string","enum":["ISO","NSO","RSU","SAR","PSU"],"description":"Type of equity plan"},"shareClassId":{"type":"string","description":"Associated share class ID"},"totalShares":{"type":"number","description":"Total shares allocated to this plan"},"availableShares":{"type":"number","description":"Remaining shares available for grants"},"startDate":{"type":"string","format":"date","description":"Plan start date"},"expirationDate":{"type":"string","format":"date","description":"Plan expiration date"},"status":{"type":"string","enum":["active","expired","terminated"],"description":"Current plan status"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Equity Plans"],"summary":"Delete equity plan","description":"Deletes an equity plan by ID","operationId":"deleteEquityPlan","responses":{"204":{"description":"Equity plan deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/equityPlans/company/{companyId}":{"parameters":[{"name":"companyId","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["Equity Plans"],"summary":"Get equity plans by company","description":"Returns all equity plans for a specific company","operationId":"getEquityPlansByCompany","responses":{"200":{"description":"Equity plans found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Unique identifier for the equity plan"},"name":{"type":"string","description":"Plan name"},"planType":{"type":"string","enum":["ISO","NSO","RSU","SAR","PSU"],"description":"Type of equity plan"},"totalShares":{"type":"number","description":"Total shares allocated to this plan"},"availableShares":{"type":"number","description":"Remaining shares available for grants"},"status":{"type":"string","enum":["active","expired","terminated"],"description":"Current plan status"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/equityPlans/{id}/grants":{"parameters":[{"name":"id","in":"path","required":true,"description":"Equity plan ID","schema":{"type":"string"}}],"get":{"tags":["Equity Plans"],"summary":"Get grants for an equity plan","description":"Returns all grants issued under a specific equity plan","operationId":"getEquityPlanGrants","responses":{"200":{"description":"Equity plan grants found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Grant ID"},"employeeId":{"type":"string","description":"Employee ID"},"grantDate":{"type":"string","format":"date","description":"Date the grant was issued"},"sharesGranted":{"type":"number","description":"Number of shares granted"},"vestingSchedule":{"type":"object","description":"Vesting schedule details"},"status":{"type":"string","enum":["active","cancelled","exercised"],"description":"Grant status"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/v1/companies/{companyId}/metrics/profitability":{"get":{"summary":"Calculate profitability metrics","description":"Calculates profitability metrics such as gross profit margin, \noperating profit margin, and net profit margin for a specific company.\n","tags":["Financial Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Unique identifier of the company"},{"in":"query","name":"period","required":true,"schema":{"type":"string"},"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Profitability metrics calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfitabilityMetrics"}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No financial data found for the specified period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error while calculating metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/companies/{companyId}/metrics/liquidity":{"get":{"summary":"Calculate liquidity metrics","description":"Calculates liquidity metrics such as current ratio, quick ratio, \nand cash ratio for a specific company.\n","tags":["Financial Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Unique identifier of the company"},{"in":"query","name":"period","required":true,"schema":{"type":"string"},"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Liquidity metrics calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiquidityMetrics"}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No financial data found for the specified period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error while calculating metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/companies/{companyId}/metrics/solvency":{"get":{"summary":"Calculate solvency metrics","description":"Calculates solvency metrics such as debt-to-equity ratio and \ninterest coverage ratio for a specific company.\n","tags":["Financial Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Unique identifier of the company"},{"in":"query","name":"period","required":true,"schema":{"type":"string"},"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Solvency metrics calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolvencyMetrics"}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No financial data found for the specified period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error while calculating metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/companies/{companyId}/metrics/efficiency":{"get":{"summary":"Calculate efficiency metrics","description":"Calculates efficiency metrics such as asset turnover, inventory turnover,\nand receivables turnover for a specific company.\n","tags":["Financial Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Unique identifier of the company"},{"in":"query","name":"period","required":true,"schema":{"type":"string"},"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Efficiency metrics calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EfficiencyMetrics"}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No financial data found for the specified period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error while calculating metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/companies/{companyId}/metrics/growth":{"get":{"summary":"Calculate growth metrics","description":"Calculates growth metrics such as revenue growth, EBITDA growth,\nand net income growth compared to a previous period.\n","tags":["Financial Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Unique identifier of the company"},{"in":"query","name":"period","required":true,"schema":{"type":"string"},"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"},{"in":"query","name":"compareWith","required":false,"schema":{"type":"string","enum":["previous-year","previous-quarter"]},"description":"Basis for comparison (defaults to previous-year)"}],"responses":{"200":{"description":"Growth metrics calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrowthMetrics"}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No financial data found for the specified period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error while calculating metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/companies/{companyId}/metrics/valuation":{"get":{"summary":"Calculate valuation metrics","description":"Calculates valuation metrics such as P/E ratio, EV/EBITDA, P/B ratio,\nand other metrics for public companies.\n","tags":["Financial Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Unique identifier of the company"},{"in":"query","name":"period","required":true,"schema":{"type":"string"},"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Valuation metrics calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationMetrics"}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No financial data found for the specified period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error while calculating metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/companies/{companyId}/metrics/dashboard":{"get":{"summary":"Calculate comprehensive financial metrics dashboard","description":"Combines all financial metrics into a comprehensive dashboard view\nfor a specific company and reporting period.\n","tags":["Financial Metrics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"},"description":"Unique identifier of the company"},{"in":"query","name":"period","required":true,"schema":{"type":"string"},"description":"Reporting period in format YYYY-QX or YYYY-full (e.g., 2024-Q1 or 2024-full)"}],"responses":{"200":{"description":"Comprehensive metrics dashboard calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsDashboard"}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No financial data found for the specified period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error while calculating metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/financial-reports":{"get":{"tags":["Financial Reports"],"summary":"Get all financial reports","description":"Returns a paginated list of all financial reports","operationId":"getAllFinancialReports","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of financial reports","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FinancialReport"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Financial Reports"],"summary":"Create a new financial report","description":"Creates a new financial report in the system","operationId":"createFinancialReport","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialReportInput"}}}},"responses":{"201":{"description":"Financial report created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialReport"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/financial-reports/search":{"get":{"tags":["Financial Reports"],"summary":"Search financial reports","description":"Search for financial reports matching specific criteria","operationId":"searchFinancialReports","parameters":[{"name":"query","in":"query","description":"Search query","schema":{"type":"string"}},{"name":"reportType","in":"query","description":"Type of report","schema":{"type":"string"}},{"name":"startDate","in":"query","description":"Start date for filtering reports","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"End date for filtering reports","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FinancialReport"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/financial-reports/analytics":{"get":{"tags":["Financial Reports"],"summary":"Get financial report analytics","description":"Get analytical data and insights from financial reports","operationId":"getFinancialReportAnalytics","parameters":[{"name":"reportType","in":"query","description":"Type of report for analytics","schema":{"type":"string"}},{"name":"timeframe","in":"query","description":"Timeframe for analytics (e.g., monthly, quarterly, yearly)","schema":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]}}],"responses":{"200":{"description":"Analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"description":"Analytics data structure"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/financial-reports/bulk":{"post":{"tags":["Financial Reports"],"summary":"Create multiple financial reports","description":"Bulk create multiple financial reports in a single request","operationId":"bulkCreateFinancialReports","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/FinancialReportInput"}}}}}}},"responses":{"201":{"description":"Financial reports created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FinancialReport"}},"count":{"type":"integer","description":"Number of reports created"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/financial-reports/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Financial report ID","schema":{"type":"string"}}],"get":{"tags":["Financial Reports"],"summary":"Get financial report by ID","description":"Returns a single financial report by its ID","operationId":"getFinancialReportById","responses":{"200":{"description":"Financial report found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Financial Reports"],"summary":"Update financial report","description":"Updates an existing financial report","operationId":"updateFinancialReport","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialReportInput"}}}},"responses":{"200":{"description":"Financial report updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialReport"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Financial Reports"],"summary":"Delete financial report","description":"Deletes a financial report by ID","operationId":"deleteFinancialReport","responses":{"204":{"description":"Financial report deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/investments":{"get":{"tags":["Investment Management"],"summary":"Get all investments","description":"Returns a paginated list of all investments","operationId":"getAllInvestments","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of investments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Investment unique identifier"},"investorId":{"type":"string","description":"Investor ID making the investment"},"companyId":{"type":"string","description":"Company ID receiving the investment"},"spvId":{"type":"string","description":"SPV ID if applicable"},"amount":{"type":"number","description":"Investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)"},"investmentType":{"type":"string","enum":["equity","convertible_note","safe","debt"],"description":"Type of investment"},"shareClassId":{"type":"string","description":"Share class ID if equity investment"},"shareCount":{"type":"number","description":"Number of shares for equity investment"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"Current status of the investment"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Investment Management"],"summary":"Create a new investment","description":"Records a new investment in the system","operationId":"createInvestment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["investorId","amount","investmentType"],"properties":{"investorId":{"type":"string","description":"Investor ID making the investment"},"companyId":{"type":"string","description":"Company ID receiving the investment"},"spvId":{"type":"string","description":"SPV ID if applicable"},"amount":{"type":"number","description":"Investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)","default":"USD"},"investmentType":{"type":"string","enum":["equity","convertible_note","safe","debt"],"description":"Type of investment"},"shareClassId":{"type":"string","description":"Share class ID if equity investment"},"shareCount":{"type":"number","description":"Number of shares for equity investment"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"Current status of the investment","default":"pending"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"},"terms":{"type":"object","description":"Investment-specific terms","additionalProperties":true}}}}}},"responses":{"201":{"description":"Investment created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Investment unique identifier"},"investorId":{"type":"string","description":"Investor ID making the investment"},"companyId":{"type":"string","description":"Company ID receiving the investment"},"spvId":{"type":"string","description":"SPV ID if applicable"},"amount":{"type":"number","description":"Investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)"},"investmentType":{"type":"string","enum":["equity","convertible_note","safe","debt"],"description":"Type of investment"},"shareClassId":{"type":"string","description":"Share class ID if equity investment"},"shareCount":{"type":"number","description":"Number of shares for equity investment"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"Current status of the investment"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/investments/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Investment ID","schema":{"type":"string"}}],"get":{"tags":["Investment Management"],"summary":"Get investment by ID","description":"Returns a single investment by its ID","operationId":"getInvestmentById","responses":{"200":{"description":"Investment found","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Investment unique identifier"},"investorId":{"type":"string","description":"Investor ID making the investment"},"companyId":{"type":"string","description":"Company ID receiving the investment"},"spvId":{"type":"string","description":"SPV ID if applicable"},"amount":{"type":"number","description":"Investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)"},"investmentType":{"type":"string","enum":["equity","convertible_note","safe","debt"],"description":"Type of investment"},"shareClassId":{"type":"string","description":"Share class ID if equity investment"},"shareCount":{"type":"number","description":"Number of shares for equity investment"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"Current status of the investment"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"},"terms":{"type":"object","description":"Investment-specific terms","additionalProperties":true},"documents":{"type":"array","description":"Associated documents","items":{"type":"string","description":"Document ID"}},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Investment Management"],"summary":"Update investment","description":"Updates an existing investment","operationId":"updateInvestment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)"},"shareCount":{"type":"number","description":"Number of shares for equity investment"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"Current status of the investment"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"},"terms":{"type":"object","description":"Investment-specific terms","additionalProperties":true},"documents":{"type":"array","description":"Associated documents","items":{"type":"string","description":"Document ID"}}}}}}},"responses":{"200":{"description":"Investment updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Investment unique identifier"},"amount":{"type":"number","description":"Investment amount"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"Current status of the investment"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Investment Management"],"summary":"Delete investment","description":"Deletes an investment by ID","operationId":"deleteInvestment","responses":{"204":{"description":"Investment deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/investments/investor/{investorId}":{"parameters":[{"name":"investorId","in":"path","required":true,"description":"Investor ID","schema":{"type":"string"}}],"get":{"tags":["Investment Management"],"summary":"Get investments by investor","description":"Returns all investments made by a specific investor","operationId":"getInvestmentsByInvestor","responses":{"200":{"description":"Investments found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Investment unique identifier"},"companyId":{"type":"string","description":"Company ID receiving the investment"},"spvId":{"type":"string","description":"SPV ID if applicable"},"amount":{"type":"number","description":"Investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)"},"investmentType":{"type":"string","enum":["equity","convertible_note","safe","debt"],"description":"Type of investment"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"Current status of the investment"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/investments/company/{companyId}":{"parameters":[{"name":"companyId","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["Investment Management"],"summary":"Get investments by company","description":"Returns all investments made into a specific company","operationId":"getInvestmentsByCompany","responses":{"200":{"description":"Investments found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Investment unique identifier"},"investorId":{"type":"string","description":"Investor ID making the investment"},"amount":{"type":"number","description":"Investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)"},"investmentType":{"type":"string","enum":["equity","convertible_note","safe","debt"],"description":"Type of investment"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded"],"description":"Current status of the investment"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/investments/analytics/summary":{"get":{"tags":["Investment Management"],"summary":"Get investment analytics summary","description":"Returns summary analytics for investments","operationId":"getInvestmentAnalyticsSummary","parameters":[{"name":"companyId","in":"query","description":"Filter by company ID","schema":{"type":"string"}},{"name":"startDate","in":"query","description":"Start date for analytics period","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"End date for analytics period","schema":{"type":"string","format":"date"}},{"name":"investmentType","in":"query","description":"Filter by investment type","schema":{"type":"string","enum":["equity","convertible_note","safe","debt"]}}],"responses":{"200":{"description":"Investment analytics summary","content":{"application/json":{"schema":{"type":"object","properties":{"totalInvestments":{"type":"number","description":"Total number of investments"},"totalAmount":{"type":"number","description":"Total investment amount"},"byStatus":{"type":"object","description":"Breakdown by status","properties":{"pending":{"type":"number","description":"Number of pending investments"},"completed":{"type":"number","description":"Number of completed investments"},"cancelled":{"type":"number","description":"Number of cancelled investments"}}},"byType":{"type":"object","description":"Breakdown by investment type","properties":{"equity":{"type":"number","description":"Number of equity investments"},"convertible_note":{"type":"number","description":"Number of convertible note investments"},"safe":{"type":"number","description":"Number of SAFE investments"},"debt":{"type":"number","description":"Number of debt investments"}}},"trends":{"type":"object","description":"Time-based investment trends","additionalProperties":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/investors":{"get":{"tags":["Investor Management"],"summary":"Get all investors","description":"Returns a paginated list of all investors","operationId":"getAllInvestors","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of investors","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Investor"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Investor Management"],"summary":"Create a new investor","description":"Registers a new investor in the system","operationId":"createInvestor","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Full name of the investor"},"email":{"type":"string","format":"email","description":"Email address"},"type":{"type":"string","enum":["individual","institutional"],"description":"Type of investor"},"companyId":{"type":"string","description":"ID of the associated company"}}}}}},"responses":{"201":{"description":"Investor created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Investor"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/investors/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Investor ID","schema":{"type":"string"}}],"get":{"tags":["Investor Management"],"summary":"Get investor by ID","description":"Returns a single investor by ID","operationId":"getInvestorById","responses":{"200":{"description":"Investor found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Investor"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Investor Management"],"summary":"Update investor","description":"Updates an existing investor","operationId":"updateInvestor","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Full name of the investor"},"email":{"type":"string","format":"email","description":"Email address"},"type":{"type":"string","enum":["individual","institutional"],"description":"Type of investor"},"status":{"type":"string","enum":["active","inactive"],"description":"Investor status"}}}}}},"responses":{"200":{"description":"Investor updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Investor"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Investor Management"],"summary":"Delete investor","description":"Deletes an investor by ID","operationId":"deleteInvestor","responses":{"204":{"description":"Investor deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/investors/company/{companyId}":{"parameters":[{"name":"companyId","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["Investor Management"],"summary":"Get investors by company","description":"Returns all investors associated with a specific company","operationId":"getInvestorsByCompany","responses":{"200":{"description":"Investors found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Investor"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/notifications":{"get":{"tags":["Notifications"],"summary":"Get user notifications","description":"Returns a paginated list of notifications for the current user","operationId":"getUserNotifications","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"},{"name":"read","in":"query","description":"Filter by read status","schema":{"type":"boolean"}},{"name":"type","in":"query","description":"Filter by notification type","schema":{"type":"string","enum":["system","document","investment","compliance","user","other"]}}],"responses":{"200":{"description":"A list of notifications","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Notification unique identifier"},"userId":{"type":"string","description":"User ID the notification is for"},"title":{"type":"string","description":"Notification title"},"message":{"type":"string","description":"Notification message"},"type":{"type":"string","enum":["system","document","investment","compliance","user","other"],"description":"Type of notification"},"read":{"type":"boolean","description":"Whether the notification has been read"},"priority":{"type":"string","enum":["low","normal","high"],"description":"Notification priority"},"link":{"type":"string","description":"Optional link to related content"},"metadata":{"type":"object","description":"Additional data related to the notification","additionalProperties":true},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}},"unreadCount":{"type":"integer","description":"Count of unread notifications"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Notifications"],"summary":"Create a notification","description":"Creates a new notification for one or more users","operationId":"createNotification","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userIds","title","message","type"],"properties":{"userIds":{"type":"array","description":"Array of user IDs to notify","items":{"type":"string"}},"title":{"type":"string","description":"Notification title"},"message":{"type":"string","description":"Notification message"},"type":{"type":"string","enum":["system","document","investment","compliance","user","other"],"description":"Type of notification"},"priority":{"type":"string","enum":["low","normal","high"],"description":"Notification priority","default":"normal"},"link":{"type":"string","description":"Optional link to related content"},"metadata":{"type":"object","description":"Additional data related to the notification","additionalProperties":true}}}}}},"responses":{"201":{"description":"Notification created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"notificationIds":{"type":"array","description":"IDs of created notifications","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/notifications/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Notification ID","schema":{"type":"string"}}],"get":{"tags":["Notifications"],"summary":"Get notification by ID","description":"Returns a single notification by ID","operationId":"getNotificationById","responses":{"200":{"description":"Notification found","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Notification unique identifier"},"userId":{"type":"string","description":"User ID the notification is for"},"title":{"type":"string","description":"Notification title"},"message":{"type":"string","description":"Notification message"},"type":{"type":"string","enum":["system","document","investment","compliance","user","other"],"description":"Type of notification"},"read":{"type":"boolean","description":"Whether the notification has been read"},"priority":{"type":"string","enum":["low","normal","high"],"description":"Notification priority"},"link":{"type":"string","description":"Optional link to related content"},"metadata":{"type":"object","description":"Additional data related to the notification","additionalProperties":true},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Notifications"],"summary":"Mark notification as read","description":"Marks a notification as read","operationId":"markNotificationAsRead","responses":{"200":{"description":"Notification marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Notification unique identifier"},"read":{"type":"boolean","description":"Read status (should be true)"},"updatedAt":{"type":"string","format":"date-time","description":"Update timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Notifications"],"summary":"Delete notification","description":"Deletes a notification","operationId":"deleteNotification","responses":{"204":{"description":"Notification deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/notifications/read-all":{"put":{"tags":["Notifications"],"summary":"Mark all notifications as read","description":"Marks all of the current user's notifications as read","operationId":"markAllNotificationsAsRead","responses":{"200":{"description":"All notifications marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"count":{"type":"integer","description":"Number of notifications marked as read"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/notifications/count":{"get":{"tags":["Notifications"],"summary":"Get notification count","description":"Returns the count of notifications for the current user, including unread count","operationId":"getNotificationCount","responses":{"200":{"description":"Notification counts","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of notifications"},"unread":{"type":"integer","description":"Number of unread notifications"},"byType":{"type":"object","description":"Counts grouped by notification type","additionalProperties":{"type":"integer"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/notifications/user/{userId}":{"parameters":[{"name":"userId","in":"path","required":true,"description":"User ID","schema":{"type":"string"}}],"get":{"tags":["Notifications"],"summary":"Get notifications by user ID","description":"Returns notifications for a specific user (admin only)","operationId":"getNotificationsByUserId","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"Notifications found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Notification unique identifier"},"title":{"type":"string","description":"Notification title"},"message":{"type":"string","description":"Notification message"},"type":{"type":"string","description":"Type of notification"},"read":{"type":"boolean","description":"Whether the notification has been read"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/notifications/preferences":{"get":{"tags":["Notifications"],"summary":"Get notification preferences","description":"Returns the current user's notification preferences","operationId":"getNotificationPreferences","responses":{"200":{"description":"Notification preferences","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"object","description":"Email notification preferences","properties":{"system":{"type":"boolean","description":"Receive system notifications via email"},"document":{"type":"boolean","description":"Receive document notifications via email"},"investment":{"type":"boolean","description":"Receive investment notifications via email"},"compliance":{"type":"boolean","description":"Receive compliance notifications via email"},"user":{"type":"boolean","description":"Receive user notifications via email"}}},"push":{"type":"object","description":"Push notification preferences","properties":{"system":{"type":"boolean","description":"Receive system notifications via push"},"document":{"type":"boolean","description":"Receive document notifications via push"},"investment":{"type":"boolean","description":"Receive investment notifications via push"},"compliance":{"type":"boolean","description":"Receive compliance notifications via push"},"user":{"type":"boolean","description":"Receive user notifications via push"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Notifications"],"summary":"Update notification preferences","description":"Updates the current user's notification preferences","operationId":"updateNotificationPreferences","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"object","description":"Email notification preferences","properties":{"system":{"type":"boolean","description":"Receive system notifications via email"},"document":{"type":"boolean","description":"Receive document notifications via email"},"investment":{"type":"boolean","description":"Receive investment notifications via email"},"compliance":{"type":"boolean","description":"Receive compliance notifications via email"},"user":{"type":"boolean","description":"Receive user notifications via email"}}},"push":{"type":"object","description":"Push notification preferences","properties":{"system":{"type":"boolean","description":"Receive system notifications via push"},"document":{"type":"boolean","description":"Receive document notifications via push"},"investment":{"type":"boolean","description":"Receive investment notifications via push"},"compliance":{"type":"boolean","description":"Receive compliance notifications via push"},"user":{"type":"boolean","description":"Receive user notifications via push"}}}}}}}},"responses":{"200":{"description":"Notification preferences updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/notifications/subscribe":{"post":{"tags":["Notifications"],"summary":"Subscribe to push notifications","description":"Registers a device for push notifications","operationId":"subscribeToPushNotifications","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["deviceToken","platform"],"properties":{"deviceToken":{"type":"string","description":"Device token for push notifications"},"platform":{"type":"string","enum":["ios","android","web"],"description":"Device platform"},"deviceName":{"type":"string","description":"Name of the device"}}}}}},"responses":{"200":{"description":"Successfully subscribed to push notifications","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"subscriptionId":{"type":"string","description":"Subscription ID"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/notifications/unsubscribe":{"post":{"tags":["Notifications"],"summary":"Unsubscribe from push notifications","description":"Unregisters a device from push notifications","operationId":"unsubscribeFromPushNotifications","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["deviceToken"],"properties":{"deviceToken":{"type":"string","description":"Device token for push notifications"}}}}}},"responses":{"200":{"description":"Successfully unsubscribed from push notifications","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/auth/permissions":{"get":{"summary":"Get current user's permissions","description":"Returns the list of permissions for the authenticated user","tags":["Authentication"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"User permissions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"array","items":{"type":"string","example":"read:users"}},"role":{"type":"string","example":"admin"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/rbac/roles":{"get":{"summary":"Get all available roles","description":"Returns the list of all roles in the system","tags":["RBAC"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Roles retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/rbac/permissions":{"get":{"summary":"Get all available permissions","description":"Returns the list of all permissions in the system","tags":["RBAC"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Permissions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/users/{userId}/permissions":{"put":{"summary":"Update user permissions","description":"Updates the permissions for a specific user","tags":["Users","RBAC"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"array","items":{"type":"string","example":"read:users"}}},"required":["permissions"]}}}},"responses":{"200":{"description":"User permissions updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/share-classes":{"get":{"tags":["Share Classes"],"summary":"Get all share classes","description":"Returns a paginated list of all share classes","operationId":"getAllShareClasses","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of share classes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShareClass"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Share Classes"],"summary":"Create a new share class","description":"Creates a new share class in the system","operationId":"createShareClass","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareClassInput"}}}},"responses":{"201":{"description":"Share class created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareClass"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/share-classes/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Share class ID","schema":{"type":"string"}}],"get":{"tags":["Share Classes"],"summary":"Get share class by ID","description":"Returns a single share class by its ID","operationId":"getShareClassById","responses":{"200":{"description":"Share class found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareClass"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Share Classes"],"summary":"Update share class","description":"Updates an existing share class","operationId":"updateShareClass","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareClassInput"}}}},"responses":{"200":{"description":"Share class updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareClass"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Share Classes"],"summary":"Delete share class","description":"Deletes a share class by ID","operationId":"deleteShareClass","responses":{"204":{"description":"Share class deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/share-classes/company/{companyId}":{"parameters":[{"name":"companyId","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["Share Classes"],"summary":"Get share classes by company","description":"Returns all share classes for a specific company","operationId":"getShareClassesByCompany","responses":{"200":{"description":"Share classes found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShareClass"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/spvs/{id}":{"get":{"tags":["SPV Management"],"summary":"Get SPV by ID","description":"Returns a single SPV by its ID","operationId":"getSPVById","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"SPV ID"}],"responses":{"200":{"description":"SPV found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SPV","type":"object","properties":{"_id":{"type":"string","description":"SPV unique identifier"},"name":{"type":"string","description":"Name of the SPV"},"description":{"type":"string","description":"Description of the SPV"},"legalEntityType":{"type":"string","enum":["llc","lp","corporation","trust"],"description":"Legal entity type"},"managerId":{"type":"string","description":"ID of the managing user or company"},"adminIds":{"type":"array","description":"IDs of administrators","items":{"type":"string"}},"targetCompanyId":{"type":"string","description":"ID of the company this SPV invests in"},"status":{"type":"string","enum":["draft","active","closed","liquidated"],"description":"Current status of the SPV"},"investmentTarget":{"type":"number","description":"Target investment amount"},"investmentMinimum":{"type":"number","description":"Minimum investment amount"},"investmentMaximum":{"type":"number","description":"Maximum investment amount"},"currency":{"type":"string","description":"Currency code (e.g., USD)"},"legalFormationDate":{"type":"string","format":"date","description":"Date of legal formation"},"fees":{"type":"object","description":"Fee structure","properties":{"managementFee":{"type":"number","description":"Management fee percentage"},"carriedInterest":{"type":"number","description":"Carried interest percentage"},"establishmentFee":{"type":"number","description":"One-time establishment fee"}}},"legalDocuments":{"type":"array","description":"Associated legal documents","items":{"type":"object","properties":{"documentType":{"type":"string","enum":["operating_agreement","subscription_agreement","ppm","term_sheet"],"description":"Type of document"},"documentId":{"type":"string","description":"Document ID in storage"}}}},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"put":{"tags":["SPV Management"],"summary":"Update SPV","description":"Updates an existing SPV","operationId":"updateSPV","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"SPV ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SPVInput","type":"object","properties":{"name":{"type":"string","description":"Name of the SPV"},"description":{"type":"string","description":"Description of the SPV"},"adminIds":{"type":"array","description":"IDs of administrators","items":{"type":"string"}},"targetCompanyId":{"type":"string","description":"ID of the company this SPV invests in"},"status":{"type":"string","enum":["draft","active","closed","liquidated"],"description":"Current status of the SPV"},"investmentTarget":{"type":"number","description":"Target investment amount"},"investmentMinimum":{"type":"number","description":"Minimum investment amount"},"investmentMaximum":{"type":"number","description":"Maximum investment amount"},"legalFormationDate":{"type":"string","format":"date","description":"Date of legal formation"},"fees":{"type":"object","description":"Fee structure","properties":{"managementFee":{"type":"number","description":"Management fee percentage"},"carriedInterest":{"type":"number","description":"Carried interest percentage"},"establishmentFee":{"type":"number","description":"One-time establishment fee"}}},"legalDocuments":{"type":"array","description":"Associated legal documents","items":{"type":"object","properties":{"documentType":{"type":"string","enum":["operating_agreement","subscription_agreement","ppm","term_sheet"],"description":"Type of document"},"documentId":{"type":"string","description":"Document ID in storage"}}}}}}}}},"responses":{"200":{"description":"SPV updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SPV","type":"object","properties":{"_id":{"type":"string","description":"SPV unique identifier"},"name":{"type":"string","description":"Name of the SPV"},"status":{"type":"string","enum":["draft","active","closed","liquidated"],"description":"Current status of the SPV"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"tags":["SPV Management"],"summary":"Delete SPV","description":"Deletes an SPV by ID","operationId":"deleteSPV","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"SPV ID"}],"responses":{"200":{"description":"SPV deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"id":{"type":"string"}}}}}},"204":{"description":"SPV deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"parameters":[{"name":"id","in":"path","required":true,"description":"SPV ID","schema":{"type":"string"}}]},"/api/spvs/status/{status}":{"get":{"tags":["SPV Management"],"summary":"Get SPVs by status","description":"Retrieve SPVs filtered by their operational status","operationId":"getSPVsByStatus","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"status","required":true,"schema":{"type":"string","enum":["Active","Pending","Closed"]},"description":"SPV status"},{"in":"query","name":"limit","schema":{"type":"integer","default":10},"description":"Maximum number of records to return"},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Page number for pagination"}],"responses":{"200":{"description":"List of SPVs with the specified status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SPV"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/spvs/compliance/{status}":{"get":{"tags":["SPV Management"],"summary":"Get SPVs by compliance status","description":"Retrieve SPVs filtered by their compliance status","operationId":"getSPVsByComplianceStatus","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"status","required":true,"schema":{"type":"string","enum":["Compliant","NonCompliant","PendingReview"]},"description":"Compliance status"},{"in":"query","name":"limit","schema":{"type":"integer","default":10},"description":"Maximum number of records to return"},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Page number for pagination"}],"responses":{"200":{"description":"List of SPVs with the specified compliance status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SPV"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/spvs/{id}/investors":{"parameters":[{"name":"id","in":"path","required":true,"description":"SPV ID","schema":{"type":"string"}}],"get":{"tags":["SPV Management"],"summary":"Get SPV investors","description":"Returns all investors in a specific SPV","operationId":"getSPVInvestors","responses":{"200":{"description":"SPV investors found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Investor ID"},"investorName":{"type":"string","description":"Name of the investor"},"investmentAmount":{"type":"number","description":"Amount invested"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"},"status":{"type":"string","enum":["pending","active","exited"],"description":"Investor status in the SPV"},"ownershipPercentage":{"type":"number","description":"Percentage ownership in the SPV"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/spvs/{id}/investments":{"parameters":[{"name":"id","in":"path","required":true,"description":"SPV ID","schema":{"type":"string"}}],"get":{"tags":["SPV Management"],"summary":"Get SPV investments","description":"Returns all investments made by a specific SPV","operationId":"getSPVInvestments","responses":{"200":{"description":"SPV investments found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Investment ID"},"targetCompanyId":{"type":"string","description":"ID of the target company"},"targetCompanyName":{"type":"string","description":"Name of the target company"},"amount":{"type":"number","description":"Investment amount"},"currency":{"type":"string","description":"Currency code"},"investmentType":{"type":"string","enum":["equity","convertible_note","safe","debt"],"description":"Type of investment"},"investmentDate":{"type":"string","format":"date","description":"Date of investment"},"status":{"type":"string","enum":["pending","completed","exited"],"description":"Status of the investment"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/spvs/{id}/documents":{"parameters":[{"name":"id","in":"path","required":true,"description":"SPV ID","schema":{"type":"string"}}],"get":{"tags":["SPV Management"],"summary":"Get SPV documents","description":"Returns all documents associated with a specific SPV","operationId":"getSPVDocuments","responses":{"200":{"description":"SPV documents found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Document ID"},"documentName":{"type":"string","description":"Name of the document"},"documentType":{"type":"string","enum":["operating_agreement","subscription_agreement","ppm","term_sheet","tax_document","financial_statement","other"],"description":"Type of document"},"uploadDate":{"type":"string","format":"date-time","description":"Date the document was uploaded"},"uploadedBy":{"type":"string","description":"ID of the user who uploaded the document"},"fileSize":{"type":"number","description":"Size of the document in bytes"},"fileType":{"type":"string","description":"MIME type of the document"},"downloadUrl":{"type":"string","description":"URL to download the document"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/spvs/{id}/capital-calls":{"parameters":[{"name":"id","in":"path","required":true,"description":"SPV ID","schema":{"type":"string"}}],"get":{"tags":["SPV Management"],"summary":"Get SPV capital calls","description":"Returns all capital calls for a specific SPV","operationId":"getSPVCapitalCalls","responses":{"200":{"description":"SPV capital calls found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Capital call ID"},"callNumber":{"type":"number","description":"Sequential number of the capital call"},"callDate":{"type":"string","format":"date","description":"Date of the capital call"},"dueDate":{"type":"string","format":"date","description":"Due date for contributions"},"totalAmount":{"type":"number","description":"Total amount of the capital call"},"status":{"type":"string","enum":["draft","issued","partially_funded","fully_funded","closed"],"description":"Status of the capital call"},"purpose":{"type":"string","description":"Purpose of the capital call"},"contributionDetails":{"type":"array","description":"Details of investor contributions","items":{"type":"object","properties":{"investorId":{"type":"string","description":"Investor ID"},"amount":{"type":"number","description":"Amount due from this investor"},"status":{"type":"string","enum":["pending","received","late"],"description":"Status of this contribution"}}}}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["SPV Management"],"summary":"Create SPV capital call","description":"Creates a new capital call for a specific SPV","operationId":"createSPVCapitalCall","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["callDate","dueDate","totalAmount","purpose"],"properties":{"callDate":{"type":"string","format":"date","description":"Date of the capital call"},"dueDate":{"type":"string","format":"date","description":"Due date for contributions"},"totalAmount":{"type":"number","description":"Total amount of the capital call"},"status":{"type":"string","enum":["draft","issued","partially_funded","fully_funded","closed"],"description":"Status of the capital call","default":"draft"},"purpose":{"type":"string","description":"Purpose of the capital call"},"notes":{"type":"string","description":"Additional notes about the capital call"},"documentIds":{"type":"array","description":"IDs of documents related to this capital call","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"SPV capital call created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Capital call ID"},"callNumber":{"type":"number","description":"Sequential number of the capital call"},"callDate":{"type":"string","format":"date","description":"Date of the capital call"},"dueDate":{"type":"string","format":"date","description":"Due date for contributions"},"totalAmount":{"type":"number","description":"Total amount of the capital call"},"status":{"type":"string","enum":["draft","issued","partially_funded","fully_funded","closed"],"description":"Status of the capital call"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/spvs/manager/{managerId}":{"parameters":[{"name":"managerId","in":"path","required":true,"description":"Manager ID","schema":{"type":"string"}}],"get":{"tags":["SPV Management"],"summary":"Get SPVs by manager","description":"Returns all SPVs managed by a specific user or company","operationId":"getSPVsByManager","responses":{"200":{"description":"SPVs found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"SPV unique identifier"},"name":{"type":"string","description":"Name of the SPV"},"status":{"type":"string","enum":["draft","active","closed","liquidated"],"description":"Current status of the SPV"},"investmentTarget":{"type":"number","description":"Target investment amount"},"currency":{"type":"string","description":"Currency code"},"legalFormationDate":{"type":"string","format":"date","description":"Date of legal formation"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/taxCalculations":{"get":{"tags":["Tax Calculator"],"summary":"Get all tax calculations","description":"Returns a paginated list of previous tax calculations","operationId":"getAllTaxCalculations","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"}],"responses":{"200":{"description":"A list of tax calculations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Calculation unique identifier"},"userId":{"type":"string","description":"User who performed the calculation"},"companyId":{"type":"string","description":"Associated company ID"},"calculationType":{"type":"string","enum":["409a","83b","exercise","AMT"],"description":"Type of tax calculation"},"inputParameters":{"type":"object","description":"Input parameters used for calculation"},"results":{"type":"object","description":"Calculation results"},"createdAt":{"type":"string","format":"date-time","description":"Calculation timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Tax Calculator"],"summary":"Perform a new tax calculation","description":"Performs a new tax calculation based on input parameters","operationId":"performTaxCalculation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["calculationType","parameters"],"properties":{"companyId":{"type":"string","description":"Associated company ID"},"calculationType":{"type":"string","enum":["409a","83b","exercise","AMT"],"description":"Type of tax calculation"},"parameters":{"type":"object","description":"Input parameters for calculation (varies by calculation type)","additionalProperties":true}}}}}},"responses":{"200":{"description":"Tax calculation performed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Calculation unique identifier"},"calculationType":{"type":"string","enum":["409a","83b","exercise","AMT"],"description":"Type of tax calculation"},"inputParameters":{"type":"object","description":"Input parameters used for calculation"},"results":{"type":"object","description":"Calculation results"},"createdAt":{"type":"string","format":"date-time","description":"Calculation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/taxCalculations/409a":{"post":{"tags":["Tax Calculator"],"summary":"Perform 409A valuation calculation","description":"Calculates a 409A valuation based on input parameters","operationId":"perform409ACalculation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyId","valuationMethod","financialData"],"properties":{"companyId":{"type":"string","description":"Associated company ID"},"valuationMethod":{"type":"string","enum":["DCF","comparable","precedent","hybrid"],"description":"Valuation method to use"},"valuationDate":{"type":"string","format":"date","description":"Date for the valuation"},"financialData":{"type":"object","description":"Financial data for valuation calculation","additionalProperties":true},"recentFundingInfo":{"type":"object","description":"Recent funding information (if available)","additionalProperties":true}}}}}},"responses":{"200":{"description":"409A valuation calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Calculation unique identifier"},"companyId":{"type":"string","description":"Associated company ID"},"valuationMethod":{"type":"string","enum":["DCF","comparable","precedent","hybrid"],"description":"Valuation method used"},"commonStockValue":{"type":"number","description":"Calculated common stock value"},"preferredStockValue":{"type":"number","description":"Calculated preferred stock value (if applicable)"},"enterpriseValue":{"type":"number","description":"Calculated enterprise value"},"valuationDetails":{"type":"object","description":"Detailed valuation breakdown","additionalProperties":true},"createdAt":{"type":"string","format":"date-time","description":"Calculation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/taxCalculations/83b":{"post":{"tags":["Tax Calculator"],"summary":"Perform 83(b) election calculation","description":"Calculates tax implications of filing an 83(b) election","operationId":"perform83bCalculation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grantInfo","personalInfo"],"properties":{"grantInfo":{"type":"object","required":["shareCount","fairMarketValue","purchasePrice"],"properties":{"shareCount":{"type":"number","description":"Number of shares granted"},"fairMarketValue":{"type":"number","description":"Fair market value per share"},"purchasePrice":{"type":"number","description":"Purchase price per share"},"grantDate":{"type":"string","format":"date","description":"Date of grant"}}},"personalInfo":{"type":"object","required":["incomeBracket","state"],"properties":{"incomeBracket":{"type":"string","enum":["low","medium","high","very_high"],"description":"Income tax bracket"},"state":{"type":"string","description":"State of residence for tax purposes"},"filingStatus":{"type":"string","enum":["single","married_joint","married_separate","head_household"],"description":"Tax filing status"}}}}}}}},"responses":{"200":{"description":"83(b) election calculation performed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Calculation unique identifier"},"ordinaryIncomeTax":{"type":"number","description":"Ordinary income tax if 83(b) is not filed"},"taxWith83b":{"type":"number","description":"Tax amount with 83(b) election"},"taxWithout83b":{"type":"number","description":"Projected tax amount without 83(b) election"},"potentialSavings":{"type":"number","description":"Potential tax savings with 83(b) election"},"calculations":{"type":"object","description":"Detailed calculation breakdown","additionalProperties":true},"deadline":{"type":"string","format":"date","description":"Deadline to file 83(b) election"},"createdAt":{"type":"string","format":"date-time","description":"Calculation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/taxCalculations/exercise":{"post":{"tags":["Tax Calculator"],"summary":"Perform option exercise tax calculation","description":"Calculates tax implications of exercising stock options","operationId":"performExerciseCalculation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["optionInfo","personalInfo"],"properties":{"optionInfo":{"type":"object","required":["optionType","shareCount","strikePrice","fairMarketValue"],"properties":{"optionType":{"type":"string","enum":["ISO","NSO"],"description":"Type of stock option"},"shareCount":{"type":"number","description":"Number of options to exercise"},"strikePrice":{"type":"number","description":"Strike price per share"},"fairMarketValue":{"type":"number","description":"Current fair market value per share"},"grantDate":{"type":"string","format":"date","description":"Date of option grant"},"exerciseDate":{"type":"string","format":"date","description":"Planned exercise date"}}},"personalInfo":{"type":"object","required":["incomeBracket","state"],"properties":{"incomeBracket":{"type":"string","enum":["low","medium","high","very_high"],"description":"Income tax bracket"},"state":{"type":"string","description":"State of residence for tax purposes"},"filingStatus":{"type":"string","enum":["single","married_joint","married_separate","head_household"],"description":"Tax filing status"},"holdingPeriod":{"type":"string","enum":["short_term","long_term"],"description":"Planned holding period after exercise"}}}}}}}},"responses":{"200":{"description":"Exercise tax calculation performed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Calculation unique identifier"},"bargainElement":{"type":"number","description":"Bargain element (spread between FMV and strike price)"},"federalIncomeTax":{"type":"number","description":"Estimated federal income tax"},"stateTax":{"type":"number","description":"Estimated state tax"},"medicareTax":{"type":"number","description":"Estimated Medicare tax"},"socialSecurityTax":{"type":"number","description":"Estimated Social Security tax"},"AMTImpact":{"type":"number","description":"Potential AMT impact (for ISOs)"},"totalTaxLiability":{"type":"number","description":"Total estimated tax liability"},"calculations":{"type":"object","description":"Detailed calculation breakdown","additionalProperties":true},"createdAt":{"type":"string","format":"date-time","description":"Calculation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/taxCalculations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Tax calculation ID","schema":{"type":"string"}}],"get":{"tags":["Tax Calculator"],"summary":"Get tax calculation by ID","description":"Returns a single tax calculation by its ID","operationId":"getTaxCalculationById","responses":{"200":{"description":"Tax calculation found","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Calculation unique identifier"},"userId":{"type":"string","description":"User who performed the calculation"},"companyId":{"type":"string","description":"Associated company ID"},"calculationType":{"type":"string","enum":["409a","83b","exercise","AMT"],"description":"Type of tax calculation"},"inputParameters":{"type":"object","description":"Input parameters used for calculation"},"results":{"type":"object","description":"Calculation results"},"createdAt":{"type":"string","format":"date-time","description":"Calculation timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Tax Calculator"],"summary":"Delete tax calculation","description":"Deletes a tax calculation by ID","operationId":"deleteTaxCalculation","responses":{"204":{"description":"Tax calculation deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/users":{"get":{"tags":["User Management"],"summary":"Get all users","description":"Returns a paginated list of all users (admin access required)","operationId":"getAllUsers","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"},{"name":"role","in":"query","description":"Filter users by role","schema":{"type":"string","enum":["admin","manager","employee","investor"]}},{"name":"status","in":"query","description":"Filter users by status","schema":{"type":"string","enum":["active","inactive","pending"]}}],"responses":{"200":{"description":"A list of users","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","description":"User's email address"},"role":{"type":"string","enum":["admin","manager","employee","investor"],"description":"User's role in the system"},"status":{"type":"string","enum":["active","inactive","pending"],"description":"User's status"},"lastLogin":{"type":"string","format":"date-time","description":"Time of last login"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["User Management"],"summary":"Create a new user","description":"Creates a new user in the system","operationId":"createUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["firstName","lastName","email","password","role"],"properties":{"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"password":{"type":"string","format":"password","description":"User's password"},"role":{"type":"string","enum":["admin","manager","employee","investor"],"description":"User's role in the system"},"phone":{"type":"string","description":"User's phone number"},"companyId":{"type":"string","description":"ID of the company the user belongs to"},"photo":{"type":"string","description":"URL to user's profile photo"},"preferences":{"type":"object","description":"User preferences","additionalProperties":true}}}}}},"responses":{"201":{"description":"User created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","description":"User's email address"},"role":{"type":"string","enum":["admin","manager","employee","investor"],"description":"User's role in the system"},"status":{"type":"string","enum":["active","inactive","pending"],"description":"User's status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Email already in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/users/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"User ID","schema":{"type":"string"}}],"get":{"tags":["User Management"],"summary":"Get user by ID","description":"Returns a single user by ID","operationId":"getUserById","responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","description":"User's email address"},"role":{"type":"string","enum":["admin","manager","employee","investor"],"description":"User's role in the system"},"status":{"type":"string","enum":["active","inactive","pending"],"description":"User's status"},"phone":{"type":"string","description":"User's phone number"},"companyId":{"type":"string","description":"ID of the company the user belongs to"},"photo":{"type":"string","description":"URL to user's profile photo"},"lastLogin":{"type":"string","format":"date-time","description":"Time of last login"},"preferences":{"type":"object","description":"User preferences","additionalProperties":true},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["User Management"],"summary":"Update user","description":"Updates an existing user","operationId":"updateUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"role":{"type":"string","enum":["admin","manager","employee","investor"],"description":"User's role in the system"},"status":{"type":"string","enum":["active","inactive","pending"],"description":"User's status"},"phone":{"type":"string","description":"User's phone number"},"companyId":{"type":"string","description":"ID of the company the user belongs to"},"photo":{"type":"string","description":"URL to user's profile photo"},"preferences":{"type":"object","description":"User preferences","additionalProperties":true}}}}}},"responses":{"200":{"description":"User updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Email already in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["User Management"],"summary":"Delete user","description":"Deletes a user (soft delete - sets status to inactive)","operationId":"deleteUser","responses":{"204":{"description":"User deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/users/me":{"get":{"tags":["User Management"],"summary":"Get current user","description":"Returns the currently authenticated user's profile","operationId":"getCurrentUser","responses":{"200":{"description":"Current user profile","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","description":"User's email address"},"role":{"type":"string","enum":["admin","manager","employee","investor"],"description":"User's role in the system"},"status":{"type":"string","enum":["active","inactive","pending"],"description":"User's status"},"phone":{"type":"string","description":"User's phone number"},"companyId":{"type":"string","description":"ID of the company the user belongs to"},"photo":{"type":"string","description":"URL to user's profile photo"},"preferences":{"type":"object","description":"User preferences","additionalProperties":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["User Management"],"summary":"Update current user","description":"Updates the currently authenticated user's profile","operationId":"updateCurrentUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"phone":{"type":"string","description":"User's phone number"},"photo":{"type":"string","description":"URL to user's profile photo"},"preferences":{"type":"object","description":"User preferences","additionalProperties":true}}}}}},"responses":{"200":{"description":"User updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Email already in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/users/company/{companyId}":{"parameters":[{"name":"companyId","in":"path","required":true,"description":"Company ID","schema":{"type":"string"}}],"get":{"tags":["User Management"],"summary":"Get users by company","description":"Returns all users associated with a specific company","operationId":"getUsersByCompany","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SortParam"},{"name":"role","in":"query","description":"Filter users by role","schema":{"type":"string","enum":["admin","manager","employee","investor"]}}],"responses":{"200":{"description":"Users found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","description":"User's email address"},"role":{"type":"string","enum":["admin","manager","employee","investor"],"description":"User's role in the system"},"status":{"type":"string","enum":["active","inactive","pending"],"description":"User's status"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/auth/login":{"post":{"tags":["Authentication"],"summary":"User login","description":"Authenticates a user and returns a JWT token","operationId":"loginUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","description":"User's email address"},"password":{"type":"string","format":"password","description":"User's password"}}}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"JWT authentication token"},"user":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","description":"User's email address"},"role":{"type":"string","description":"User's role"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/auth/register":{"post":{"tags":["Authentication"],"summary":"User registration","description":"Registers a new user","operationId":"registerUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["firstName","lastName","email","password"],"properties":{"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"password":{"type":"string","format":"password","description":"User's password"},"phone":{"type":"string","description":"User's phone number"},"companyId":{"type":"string","description":"ID of the company the user belongs to"},"inviteCode":{"type":"string","description":"Invitation code if registering via invite"}}}}}},"responses":{"201":{"description":"Registration successful","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"_id":{"type":"string","description":"User unique identifier"},"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"email":{"type":"string","description":"User's email address"},"status":{"type":"string","description":"User's status"}}},"message":{"type":"string","description":"Success message"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"description":"Email already in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/auth/forgot-password":{"post":{"tags":["Authentication"],"summary":"Forgot password","description":"Initiates the password reset process","operationId":"forgotPassword","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"User's email address"}}}}}},"responses":{"200":{"description":"Password reset email sent","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Email not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/auth/reset-password":{"post":{"tags":["Authentication"],"summary":"Reset password","description":"Resets the user's password using a reset token","operationId":"resetPassword","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","password"],"properties":{"token":{"type":"string","description":"Password reset token"},"password":{"type":"string","format":"password","description":"New password"}}}}}},"responses":{"200":{"description":"Password reset successful","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/auth/change-password":{"post":{"tags":["Authentication"],"summary":"Change password","description":"Changes the password for the currently authenticated user","operationId":"changePassword","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currentPassword","newPassword"],"properties":{"currentPassword":{"type":"string","format":"password","description":"Current password"},"newPassword":{"type":"string","format":"password","description":"New password"}}}}}},"responses":{"200":{"description":"Password changed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Current password is incorrect","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/webhooks":{"get":{"tags":["Webhooks"],"summary":"Get webhooks","description":"Returns all webhooks configured for the current user or company","operationId":"getWebhooks","parameters":[{"name":"companyId","in":"query","description":"Filter by company ID","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by webhook status","schema":{"type":"string","enum":["active","inactive"]}},{"name":"eventType","in":"query","description":"Filter by event type","schema":{"type":"string"}}],"responses":{"200":{"description":"A list of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Webhook unique identifier"},"name":{"type":"string","description":"Webhook name"},"url":{"type":"string","description":"Endpoint URL"},"eventTypes":{"type":"array","description":"Event types to trigger this webhook","items":{"type":"string"}},"status":{"type":"string","enum":["active","inactive"],"description":"Webhook status"},"secret":{"type":"string","description":"Secret key for webhook signature (partially masked)"},"createdBy":{"type":"string","description":"ID of the user who created the webhook"},"companyId":{"type":"string","description":"Associated company ID"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Webhooks"],"summary":"Create webhook","description":"Creates a new webhook endpoint","operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url","eventTypes"],"properties":{"name":{"type":"string","description":"Webhook name"},"url":{"type":"string","description":"Endpoint URL"},"eventTypes":{"type":"array","description":"Event types to trigger this webhook","items":{"type":"string","enum":["user.created","user.updated","user.deleted","investor.created","investor.updated","investor.deleted","company.created","company.updated","company.deleted","share_class.created","share_class.updated","share_class.deleted","equity_plan.created","equity_plan.updated","equity_plan.deleted","employee.created","employee.updated","employee.deleted","investment.created","investment.updated","investment.deleted","document.created","document.updated","document.deleted","compliance.check.completed","compliance.check.failed","notification.created","spv.created","spv.updated","spv.deleted"]}},"description":{"type":"string","description":"Webhook description"},"companyId":{"type":"string","description":"Associated company ID"}}}}}},"responses":{"201":{"description":"Webhook created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Webhook unique identifier"},"name":{"type":"string","description":"Webhook name"},"url":{"type":"string","description":"Endpoint URL"},"eventTypes":{"type":"array","description":"Event types","items":{"type":"string"}},"secret":{"type":"string","description":"Secret key for webhook signature"},"status":{"type":"string","enum":["active","inactive"],"description":"Webhook status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID","schema":{"type":"string"}}],"get":{"tags":["Webhooks"],"summary":"Get webhook by ID","description":"Returns a single webhook by ID","operationId":"getWebhookById","responses":{"200":{"description":"Webhook found","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Webhook unique identifier"},"name":{"type":"string","description":"Webhook name"},"url":{"type":"string","description":"Endpoint URL"},"eventTypes":{"type":"array","description":"Event types","items":{"type":"string"}},"status":{"type":"string","enum":["active","inactive"],"description":"Webhook status"},"secret":{"type":"string","description":"Secret key for webhook signature (partially masked)"},"description":{"type":"string","description":"Webhook description"},"createdBy":{"type":"string","description":"ID of the user who created the webhook"},"companyId":{"type":"string","description":"Associated company ID"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Webhooks"],"summary":"Update webhook","description":"Updates an existing webhook","operationId":"updateWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Webhook name"},"url":{"type":"string","description":"Endpoint URL"},"eventTypes":{"type":"array","description":"Event types","items":{"type":"string"}},"status":{"type":"string","enum":["active","inactive"],"description":"Webhook status"},"description":{"type":"string","description":"Webhook description"}}}}}},"responses":{"200":{"description":"Webhook updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Webhook unique identifier"},"name":{"type":"string","description":"Webhook name"},"status":{"type":"string","enum":["active","inactive"],"description":"Webhook status"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Webhooks"],"summary":"Delete webhook","description":"Deletes a webhook","operationId":"deleteWebhook","responses":{"204":{"description":"Webhook deleted successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/webhooks/{id}/rotate-secret":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID","schema":{"type":"string"}}],"post":{"tags":["Webhooks"],"summary":"Rotate webhook secret","description":"Rotates the secret key for the specified webhook","operationId":"rotateWebhookSecret","responses":{"200":{"description":"Secret rotated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string","description":"Webhook unique identifier"},"secret":{"type":"string","description":"New secret key"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/webhooks/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID","schema":{"type":"string"}}],"post":{"tags":["Webhooks"],"summary":"Test webhook","description":"Sends a test event to the webhook endpoint","operationId":"testWebhook","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"eventType":{"type":"string","description":"Event type to simulate"}}}}}},"responses":{"200":{"description":"Test executed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the test was successful"},"statusCode":{"type":"integer","description":"HTTP status code received"},"message":{"type":"string","description":"Response message"},"responseTime":{"type":"number","description":"Response time in milliseconds"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/webhooks/{id}/deliveries":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID","schema":{"type":"string"}}],"get":{"tags":["Webhooks"],"summary":"Get webhook deliveries","description":"Returns a list of recent webhook delivery attempts","operationId":"getWebhookDeliveries","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"name":"status","in":"query","description":"Filter by delivery status","schema":{"type":"string","enum":["success","failed"]}},{"name":"eventType","in":"query","description":"Filter by event type","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Delivery unique identifier"},"webhookId":{"type":"string","description":"Webhook ID"},"eventType":{"type":"string","description":"Event type"},"status":{"type":"string","enum":["success","failed"],"description":"Delivery status"},"statusCode":{"type":"integer","description":"HTTP status code"},"responseTime":{"type":"number","description":"Response time in milliseconds"},"requestPayload":{"type":"object","description":"Request payload sent"},"responseBody":{"type":"string","description":"Response body received"},"error":{"type":"string","description":"Error message if failed"},"createdAt":{"type":"string","format":"date-time","description":"Delivery timestamp"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/webhooks/event-types":{"get":{"tags":["Webhooks"],"summary":"Get webhook event types","description":"Returns all available webhook event types","operationId":"getWebhookEventTypes","responses":{"200":{"description":"Available event types","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"eventType":{"type":"string","description":"Event type identifier"},"description":{"type":"string","description":"Description of the event"},"category":{"type":"string","description":"Category of the event"},"payloadSchema":{"type":"object","description":"Schema of the event payload"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}},"/api/webhooks/delivery/{deliveryId}/retry":{"parameters":[{"name":"deliveryId","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"post":{"tags":["Webhooks"],"summary":"Retry webhook delivery","description":"Retries a failed webhook delivery","operationId":"retryWebhookDelivery","responses":{"200":{"description":"Retry initiated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"deliveryId":{"type":"string","description":"New delivery ID for the retry"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerAuth":[]}]}}},"tags":[{"name":"API Metrics","description":"API performance metrics and monitoring"},{"name":"Cache","description":"Cache management endpoints"},{"name":"Email Tracking","description":"Email delivery tracking and analytics"},{"name":"Material Events","description":"Material event detection and tracking for 409A compliance"},{"name":"StakeholderReports","description":"Stakeholder report generation and management"},{"name":"Terminations","description":"Employee termination and equity management"},{"name":"409A Export","description":"Export data for third-party 409A valuation providers"},{"name":"409A Valuations","description":"409A valuation request and management"},{"name":"Valuation Partners","description":"Valuation specialist/firm integration and management"}]}