{"openapi":"3.0.3","info":{"version":"1.0.0","contact":{"name":"API Support","email":"support@contexthub.dev"},"title":"Context Hub - App Logs API","description":"Application functional logging system for tracking events, errors, and system activities."},"servers":[{"url":"http://localhost:3000","description":"Development Server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication. Keys can have different permissions:\n- CREATE: Ability to create new logs\n- READ: Ability to read/query logs\n- UPDATE: Ability to modify existing logs\n- DELETE: Ability to delete logs\n\nEach endpoint requires specific permissions as documented below.\n"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"PermissionDenied":{"description":"Insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Insufficient permissions"},"message":{"type":"string","example":"This API key does not have CREATE permission"},"required":{"type":"string","example":"CREATE"},"available":{"type":"array","items":{"type":"string"},"example":["READ"]}}}}}}}},"paths":{"/api/v1/app-logs":{"post":{"summary":"Create a new app log entry","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Create a new application log entry.\n**Required Permission: CREATE**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["module","event","payload"],"properties":{"module":{"type":"string","description":"The module/component generating the log"},"event":{"type":"string","description":"Short description of the event"},"payload":{"oneOf":[{"type":"string"},{"type":"object"}],"description":"The log message or data"},"stackTrace":{"type":"string","description":"Stack trace for errors (optional)"},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"],"default":"INFO"},"statusCode":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code (optional)"},"userId":{"type":"string","description":"Associated user ID (optional)"},"metadata":{"type":"object","description":"Additional key-value data (optional)"}}}}}},"responses":{"201":{"description":"App log created successfully"},"400":{"description":"Invalid input data"},"403":{"$ref":"#/components/responses/PermissionDenied"}}},"get":{"summary":"Get app logs with optional filtering and pagination","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Retrieve application logs with optional filtering and pagination.\n**Required Permission: READ**\n","parameters":[{"in":"query","name":"module","schema":{"type":"string"},"description":"Filter by module name"},{"in":"query","name":"logLevel","schema":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"]},"description":"Filter by log level"},{"in":"query","name":"userId","schema":{"type":"string"},"description":"Filter by user ID"},{"in":"query","name":"event","schema":{"type":"string"},"description":"Search in event names (case-insensitive)"},{"in":"query","name":"startDate","schema":{"type":"string","format":"date-time"},"description":"Filter logs from this date onwards"},{"in":"query","name":"endDate","schema":{"type":"string","format":"date-time"},"description":"Filter logs up to this date"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Number of logs per page"},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["createdAt","logLevel","module"],"default":"createdAt"},"description":"Field to order by"},{"in":"query","name":"orderDirection","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Order direction"}],"responses":{"200":{"description":"App logs retrieved successfully"},"400":{"description":"Invalid query parameters"},"403":{"$ref":"#/components/responses/PermissionDenied"}}}},"/api/v1/app-logs/{id}":{"get":{"summary":"Get a specific app log by ID","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Retrieve a single application log by its ID.\n**Required Permission: READ**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The app log ID"}],"responses":{"200":{"description":"App log retrieved successfully"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"App log not found"}}},"put":{"summary":"Update an app log entry","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Update an existing application log entry.\n**Required Permission: UPDATE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The app log ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"module":{"type":"string"},"event":{"type":"string"},"payload":{"oneOf":[{"type":"string"},{"type":"object"}]},"stackTrace":{"type":"string"},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"]},"statusCode":{"type":"integer","minimum":100,"maximum":599},"userId":{"type":"string"},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"App log updated successfully"},"400":{"description":"Invalid input data"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"App log not found"}}},"delete":{"summary":"Delete an app log entry","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Delete an existing application log entry.\n**Required Permission: DELETE**\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The app log ID"}],"responses":{"200":{"description":"App log deleted successfully"},"403":{"$ref":"#/components/responses/PermissionDenied"},"404":{"description":"App log not found"}}}},"/api/v1/app-logs/stats":{"get":{"summary":"Get application logs statistics","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Get statistical information about application logs.\n**Required Permission: READ**\n","responses":{"200":{"description":"Log statistics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"totalLogs":{"type":"integer"},"logsByLevel":{"type":"object"},"logsByModule":{"type":"object"},"recentActivity":{"type":"object"}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"}}}},"/api/v1/app-logs/admin/cleanup":{"delete":{"summary":"Admin cleanup of old logs","tags":["App Logs"],"security":[{"ApiKeyAuth":[]}],"description":"Clean up old log entries based on specified criteria.\n**Required Permission: DELETE**\nNote: This is a potentially destructive operation.\n","parameters":[{"in":"query","name":"olderThanDays","schema":{"type":"integer","minimum":1,"default":90},"description":"Delete logs older than this many days"},{"in":"query","name":"logLevel","schema":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"]},"description":"Only delete logs of this level"},{"in":"query","name":"confirm","schema":{"type":"boolean"},"description":"Must be set to true to confirm deletion","required":true}],"responses":{"200":{"description":"Cleanup completed successfully"},"400":{"description":"Missing confirmation or invalid parameters"},"403":{"$ref":"#/components/responses/PermissionDenied"}}}},"/api/v1/app-logs/csp-report":{"post":{"summary":"CSP violation report endpoint","tags":["CSP Violations"],"description":"Receives CSP violation reports from browsers and logs them to the app logs system.\nThis endpoint is called automatically by browsers when CSP violations occur.\n","requestBody":{"required":true,"content":{"application/csp-report":{"schema":{"type":"object","properties":{"csp-report":{"type":"object","properties":{"document-uri":{"type":"string","description":"The URI of the document where the violation occurred"},"referrer":{"type":"string","description":"The referrer of the document"},"violated-directive":{"type":"string","description":"The policy directive that was violated"},"original-policy":{"type":"string","description":"The complete CSP policy"},"blocked-uri":{"type":"string","description":"The URI of the resource that was blocked"},"source-file":{"type":"string","description":"The file where the violation occurred"},"line-number":{"type":"integer","description":"The line number where the violation occurred"},"status-code":{"type":"integer","description":"The HTTP status code of the document"}}}}}}}},"responses":{"204":{"description":"CSP violation logged successfully"},"400":{"description":"Invalid CSP report format"}}}},"/api/v1/app-logs/csp-stats":{"get":{"summary":"Get CSP violation statistics","tags":["CSP Violations"],"security":[{"ApiKeyAuth":[]}],"description":"Get statistics and analysis of CSP violations logged in the system.\n**Required Permission: READ**\n","responses":{"200":{"description":"CSP violation statistics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"totalViolations":{"type":"integer","description":"Total number of CSP violations logged"},"recentViolations":{"type":"integer","description":"Number of recent violations returned"},"stats":{"type":"object","properties":{"violatedDirectives":{"type":"object","description":"Count of violations by directive type"},"blockedUris":{"type":"object","description":"Count of violations by blocked URI"},"sourceFiles":{"type":"object","description":"Count of violations by source file"},"violationsByHour":{"type":"object","description":"Count of violations by hour of day"}}},"logs":{"type":"array","items":{"$ref":"#/components/schemas/AppLog"}}}}}}},"403":{"$ref":"#/components/responses/PermissionDenied"}}}}},"tags":[{"name":"App Logs","description":"Application functional logging - Track events, errors, and system activities"},{"name":"CSP Violations","description":"Content Security Policy violation reporting and analysis"}]}