{"openapi":"3.0.0","paths":{"/api/v1/security/agencies":{"get":{"description":"Returns the caller agency and, for a master agency, each of its sub-agencies. Pass an id from this list as agencyId to create or list external scans and risk assessments for that agency.","operationId":"SecurityApiAgenciesController_getAgencies","parameters":[],"responses":{"200":{"description":"The caller agency followed by its sub-agencies.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SecurityApiAgencyDTO"}}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"List the agencies the caller can target","tags":["Agencies"]}},"/api/v1/security/devices":{"get":{"description":"Returns the devices of every risk assessment the caller can see, each with its assessmentId and agencyId, so a full sync does not need one request per assessment. Removed devices are excluded.","operationId":"SecurityApiDevicesController_listDevices","parameters":[{"name":"agencyId","required":false,"in":"query","description":"Agency to list devices for, as listed by GET /api/v1/security/agencies. A master agency includes its sub-agencies. Required for callers without an agency, such as platform-app credentials. Targeting an agency outside your own tree returns 403.","schema":{"format":"uuid","type":"string"}},{"name":"assessmentId","required":false,"in":"query","description":"Only return devices of this risk assessment","schema":{"format":"uuid","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of devices to skip. Devices are ordered by creation time, oldest first.","schema":{"minimum":0,"default":0,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Maximum devices to return, at most 500","schema":{"minimum":1,"maximum":500,"default":100,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicesDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"List devices across risk assessments","tags":["Devices"]}},"/api/v1/security/external-scans":{"get":{"operationId":"SecurityApiExternalScansController_getExternalScanAssessments","parameters":[{"required":false,"description":"Search query string","name":"search","in":"query","schema":{"type":"string"}},{"required":false,"description":"Field to sort by","name":"assessmentSortBy","in":"query","schema":{"default":"createdAt","allOf":[{"$ref":"#/components/schemas/AssessmentSortBy"}]}},{"required":false,"description":"Sort order","name":"sortOrder","in":"query","schema":{"default":"DESC","allOf":[{"$ref":"#/components/schemas/SortOrder"}]}},{"required":false,"description":"Number of records to skip","name":"offset","in":"query","schema":{"default":0,"type":"number"}},{"required":false,"description":"Maximum results to return","name":"limit","in":"query","schema":{"default":100,"type":"number"}},{"required":false,"description":"Optional target agency ID to scope results to. Allowed for TELIVY_ADMIN callers (e.g. platform-app credentials) and for the admin of a master agency (including its API key) targeting its own agency or one of its sub-agencies, listed by GET /api/v1/security/agencies. Any other caller gets 403.","name":"agencyId","in":"query","schema":{"format":"uuid","type":"string"}},{"required":false,"description":"Only return assessments mapped to this company id in the owning agency PSA integration (ConnectWise company id, Autotask account id or HaloPSA client id), as reported in psaCompanies","name":"psaCompanyId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The external scan assessments are successfully listed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScansDTO"}}}}},"security":[{"oauth2":[]},{"ApiKey":[]},{"bearer":[]}],"summary":"Get all external scans","tags":["External Scans"]},"post":{"operationId":"SecurityApiExternalScansController_addExternalScanAssessment","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScanCreateDTO"}}}},"responses":{"201":{"description":"The external scan assessment has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScanDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Create an external scan","tags":["External Scans"]}},"/api/v1/security/external-scans/{id}":{"get":{"operationId":"SecurityApiExternalScansController_getExternalScanAssessment","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The external scan assessment data is fetched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScanDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get external scan by ID","tags":["External Scans"]},"put":{"operationId":"SecurityApiExternalScansController_editExternalScanAssessment","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScanCreateDTO"}}}},"responses":{"200":{"description":"The external scan assessment has been successfully updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScanDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Update an external scan","tags":["External Scans"]}},"/api/v1/security/external-scans/{id}/agency":{"patch":{"description":"Moves the scan and its history to another agency. The response carries the new agencyId. Moving to the agency that already owns it changes nothing.","operationId":"SecurityApiExternalScansController_moveExternalScanToAgency","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveToAgencyDTO"}}}},"responses":{"200":{"description":"The scan as filed under its new agency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScanDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Move an external scan to another agency","tags":["External Scans"],"x-mcp":{"destructive":true}}},"/api/v1/security/external-scans/{id}/archive":{"post":{"description":"Use when a customer stops the service. Sets scanStatus to archived and turns monitoring off. Scan history, findings and reports are kept and stay readable through the API. GET /api/v1/security/external-scans leaves archived scans out unless a search term is passed.","operationId":"SecurityApiExternalScansController_archiveExternalScan","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"The archived scan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScanDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Archive an external scan","tags":["External Scans"],"x-mcp":{"destructive":true}}},"/api/v1/security/external-scans/{id}/unarchive":{"post":{"description":"Returns an archived scan to in_progress. Monitoring stays off until it is enabled again.","operationId":"SecurityApiExternalScansController_unarchiveExternalScan","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"The unarchived scan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalScanDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Unarchive an external scan","tags":["External Scans"]}},"/api/v1/security/external-scans/{id}/findings":{"get":{"operationId":"SecurityApiExternalScansController_getExternalScanAssessmentFindings","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The external scan assessment findings data is fetched.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SecurityFindingDTO"}}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get external scan findings","tags":["External Scans"]}},"/api/v1/security/external-scans/{id}/rescan-all":{"post":{"operationId":"SecurityApiExternalScansController_markApplicationRescanAll","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepScanEventDTO"}}}},"responses":{"200":{"description":"The assessment is marked for rescan."}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Rescan all devices for assessment","tags":["External Scans"]}},"/api/v1/security/external-scans/{id}/uninstall-all":{"post":{"operationId":"SecurityApiExternalScansController_markApplicationUninstallAll","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepScanEventDTO"}}}},"responses":{"200":{"description":"The application is marked for uninstall."}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Uninstall all devices for assessment","tags":["External Scans"],"x-mcp":{"destructive":true}}},"/api/v1/security/external-scans/{id}/breach-data":{"get":{"operationId":"SecurityApiExternalScansController_getBreachData","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The breach data is fetched.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BreachDataDTO"}}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get breach data for assessment","tags":["External Scans"]}},"/api/v1/security/external-scans/{id}/findings/{slug}":{"get":{"operationId":"SecurityApiExternalScansController_getExternalScanFindings","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}},{"name":"slug","required":true,"in":"path","description":"Finding Slug","schema":{"type":"string"}}],"responses":{"200":{"description":"The external scan assessment finding data is fetched.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SecurityFindingDetailDTO"}}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get external scan finding details by slug","tags":["External Scans"]}},"/api/v1/security/external-scans/{id}/report":{"get":{"operationId":"SecurityApiExternalScansController_generateExternalScanReport","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment ID","schema":{"type":"string"}},{"name":"detailed","required":false,"in":"query","description":"Generate detailed report","schema":{"default":false,"type":"boolean"}},{"name":"format","required":false,"in":"query","description":"Report file format","schema":{"$ref":"#/components/schemas/ReportFormat"}},{"required":false,"description":"Generate detailed report","name":"detailed","in":"query","schema":{"default":false,"type":"boolean"}},{"required":false,"description":"Report file format","name":"format","in":"query","schema":{"default":"pdf","allOf":[{"$ref":"#/components/schemas/ReportFormat"}]}}],"responses":{"200":{"description":"The external scan assessment report is downloaded.","content":{"application/octet-stream":{}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Download external scan report","tags":["External Scans"]}},"/api/v1/security/risk-assessments/{id}/convert-to-risk-assessment":{"post":{"operationId":"SecurityApiRiskAssessmentsController_convertToRiskAssessment","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully converted application to a risk assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Convert application to risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/monitoring-settings":{"patch":{"operationId":"SecurityApiRiskAssessmentsController_updateApplicationSettings","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentUpdateMonitoringDTO"}}}},"responses":{"200":{"description":"Successfully updated risk monitoring configuration for the assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Update monitoring settings for risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getRiskAssessments","parameters":[{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"scanStatus","required":false,"in":"query","schema":{"type":"array","items":{"$ref":"#/components/schemas/RiskAssessmentStatus"}}},{"name":"assessmentSortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/AssessmentSortBy"}},{"name":"sortOrder","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"offset","required":false,"in":"query","description":"Number of records to skip","schema":{"default":0,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Maximum records to return","schema":{"default":100,"type":"number"}},{"name":"agencyId","required":false,"in":"query","description":"Optional target agency ID to scope results to. Allowed for TELIVY_ADMIN callers (e.g. platform-app credentials) and for the admin of a master agency (including its API key) targeting its own agency or one of its sub-agencies, listed by GET /api/v1/security/agencies. Any other caller gets 403.","schema":{"format":"uuid","type":"string"}},{"name":"psaCompanyId","required":false,"in":"query","description":"Only return assessments mapped to this company id in the owning agency PSA integration (ConnectWise company id, Autotask account id or HaloPSA client id), as reported in psaCompanies","schema":{"type":"string"}},{"required":false,"name":"search","in":"query","schema":{"type":"string"}},{"required":false,"name":"scanStatus","in":"query","schema":{"type":"array","items":{"$ref":"#/components/schemas/RiskAssessmentStatus"}}},{"required":false,"name":"assessmentSortBy","in":"query","schema":{"default":"createdAt","allOf":[{"$ref":"#/components/schemas/AssessmentSortBy"}]}},{"required":false,"name":"sortOrder","in":"query","schema":{"default":"DESC","allOf":[{"$ref":"#/components/schemas/SortOrder"}]}},{"required":false,"description":"Number of records to skip","name":"offset","in":"query","schema":{"default":0,"type":"number"}},{"required":false,"description":"Maximum records to return","name":"limit","in":"query","schema":{"default":100,"type":"number"}},{"required":false,"description":"Optional target agency ID to scope results to. Allowed for TELIVY_ADMIN callers (e.g. platform-app credentials) and for the admin of a master agency (including its API key) targeting its own agency or one of its sub-agencies, listed by GET /api/v1/security/agencies. Any other caller gets 403.","name":"agencyId","in":"query","schema":{"format":"uuid","type":"string"}},{"required":false,"description":"Only return assessments mapped to this company id in the owning agency PSA integration (ConnectWise company id, Autotask account id or HaloPSA client id), as reported in psaCompanies","name":"psaCompanyId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved risk assessments based on query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentsDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get all risk assessments","tags":["Risk Assessments"]},"post":{"operationId":"SecurityApiRiskAssessmentsController_addRiskAssessment","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentCreateDTO"}}}},"responses":{"201":{"description":"Successfully created a new light scan risk assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Create a risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getRiskAssessment","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved detailed risk assessment data including security scan information when available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get risk assessment by ID","tags":["Risk Assessments"]},"put":{"operationId":"SecurityApiRiskAssessmentsController_editRiskAssessment","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentCreateDTO"}}}},"responses":{"200":{"description":"Successfully updated organization and domain information for the risk assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Update a risk assessment","tags":["Risk Assessments"],"x-mcp":{"destructive":true}}},"/api/v1/security/risk-assessments/{id}/end-trial":{"post":{"operationId":"SecurityApiRiskAssessmentsController_endTrial","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"201":{"description":"The trial is ended. A repeat call returns the same state unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"End a persistent-agent trial and mark the assessment converted","tags":["Risk Assessments"],"x-mcp":{"destructive":true}}},"/api/v1/security/risk-assessments/{id}/agency":{"patch":{"description":"Moves the assessment, its scan history and its deployed agents to another agency without reinstalling anything. The response carries the new agencyId. Moving to the agency that already owns it changes nothing.","operationId":"SecurityApiRiskAssessmentsController_moveRiskAssessmentToAgency","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveToAgencyDTO"}}}},"responses":{"200":{"description":"The assessment as filed under its new agency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Move a risk assessment to another agency","tags":["Risk Assessments"],"x-mcp":{"destructive":true}}},"/api/v1/security/risk-assessments/{id}/archive":{"post":{"description":"Use when a customer stops the service. Sets scanStatus to archived, turns monitoring off and schedules the Telivy agent to uninstall itself from every device. Scan history, findings and reports are kept and stay readable through the API. GET /api/v1/security/risk-assessments leaves archived assessments out unless scanStatus=archived or a search term is passed.","operationId":"SecurityApiRiskAssessmentsController_archiveRiskAssessment","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"201":{"description":"The archived assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Archive a risk assessment","tags":["Risk Assessments"],"x-mcp":{"destructive":true}}},"/api/v1/security/risk-assessments/{id}/unarchive":{"post":{"description":"Returns an archived assessment to in_progress. Monitoring stays off until it is set again with PATCH /api/v1/security/risk-assessments/{id}/monitoring-settings, and agents removed by the archive must be deployed again.","operationId":"SecurityApiRiskAssessmentsController_unarchiveRiskAssessment","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"201":{"description":"The unarchived assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Unarchive a risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/findings":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getDeviceFindings","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"New, open and regressed device findings of the current scan group. Resolved findings are never included.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RiskAssessmentDeviceFindingDTO"}}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get open device findings of the current scan group for a risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/domain-change-preview":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getDomainChangePreview","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Preview of data that will be affected by a domain change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainChangePreviewDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/devices":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getAllDeepScanDevices","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved all scan targets associated with this assessment.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DeepScanTargetDTO"}}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get all devices for risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/devices/{deviceId}":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getDeepScanTarget","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}},{"name":"deviceId","required":true,"in":"path","description":"Deep Scan Target UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved detailed information for the specified scan target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepScanTargetDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get device by ID","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/devices/{deviceId}/uninstall":{"post":{"description":"Schedules removal of the Telivy agent from a single device of the assessment. The agent uninstalls itself on its next check-in and the device then reports telivyAgentUninstalledAt. Other devices are untouched; use POST /api/v1/security/external-scans/{id}/uninstall-all for every device. Returns 422 when the device has no Telivy agent.","operationId":"SecurityApiRiskAssessmentsController_uninstallDevice","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}},{"name":"deviceId","required":true,"in":"path","description":"Device UUID, as returned by the devices endpoints","schema":{"type":"string"}}],"responses":{"201":{"description":"The uninstall is scheduled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepScanTargetDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Uninstall the Telivy agent from one device","tags":["Risk Assessments"],"x-mcp":{"destructive":true}}},"/api/v1/security/risk-assessments/{id}/devices/{deviceId}/rescan":{"post":{"operationId":"SecurityApiRiskAssessmentsController_rescanDeepScanTarget","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}},{"name":"deviceId","required":true,"in":"path","description":"Deep Scan Target UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully initiated a rescan for the specified target device."}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Rescan device","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/scan-status":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getScanStatus","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Scan completion status summary for all devices in the assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentScanStatusDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get scan completion status for all devices in a risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/report":{"get":{"operationId":"SecurityApiRiskAssessmentsController_generateRiskAssessmentReport","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}},{"required":false,"name":"reportType","in":"query","schema":{"default":"telivy_complete_report_pdf","allOf":[{"$ref":"#/components/schemas/ReportType"}]}}],"responses":{"200":{"description":"Successfully generated and delivered risk assessment report as a downloadable file.","content":{"application/octet-stream":{}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Download risk assessment report","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/documents":{"get":{"description":"Lists every document already generated for the assessment, newest first, including reports generated in the portal and through GET /api/v1/security/risk-assessments/{id}/report. Download one with GET /api/v1/security/risk-assessments/{id}/documents/{documentId}; nothing is generated.","operationId":"SecurityApiRiskAssessmentsController_getRiskAssessmentDocuments","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Number of documents to skip. Documents are ordered newest first.","schema":{"minimum":0,"default":0,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Maximum documents to return, at most 100","schema":{"minimum":1,"maximum":100,"default":100,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentDocumentsDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"List the stored reports and documents of a risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/documents/{documentId}":{"get":{"description":"Streams a document listed by GET /api/v1/security/risk-assessments/{id}/documents as it was stored, without generating it again. Returns 404 when the document does not belong to the assessment.","operationId":"SecurityApiRiskAssessmentsController_downloadRiskAssessmentDocument","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}},{"name":"documentId","required":true,"in":"path","description":"Document UUID, as returned by the documents list","schema":{"type":"string"}}],"responses":{"200":{"description":"The stored file as an attachment.","content":{"application/octet-stream":{}}},"404":{"description":"The assessment is not visible to the caller, or the document does not belong to it."}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Download a stored document of a risk assessment","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/m365-users":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getM365Users","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"M365 user data including account status, MFA, login failures. Returns configured=false if M365 is not connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/M365UsersResponseDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get M365 user accounts with login status and MFA info","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/gws-users":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getGwsUsers","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Google Workspace user data including account status, 2SV, login activity. Returns configured=false if GWS is not connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GwsUsersResponseDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get Google Workspace user accounts with login and 2SV status","tags":["Risk Assessments"]}},"/api/v1/security/risk-assessments/{id}/pii-summary":{"get":{"operationId":"SecurityApiRiskAssessmentsController_getPiiSummary","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"PII distribution by type and device, with aggregate risk values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PiiSummaryDataDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"summary":"Get PII exposure summary across all devices","tags":["Risk Assessments"]}},"/api/v1/security/{id}/risk":{"get":{"operationId":"SecurityController_getRiskProgressReport","parameters":[{"name":"id","required":true,"in":"path","description":"Assessment UUID","schema":{"type":"string"}},{"name":"currentTimestampGroup","required":true,"in":"query","description":"The current/most recent scan timestamp","schema":{"type":"string"}},{"name":"compareWithTimestampGroup","required":false,"in":"query","description":"The scan timestamp to compare against (defaults to previous scan if not provided)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved risk progress report for the assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindingsProgressReportResponseDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"tags":["security"]}},"/api/v1/security/agent-versions":{"get":{"operationId":"SecurityController_getLatestAgentVersions","parameters":[],"responses":{"200":{"description":"Successfully retrieved the latest available agent versions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionsDTO"}}}}},"security":[{"ApiKey":[]},{"oauth2":[]},{"bearer":[]}],"tags":["security"]}},"/api/v1/security/findings/{slug}":{"get":{"operationId":"SecurityController_getFindingDetailsBySlug","parameters":[{"name":"slug","required":true,"in":"path","description":"Finding slug (e.g., TYPO_SQUATTING, PERSONAL_EMAILS)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved finding details for the given slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecurityFindingDTO"}}}}},"tags":["security"]}}},"info":{"title":"Telivy Security API","description":"

Telivy Security APIs for Managed Service Providers (MSPs). Manage external scans, risk assessments, and security findings programmatically.

\n \n

Authentication

\n

Telivy uses Auth0 for secure authentication. To access the API, you'll need an MSP account on our platform.

\n

New to Telivy? Contact us to create a free account.

\n\n

OAuth2 Authentication

\n

Obtain an access token by completing the login flow:

\n

Start OAuth2 Login Flow

\n\n

API Key Authentication

\n

Include your API key in the x-api-key header with each request.

\n

Find your API key in the Telivy Portal → Account → Integrations.

\n\n

OpenAPI Schema

\n

Download the OpenAPI 3.0 specification for code generation and API tooling:

\n

https://api-v1.telivy.com/api-docs/security-json

\n\n \n

Agencies

\n

A master agency's API key can act on its own agency and on each of its sub-agencies. GET /api/v1/security/agencies lists them. Pass one of those ids as agencyId to create, list or move assessments and to list devices for that agency. Every assessment, scan and device carries the agencyId that owns it, and an agencyId outside your agency tree is rejected with 403, never ignored.

\n\n

Pagination

\n

List endpoints take offset and limit and return total, the number of matching records across all pages. Request pages until offset reaches total. limit defaults to 100; GET /api/v1/security/devices accepts at most 500 per page.

\n\n

Rate limits

\n

Requests authenticated with x-api-key are limited to 60 requests per 60 seconds per API key, counted across all endpoints and all of your client's IP addresses. There is no separate concurrency limit. Every response under the limit carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). Over the limit the API answers 429 Too Many Requests with a Retry-After header in seconds and the body {\"message\":\"ThrottlerException: Too Many Requests\",\"statusCode\":429}. Wait for Retry-After before sending more requests.

\n\n \n

Webhooks

\n

Webhook subscriptions belong to an agency. Telivy sends each event the subscription lists as an HTTP POST with a JSON body shaped like WebhookEnvelopeDTO. Events are delivered to subscriptions of the agency that owns the assessment. A master agency receives its sub-agencies' events only on subscriptions created with includeSubAgencies: true; every payload carries the owning agencyId.

\n

Request headers: X-Telivy-Event (event name), X-Webhook-ID (subscription ID), and X-Telivy-Signature, the hex HMAC-SHA256 of the raw request body keyed with the subscription secret. Custom headers configured on the subscription are added as well.

\n

Any non-2xx response or a timeout after 60 seconds counts as a failure. A failed delivery is retried with increasing delays, up to 3 attempts in total by default; metadata.attemptNumber tells retries apart. Deliveries can repeat, so handlers should be idempotent.

\n\n\n\n\n\n\n\n\n\n\n\n
EventSent whendata schema
SCAN_COMPLETEDAn external security scan of an assessment finishes, including scheduled rescans.ScanCompletedWebhookData
SECURITY_GRADE_CHANGEDThe overall security grade (the securityScore grade returned by External Scans) differs from the previous graded scan, or changes after a finding is resolved.SecurityGradeChangedWebhookData
AGENT_INSTALLEDThe Telivy agent reports a completed install on a device that has no install recorded. Starting a new install clears the device's install and uninstall records, so each reinstall sends it again.AgentLifecycleWebhookData
AGENT_UNINSTALLEDThe Telivy agent reports it was uninstalled from a device that has no uninstall recorded. Sent again after the device is reinstalled and uninstalled once more.AgentLifecycleWebhookData
ASSESSMENT_STATUS_CHANGEDAn assessment moves between not_started, in_progress, complete and archived.The assessment record after the change, including id and applicationStatus. Fields beyond those two are not a stable contract.
ALERT_RAISEDA new security alert is raised for an assessment.The alert record, including id, applicationId, category and data.
TESTThe test button is used on a subscription.{ message, scheduledAt }
\n","version":"1.0","contact":{}},"tags":[],"servers":[{"url":"https://api-v1.telivy.com"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key authentication"},"oauth2":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.telivy.com/authorize?audience=telivy-agent-portal&client_id=xY0dmr0qR6slpPOWDyHY7FFt6VuZCdKH","scopes":{}}},"description":"OAuth2 authentication via Auth0"},"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"JWT Bearer token authentication"}},"schemas":{"SecurityApiAgencyDTO":{"type":"object","properties":{"id":{"type":"string","description":"Agency ID, accepted as agencyId"},"name":{"type":"string","description":"Agency name"},"externalId":{"type":"string","nullable":true,"description":"External agency ID"},"domain":{"type":"string","nullable":true,"description":"Agency domain"},"isMasterAgency":{"type":"boolean","description":"Whether this is a master agency"},"masterAgencyId":{"type":"string","nullable":true,"description":"Master agency ID when this is a sub-agency"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"}},"required":["id","name","externalId","domain","isMasterAgency","masterAgencyId","createdAt"]},"TenantDeviceDTO":{"type":"object","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"macAddress":{"type":"string"},"osVersion":{"type":"string"},"telivyAgentInstalledAt":{"type":"string"},"telivyAgentUninstalledAt":{"type":"string"},"lastHeartBeatAt":{"type":"string"},"status":{"type":"string"},"scanCompleted":{"type":"boolean","description":"Whether all scans for this device have completed"},"agentVersion":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"assessmentId":{"type":"string","description":"Risk assessment the device reports to"},"agencyId":{"type":"string","nullable":true,"description":"Agency that owns the risk assessment"}},"required":["id","hostname","macAddress","osVersion","telivyAgentInstalledAt","telivyAgentUninstalledAt","lastHeartBeatAt","status","scanCompleted","agentVersion","createdAt","updatedAt","assessmentId","agencyId"]},"DevicesDTO":{"type":"object","properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/TenantDeviceDTO"}},"total":{"type":"number","description":"Number of devices matching the filters across all pages. Page through them with offset and limit."}},"required":["devices","total"]},"AssessmentSortBy":{"type":"string","enum":["organizationName","assessmentStatus","createdAt","updatedAt"],"description":"Field to sort by"},"SortOrder":{"type":"string","enum":["DESC","ASC"],"description":"Sort order"},"ExternalScanStatus":{"type":"string","enum":["not_started","in_progress","completed","archived"],"description":"Current scan status"},"OrganizationAddressDTO":{"type":"object","properties":{"street":{"type":"string","description":"Street address"},"unit":{"type":"string","description":"Unit or suite number"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State or province"},"zip_code":{"type":"string","description":"ZIP or postal code"}},"required":["street","city","state","zip_code"]},"AssessmentDetailsDTO":{"type":"object","properties":{"organization_name":{"type":"string","description":"Organization name"},"domain_prim":{"type":"string","description":"Primary domain"},"organization_address":{"description":"Organization address","allOf":[{"$ref":"#/components/schemas/OrganizationAddressDTO"}]},"contact_first_name":{"type":"string","description":"Contact first name"},"contact_last_name":{"type":"string","description":"Contact last name"},"contact_email":{"type":"string","description":"Contact email address"},"business_phone":{"type":"string","description":"Business phone number"},"annual_revenue":{"type":"number","description":"Annual revenue"},"employee_count":{"type":"number","description":"Employee count"},"primary_operations":{"type":"string","description":"Primary business operations"}},"required":["organization_name","domain_prim","organization_address","contact_first_name","contact_last_name","contact_email","business_phone","annual_revenue","employee_count","primary_operations"]},"SecurityGrade":{"type":"string","enum":["A","B","C","D","F","n/a"],"description":"Overall security score grade"},"SecurityGradesDTO":{"type":"object","properties":{"socialEngineering":{"nullable":true,"description":"Social engineering security grade","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"networkSecurity":{"nullable":true,"description":"Network security grade","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"applicationSecurity":{"nullable":true,"description":"Application security grade","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"dnsHealth":{"nullable":true,"description":"DNS health grade","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"ipReputation":{"nullable":true,"description":"IP reputation grade","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"externalVulnerabilities":{"nullable":true,"description":"External vulnerabilities grade","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]}},"required":["socialEngineering","networkSecurity","applicationSecurity","dnsHealth","ipReputation","externalVulnerabilities"]},"ExternalIntegrationType":{"type":"string","enum":["connectwise","autotask","halopsa"],"description":"PSA the company lives in"},"PsaCompanyDTO":{"type":"object","properties":{"integration":{"description":"PSA the company lives in","allOf":[{"$ref":"#/components/schemas/ExternalIntegrationType"}]},"externalId":{"type":"string","description":"Company ID in that PSA: the ConnectWise company id, Autotask account id or HaloPSA client id"}},"required":["integration","externalId"]},"ExternalScanDTO":{"type":"object","properties":{"id":{"type":"string","description":"External scan ID"},"scanStatus":{"description":"Current scan status","allOf":[{"$ref":"#/components/schemas/ExternalScanStatus"}]},"assessmentDetails":{"description":"Assessment details","allOf":[{"$ref":"#/components/schemas/AssessmentDetailsDTO"}]},"securityScore":{"description":"Overall security score grade","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"lastScannedAt":{"format":"date-time","type":"string","nullable":true,"description":"Last scan timestamp"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"},"agencyId":{"type":"string","nullable":true,"description":"ID of the agency that owns the scan, as listed by GET /api/v1/security/agencies"},"grades":{"description":"Security grades by category","allOf":[{"$ref":"#/components/schemas/SecurityGradesDTO"}]},"psaCompanies":{"description":"PSA companies the assessment is mapped to in the owning agency PSA integrations, one entry per integration. Returned by the list and get-by-id endpoints, omitted elsewhere. Filter the list by one of these ids with psaCompanyId.","type":"array","items":{"$ref":"#/components/schemas/PsaCompanyDTO"}}},"required":["id","scanStatus","assessmentDetails","securityScore","createdAt","updatedAt","agencyId"]},"ExternalScansDTO":{"type":"object","properties":{"message":{"type":"string","description":"Response status message"},"assessments":{"description":"List of external scan assessments","type":"array","items":{"$ref":"#/components/schemas/ExternalScanDTO"}},"total":{"type":"number","description":"Number of external scans matching the filters across all pages. Page through them with offset and limit."}},"required":["message","assessments","total"]},"ClientCategory":{"type":"string","enum":["breakfix","it_only","security_only","it_and_security"],"description":"Client category"},"ClientStatus":{"type":"string","enum":["suspect","lead","client"],"description":"Client status"},"ExternalScanCreateDTO":{"type":"object","properties":{"organizationName":{"type":"string","description":"Organization name"},"domain":{"type":"string","description":"Primary domain to scan"},"clientCategory":{"nullable":true,"description":"Client category","allOf":[{"$ref":"#/components/schemas/ClientCategory"}]},"clientStatus":{"nullable":true,"description":"Client status","allOf":[{"$ref":"#/components/schemas/ClientStatus"}]},"agencyId":{"type":"string","format":"uuid","description":"Target agency ID. Required for callers that are not associated with an agency (e.g. platform-app credentials). Also allowed for the admin of a master agency (including its API key) targeting its own agency or one of its sub-agencies, listed by GET /api/v1/security/agencies. Any other caller gets 403. The scan is attached to that agency, owned by its admin agent."},"unityCustomerId":{"type":"string","format":"uuid","description":"Unity customer ID. Accepted only from platform-app credentials. The scan is filed under the agency company linked to that customer, which is created as a client when none exists."}},"required":["organizationName","domain"]},"MoveToAgencyDTO":{"type":"object","properties":{"agencyId":{"type":"string","format":"uuid","description":"Agency to move the assessment to, as listed by GET /api/v1/security/agencies. Allowed for TELIVY_ADMIN callers and for the admin of a master agency moving between its own agency and its sub-agencies. Any other target returns 403."}},"required":["agencyId"]},"SecuritySeverity":{"type":"string","enum":["critical","high","medium","low","info"],"description":"Severity level"},"SecurityFindingDTO":{"type":"object","properties":{"name":{"type":"string","description":"Finding name"},"slug":{"type":"string","description":"Finding slug identifier"},"description":{"type":"string","description":"Finding description"},"risk":{"type":"string","description":"Risk description"},"recommendation":{"type":"string","description":"Remediation recommendation"},"references":{"description":"Reference links","type":"array","items":{"type":"string"}},"scanType":{"type":"string","description":"Type of security scan"},"severity":{"description":"Severity level","allOf":[{"$ref":"#/components/schemas/SecuritySeverity"}]}},"required":["name","scanType","severity"]},"DeepScanEventDTO":{"type":"object","properties":{"reason":{"type":"string"}}},"BreachDatePrecision":{"type":"string","enum":["day","month","year"]},"BreachAttributionDTO":{"type":"object","properties":{"text":{"type":"string"},"url":{"type":"string"}},"required":["text","url"]},"BreachCatalogDTO":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"breachDate":{"type":"string","nullable":true,"format":"date"},"breachDatePrecision":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/BreachDatePrecision"}]},"affectedAccounts":{"type":"number","nullable":true},"dataClasses":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"disclosureUrl":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true},"isVerified":{"type":"boolean"},"isSpamList":{"type":"boolean"},"isFabricated":{"type":"boolean"},"isSensitive":{"type":"boolean"},"isStealerLog":{"type":"boolean"},"isCompilation":{"type":"boolean"},"recommendedActions":{"type":"array","items":{"type":"string"}},"attribution":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/BreachAttributionDTO"}]}},"required":["id","title","breachDate","breachDatePrecision","affectedAccounts","dataClasses","summary","disclosureUrl","logoUrl","isVerified","isSpamList","isFabricated","isSensitive","isStealerLog","isCompilation","recommendedActions","attribution"]},"ExposedField":{"type":"string","enum":["email","password","hashed_password","username","name","phone","address","dob","ssn","government_id","ip","social","url","company"]},"BreachDataDTO":{"type":"object","properties":{"id":{"type":"string"},"securityScanId":{"type":"string"},"domainName":{"type":"string"},"breachName":{"type":"string","nullable":true},"lastBreach":{"type":"string","nullable":true},"email":{"type":"string"},"ipAddress":{"type":"string","nullable":true},"userName":{"type":"string","nullable":true},"password":{"type":"string"},"hashedPassword":{"type":"string","nullable":true},"hashType":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"breach":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/BreachCatalogDTO"}]},"exposedFields":{"type":"array","items":{"$ref":"#/components/schemas/ExposedField"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","securityScanId","domainName","breachName","lastBreach","email","ipAddress","userName","password","hashedPassword","hashType","name","address","phone","breach","exposedFields","createdAt","updatedAt"]},"SecurityFindingStatus":{"type":"string","enum":["open","in_review","resolved","accepted"],"description":"Finding status"},"SecurityFindingDetailDTO":{"type":"object","properties":{"id":{"type":"string","description":"Finding ID"},"domain":{"type":"string","description":"Domain where finding was detected"},"slug":{"type":"string","description":"Finding slug identifier"},"scanType":{"type":"string","description":"Type of security scan"},"severity":{"description":"Severity level","allOf":[{"$ref":"#/components/schemas/SecuritySeverity"}]},"value":{"type":"string","description":"Finding value or details"},"status":{"description":"Finding status","allOf":[{"$ref":"#/components/schemas/SecurityFindingStatus"}]},"comment":{"type":"string","description":"User comment"},"devLogs":{"type":"string","description":"Development logs"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","domain","slug","scanType","severity","value","status","comment","devLogs","createdAt","updatedAt"]},"ReportFormat":{"type":"string","enum":["pdf","docx"]},"RiskAssessmentStatus":{"type":"string","enum":["not_started","in_progress","report_completed","archived"]},"MonitoringFrequency":{"type":"string","enum":["DISABLE","QUARTERLY","MONTHLY","WEEKLY"]},"ExecutiveSummaryScore":{"type":"object","properties":{"securityScore":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"summary":{"type":"string"}},"required":["securityScore"]},"ExecutiveSummaryDTO":{"type":"object","properties":{"networkSecurity":{"$ref":"#/components/schemas/ExecutiveSummaryScore"},"dataSecurity":{"$ref":"#/components/schemas/ExecutiveSummaryScore"},"applicationSecurity":{"$ref":"#/components/schemas/ExecutiveSummaryScore"},"identityAccessManagement":{"$ref":"#/components/schemas/ExecutiveSummaryScore"},"darkWebPresence":{"$ref":"#/components/schemas/ExecutiveSummaryScore"},"m365Security":{"$ref":"#/components/schemas/ExecutiveSummaryScore"},"gwsSecurity":{"$ref":"#/components/schemas/ExecutiveSummaryScore"}},"required":["networkSecurity","dataSecurity","applicationSecurity","identityAccessManagement","darkWebPresence","m365Security","gwsSecurity"]},"RiskAssessmentDTO":{"type":"object","properties":{"id":{"type":"string"},"telivyKey":{"type":"string"},"scanStatus":{"allOf":[{"$ref":"#/components/schemas/RiskAssessmentStatus"}]},"assessmentDetails":{"$ref":"#/components/schemas/AssessmentDetailsDTO"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"monitoringEnabled":{"type":"boolean"},"monitoringFrequency":{"allOf":[{"$ref":"#/components/schemas/MonitoringFrequency"}]},"executiveSummary":{"$ref":"#/components/schemas/ExecutiveSummaryDTO"},"companyId":{"type":"string","nullable":true},"agencyId":{"type":"string","nullable":true,"description":"ID of the agency that owns the assessment, as listed by GET /api/v1/security/agencies"},"isTrial":{"type":"boolean"},"psaCompanies":{"description":"PSA companies the assessment is mapped to in the owning agency PSA integrations, one entry per integration. Returned by the list and get-by-id endpoints, omitted elsewhere. Filter the list by one of these ids with psaCompanyId.","type":"array","items":{"$ref":"#/components/schemas/PsaCompanyDTO"}}},"required":["id","telivyKey","scanStatus","assessmentDetails","createdAt","updatedAt","monitoringEnabled","companyId","agencyId","isTrial"]},"RiskAssessmentUpdateMonitoringDTO":{"type":"object","properties":{"monitoringFrequency":{"nullable":true,"description":"The frequency of monitoring for the risk assessment. Use null to disable monitoring.","allOf":[{"$ref":"#/components/schemas/MonitoringFrequency"}]}},"required":["monitoringFrequency"]},"RiskAssessmentsDTO":{"type":"object","properties":{"message":{"type":"string"},"assessments":{"type":"array","items":{"$ref":"#/components/schemas/RiskAssessmentDTO"}},"total":{"type":"number","description":"Number of risk assessments matching the filters across all pages. Page through them with offset and limit."}},"required":["message","assessments","total"]},"PiiCountry":{"type":"string","enum":["US","CA","UK","ZA","AU","NZ","SG","PL"]},"RiskAssessmentCreateDTO":{"type":"object","properties":{"organizationName":{"type":"string"},"domain":{"type":"string"},"country":{"default":"US","allOf":[{"$ref":"#/components/schemas/PiiCountry"}]},"clientCategory":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ClientCategory"}]},"clientStatus":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ClientStatus"}]},"antiVirus":{"type":"string"},"cleanupDomainChange":{"type":"boolean"},"agencyId":{"type":"string","format":"uuid","description":"Target agency ID. Allowed for TELIVY_ADMIN callers (e.g. platform-app credentials) and for the admin of a master agency (including its API key) targeting its own agency or one of its sub-agencies, listed by GET /api/v1/security/agencies. Any other caller gets 403. The assessment is attached to that agency, owned by its admin agent."},"isTrial":{"type":"boolean","description":"Create the assessment as a persistent-agent trial. Honoured only for TELIVY_ADMIN callers; ignored otherwise."},"isLightScan":{"type":"boolean"}},"required":["organizationName","domain"]},"RiskAssessmentDeviceFindingDTO":{"type":"object","properties":{"deviceId":{"type":"string","description":"Deep Scan Target UUID"},"hostname":{"type":"string","nullable":true},"slug":{"type":"string","description":"Finding slug identifier"},"name":{"type":"string"},"severity":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SecuritySeverity"}]},"recommendation":{"type":"string","nullable":true}},"required":["deviceId","hostname","slug","name","severity","recommendation"]},"DomainChangePreviewDTO":{"type":"object","properties":{"findingsCount":{"type":"number"},"tasksCount":{"type":"number"},"syncedTicketsCount":{"type":"number"},"alertsCount":{"type":"number"}},"required":["findingsCount","tasksCount","syncedTicketsCount","alertsCount"]},"DeepScanTargetDTO":{"type":"object","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"macAddress":{"type":"string"},"osVersion":{"type":"string"},"telivyAgentInstalledAt":{"type":"string"},"telivyAgentUninstalledAt":{"type":"string"},"lastHeartBeatAt":{"type":"string"},"status":{"type":"string"},"scanCompleted":{"type":"boolean","description":"Whether all scans for this device have completed"},"agentVersion":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","hostname","macAddress","osVersion","telivyAgentInstalledAt","telivyAgentUninstalledAt","lastHeartBeatAt","status","scanCompleted","agentVersion","createdAt","updatedAt"]},"DeviceScanStatusSummary":{"type":"object","properties":{"deviceId":{"type":"string","description":"Device UUID"},"hostname":{"type":"string","description":"Device hostname"},"status":{"type":"string","description":"Current scan status (e.g. install-success, install-in-progress)"},"scanCompleted":{"type":"boolean","description":"Whether all scans for this device have completed"}},"required":["deviceId","hostname","status","scanCompleted"]},"RejectedDeviceSummary":{"type":"object","properties":{"hostname":{"type":"string","description":"Hostname of the refused device"},"rejectedAt":{"type":"string","description":"When the device was last refused (ISO 8601)","format":"date-time"}},"required":["hostname","rejectedAt"]},"AssessmentScanStatusDTO":{"type":"object","properties":{"totalDevices":{"type":"number","description":"Total number of devices in the assessment"},"completedDevices":{"type":"number","description":"Number of devices that have completed scanning"},"inProgressDevices":{"type":"number","description":"Number of devices still scanning or pending"},"allScansCompleted":{"type":"boolean","description":"True when all devices have completed scanning (also true when there are no devices)"},"devices":{"description":"Per-device scan status breakdown","type":"array","items":{"$ref":"#/components/schemas/DeviceScanStatusSummary"}},"rejectedDevices":{"description":"Devices refused by the trial device limit, newest first, at most 50","type":"array","items":{"$ref":"#/components/schemas/RejectedDeviceSummary"}}},"required":["totalDevices","completedDevices","inProgressDevices","allScansCompleted","devices","rejectedDevices"]},"ReportType":{"type":"string","enum":["executive_security_summary_pdf","telivy_complete_report_pdf","telivy_complete_report_docx","telivy_progress_report_pdf","telivy_progress_report_docx","telivy_external_scan_report_pdf","telivy_network_inventory_report_csv","internal_vulnerabilities_top_pdf","internal_vulnerabilities_executive_pdf","internal_vulnerabilities_network_pdf","internal_vulnerabilities_detailed_csv","applications_security_overview_csv","applications_security_detailed_csv","data_security_sensitive_documents_csv","data_security_detailed_risk_xlsx","telivy_passwords_report_csv","telivy_passwords_reuse_report_csv","telivy_dark_web_report_csv","m365_security_report_pdf","m365_security_data_report_xlsx","gws_security_report_pdf","gws_security_data_report_xlsx","legacy_complete_report_pdf"]},"ApplicationDocumentType":{"type":"string","enum":["benchmark","security_report","risk_calculator","employee_list","telivy_detailed_external_scan_report","telivy_external_scan_report","telivy_progress_report_docx","telivy_progress_report_pdf","telivy_questionnaire_report","augument_detailed_report","augmentt_overview_report","executive_security_summary_pdf","nodeware_executive_report","nodeware_network_report","nodeware_top_vulnerabilities_report","telivy_vulnerabilities_report","m365_security_report","m365_security_data_report","gws_security_report","gws_security_data_report","saas_alerts_detailed_report","saas_alerts_summary_report","phishing_report","telivy_complete_report_pdf","telivy_complete_report_docx","telivy_passwords_report","telivy_passwords_reuse_report","telivy_dark_web_report","telivy_network_inventory_report","actifile_sensitive_documents","actifile_detailed_risk","pii_excel_report_bundle","telivy_all_reports_zip","legacy_complete_report_pdf","telivy_complete_report","augument_report"]},"RiskAssessmentDocumentDTO":{"type":"object","properties":{"id":{"type":"string","description":"Document ID, downloadable with GET /api/v1/security/risk-assessments/{id}/documents/{documentId}"},"documentType":{"allOf":[{"$ref":"#/components/schemas/ApplicationDocumentType"}]},"fileName":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","documentType","fileName","createdAt"]},"RiskAssessmentDocumentsDTO":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/RiskAssessmentDocumentDTO"}},"total":{"type":"number","description":"Number of documents of the assessment across all pages. Page through them with offset and limit."}},"required":["documents","total"]},"CloudConnectionStatus":{"type":"string","enum":["connected","token_error","needs_reauth","disconnected"]},"M365UserLoginFailureDTO":{"type":"object","properties":{"createdDateTime":{"type":"string"},"appDisplayName":{"type":"string"},"ipAddress":{"type":"string"},"clientAppUsed":{"type":"string"},"errorCode":{"type":"number"},"failureReason":{"type":"string"}},"required":["createdDateTime","appDisplayName","ipAddress","clientAppUsed","errorCode","failureReason"]},"M365UserDTO":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"mail":{"type":"string","nullable":true},"userPrincipalName":{"type":"string"},"accountEnabled":{"type":"boolean"},"hasMfa":{"type":"boolean"},"authenticationMethods":{"type":"array","items":{"type":"string"}},"lastSignInDateTime":{"type":"string","nullable":true},"lastNonInteractiveSignInDateTime":{"type":"string","nullable":true},"isInactive":{"type":"boolean"},"jobTitle":{"type":"string","nullable":true},"recentLoginFailures":{"type":"array","items":{"$ref":"#/components/schemas/M365UserLoginFailureDTO"}}},"required":["id","displayName","mail","userPrincipalName","accountEnabled","hasMfa","authenticationMethods","lastSignInDateTime","lastNonInteractiveSignInDateTime","isInactive","jobTitle","recentLoginFailures"]},"M365UsersDataDTO":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/M365UserDTO"}},"totalUsers":{"type":"number"},"usersWithMfa":{"type":"number"},"usersWithoutMfa":{"type":"number"},"disabledAccounts":{"type":"number"},"inactiveAccounts":{"type":"number"},"totalLoginFailures":{"type":"number"}},"required":["users","totalUsers","usersWithMfa","usersWithoutMfa","disabledAccounts","inactiveAccounts","totalLoginFailures"]},"M365UsersResponseDTO":{"type":"object","properties":{"message":{"type":"string","description":"Optional response message for operation status"},"configured":{"type":"boolean","default":false},"connectionStatus":{"nullable":true,"default":null,"allOf":[{"$ref":"#/components/schemas/CloudConnectionStatus"}]},"data":{"nullable":true,"default":null,"type":"object","allOf":[{"$ref":"#/components/schemas/M365UsersDataDTO"}]},"lastSyncedAt":{"format":"date-time","type":"string","nullable":true,"default":null}},"required":["configured","connectionStatus","data","lastSyncedAt"]},"GwsLoginActivityDTO":{"type":"object","properties":{"email":{"type":"string"},"ipAddress":{"type":"string"},"timestamp":{"format":"date-time","type":"string"},"eventNames":{"type":"array","items":{"type":"string"}},"city":{"type":"string","nullable":true},"countryOrRegion":{"type":"string","nullable":true}},"required":["email","ipAddress","timestamp","eventNames","city","countryOrRegion"]},"GwsUserDTO":{"type":"object","properties":{"id":{"type":"string"},"primaryEmail":{"type":"string"},"fullName":{"type":"string"},"isAdmin":{"type":"boolean"},"isDelegatedAdmin":{"type":"boolean"},"suspended":{"type":"boolean"},"archived":{"type":"boolean"},"isEnrolledIn2Sv":{"type":"boolean"},"isEnforcedIn2Sv":{"type":"boolean"},"lastLoginTime":{"format":"date-time","type":"string","nullable":true},"creationTime":{"format":"date-time","type":"string"},"isInactive":{"type":"boolean"},"changePasswordAtNextLogin":{"type":"boolean"},"isMailboxSetup":{"type":"boolean"},"recentLoginActivity":{"type":"array","items":{"$ref":"#/components/schemas/GwsLoginActivityDTO"}}},"required":["id","primaryEmail","fullName","isAdmin","isDelegatedAdmin","suspended","archived","isEnrolledIn2Sv","isEnforcedIn2Sv","lastLoginTime","creationTime","isInactive","changePasswordAtNextLogin","isMailboxSetup","recentLoginActivity"]},"GwsUsersDataDTO":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/GwsUserDTO"}},"totalUsers":{"type":"number"},"adminAccounts":{"type":"number"},"suspendedAccounts":{"type":"number"},"inactiveAccounts":{"type":"number"},"enrolledIn2Sv":{"type":"number"},"notEnrolledIn2Sv":{"type":"number"}},"required":["users","totalUsers","adminAccounts","suspendedAccounts","inactiveAccounts","enrolledIn2Sv","notEnrolledIn2Sv"]},"GwsUsersResponseDTO":{"type":"object","properties":{"message":{"type":"string","description":"Optional response message for operation status"},"configured":{"type":"boolean","default":false},"connectionStatus":{"nullable":true,"default":null,"allOf":[{"$ref":"#/components/schemas/CloudConnectionStatus"}]},"data":{"nullable":true,"default":null,"type":"object","allOf":[{"$ref":"#/components/schemas/GwsUsersDataDTO"}]},"lastSyncedAt":{"format":"date-time","type":"string","nullable":true,"default":null}},"required":["configured","connectionStatus","data","lastSyncedAt"]},"PiiTypeDistributionDTO":{"type":"object","properties":{"piiType":{"type":"string"},"filesCount":{"type":"number"},"matchesCount":{"type":"number"},"totalRisk":{"type":"number"}},"required":["piiType","filesCount","matchesCount","totalRisk"]},"PiiDeviceSummaryDTO":{"type":"object","properties":{"hostname":{"type":"string"},"filesScanned":{"type":"number"},"sensitiveFiles":{"type":"number"},"totalRisk":{"type":"number"}},"required":["hostname","filesScanned","sensitiveFiles","totalRisk"]},"PiiSummaryDataDTO":{"type":"object","properties":{"distributionByType":{"type":"array","items":{"$ref":"#/components/schemas/PiiTypeDistributionDTO"}},"deviceSummaries":{"type":"array","items":{"$ref":"#/components/schemas/PiiDeviceSummaryDTO"}},"totalSensitiveFiles":{"type":"number"},"totalDataRisk":{"type":"number"}},"required":["distributionByType","deviceSummaries","totalSensitiveFiles","totalDataRisk"]},"ScanTimestampsDTO":{"type":"object","properties":{"fromScanTimestamp":{"type":"string"},"toScanTimestamp":{"type":"string"}},"required":["fromScanTimestamp","toScanTimestamp"]},"FindingAdditionalDataType":{"type":"string","enum":["cve"],"description":"Data type discriminator"},"CveAdditionalDataDTO":{"type":"object","properties":{"type":{"description":"Data type discriminator","allOf":[{"$ref":"#/components/schemas/FindingAdditionalDataType"}]},"id":{"type":"string","description":"CVE ID"},"title":{"type":"string","description":"CVE title"},"description":{"type":"string","description":"CVE description"},"score":{"type":"number","description":"CVSS score"},"foundIn":{"type":"object","properties":{"product":{"type":"string"},"version":{"type":"string"}},"required":["product","version"]},"allAffectedProducts":{"description":"All CNA-affected products for this CVE","type":"array","items":{"type":"object"}},"remediation":{"type":"object","description":"Remediation guidance (fix versions, advisory URLs, solution text)"}},"required":["type"]},"DiskEncryptionAdditionalDataDTO":{"type":"object","properties":{"type":{"description":"Data type discriminator","allOf":[{"$ref":"#/components/schemas/FindingAdditionalDataType"}]},"MountPoint":{"type":"string","description":"Mount point path"},"FileSystem":{"type":"string","description":"File system type"},"IsEncrypted":{"type":"boolean","description":"Whether disk is encrypted"}},"required":["type","MountPoint","IsEncrypted"]},"BrowserPasswordAdditionalDataDTO":{"type":"object","properties":{"type":{"description":"Data type discriminator","allOf":[{"$ref":"#/components/schemas/FindingAdditionalDataType"}]},"breached":{"type":"boolean","description":"Whether password was found in breach database"},"browsers":{"description":"List of browsers where password was found","type":"array","items":{"type":"string"}}},"required":["type","breached","browsers"]},"ConnectedPortDTO":{"type":"object","properties":{"port":{"type":"number","description":"Port number"},"potentialServices":{"type":"string","description":"Potential services running on this port"}},"required":["port","potentialServices"]},"DeviceScanDataDTO":{"type":"object","properties":{"connectedPorts":{"description":"Connected ports","type":"array","items":{"$ref":"#/components/schemas/ConnectedPortDTO"}}}},"OpenPortsAdditionalDataDTO":{"type":"object","properties":{"type":{"description":"Data type discriminator","allOf":[{"$ref":"#/components/schemas/FindingAdditionalDataType"}]},"data":{"description":"Device scan data","allOf":[{"$ref":"#/components/schemas/DeviceScanDataDTO"}]}},"required":["type"]},"GenericAdditionalDataDTO":{"type":"object","properties":{"type":{"description":"Data type discriminator","allOf":[{"$ref":"#/components/schemas/FindingAdditionalDataType"}]},"data":{"type":"object","additionalProperties":true,"description":"Additional properties"}},"required":["type"]},"FindingValue":{"type":"object","properties":{"id":{"type":"string","description":"Finding value ID"},"value":{"type":"string","description":"Raw value"},"formattedValue":{"type":"string","description":"Formatted value for display","nullable":true},"valueHash":{"type":"string","description":"Value hash for deduplication"},"additionalData":{"description":"Additional data specific to finding type","nullable":true,"oneOf":[{"$ref":"#/components/schemas/CveAdditionalDataDTO"},{"$ref":"#/components/schemas/DiskEncryptionAdditionalDataDTO"},{"$ref":"#/components/schemas/BrowserPasswordAdditionalDataDTO"},{"$ref":"#/components/schemas/OpenPortsAdditionalDataDTO"},{"$ref":"#/components/schemas/GenericAdditionalDataDTO"}],"discriminator":{"propertyName":"type","mapping":{"cve":"#/components/schemas/CveAdditionalDataDTO","disk_encryption":"#/components/schemas/DiskEncryptionAdditionalDataDTO","browser_password":"#/components/schemas/BrowserPasswordAdditionalDataDTO","open_ports":"#/components/schemas/OpenPortsAdditionalDataDTO","generic":"#/components/schemas/GenericAdditionalDataDTO"}}},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"}},"required":["id","value","formattedValue","valueHash","additionalData","createdAt"]},"TaskSourceType":{"type":"string","enum":["TELIVY","TENTACLE","RISK_DECISION"],"description":"Source system type"},"TaskStatus":{"type":"string","enum":["OPEN","IN_PROGRESS","RESOLVED","CLOSED"],"description":"Task status"},"TaskResponseDTO":{"type":"object","properties":{"message":{"type":"string","description":"Optional response message for operation status"},"id":{"type":"string","description":"Task ID"},"applicationId":{"type":"string","description":"Application ID"},"sourceType":{"description":"Source system type","allOf":[{"$ref":"#/components/schemas/TaskSourceType"}]},"sourceEntityId":{"type":"string","description":"Source entity ID"},"sourceEntityMeta":{"type":"object","additionalProperties":true,"nullable":true,"description":"Source entity metadata"},"status":{"description":"Task status","allOf":[{"$ref":"#/components/schemas/TaskStatus"}]},"title":{"type":"string","description":"Task title"},"description":{"type":"string","description":"Task description"},"recommendation":{"type":"string","nullable":true,"description":"Recommendation"},"technicalDetails":{"type":"string","nullable":true,"description":"Technical details"},"taskNumber":{"type":"string","description":"Task number"},"resolutionTargetDate":{"type":"string","nullable":true,"description":"Resolution target date","format":"date-time"},"createdAt":{"format":"date-time","type":"string","description":"Created at timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Updated at timestamp"}},"required":["id","applicationId","sourceType","sourceEntityId","sourceEntityMeta","status","title","description","recommendation","technicalDetails","taskNumber","resolutionTargetDate","createdAt","updatedAt"]},"FindingDecisionType":{"type":"string","enum":["ACCEPTED","RESOLVED_COMPENSATING_CONTROL","RESOLVED_IN_PSA"]},"DecisionUserDTO":{"type":"object","properties":{"email":{"type":"string"}},"required":["email"]},"FindingDecisionResponseDTO":{"type":"object","properties":{"message":{"type":"string","description":"Optional response message for operation status"},"id":{"type":"string"},"decisionType":{"allOf":[{"$ref":"#/components/schemas/FindingDecisionType"}]},"findingFingerprint":{"type":"string"},"applicationId":{"type":"string"},"reason":{"type":"string"},"userId":{"type":"string","nullable":true,"description":"Null for system-authored decisions (e.g. RESOLVED_IN_PSA)."},"user":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/DecisionUserDTO"}]},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","decisionType","findingFingerprint","applicationId","reason","userId","user","expiresAt","createdAt","updatedAt"]},"FindingWithTaskResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Finding ID"},"timestampGroup":{"type":"string","description":"Timestamp group for finding grouping (e.g., weekly)"},"identifier":{"type":"string","nullable":true,"description":"Source identifier (device ID, domain name, or cloud identifier)"},"slug":{"type":"string","description":"Finding slug identifier"},"value":{"description":"Finding value with additional data","allOf":[{"$ref":"#/components/schemas/FindingValue"}]},"valueId":{"type":"string","description":"Finding value ID"},"applicationId":{"type":"string","description":"Application ID"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"},"task":{"description":"Task linked to the finding, when applicable","allOf":[{"$ref":"#/components/schemas/TaskResponseDTO"}]},"source":{"type":"string","description":"Finding source type"},"decision":{"description":"Finding decision if present","allOf":[{"$ref":"#/components/schemas/FindingDecisionResponseDTO"}]},"cisCategory":{"type":"string","description":"CIS category when available"},"controlId":{"type":"string","description":"Control identifier when available"}},"required":["id","timestampGroup","identifier","slug","value","valueId","applicationId","createdAt","updatedAt"]},"ProgressReportDTO":{"type":"object","properties":{"new":{"type":"array","items":{"$ref":"#/components/schemas/FindingWithTaskResponseDTO"}},"resolved":{"type":"array","items":{"$ref":"#/components/schemas/FindingWithTaskResponseDTO"}},"regressed":{"type":"array","items":{"$ref":"#/components/schemas/FindingWithTaskResponseDTO"}},"open":{"type":"array","items":{"$ref":"#/components/schemas/FindingWithTaskResponseDTO"}}},"required":["new","resolved","regressed","open"]},"FindingsProgressReportResponseDTO":{"type":"object","properties":{"message":{"type":"string","description":"Optional response message for operation status"},"scans":{"$ref":"#/components/schemas/ScanTimestampsDTO"},"report":{"$ref":"#/components/schemas/ProgressReportDTO"}},"required":["scans","report"]},"AgentVersionsDTO":{"type":"object","properties":{"windows":{"type":"string"},"mac":{"type":"string"}},"required":["windows","mac"]},"WebhookEvent":{"type":"string","enum":["ASSESSMENT_STATUS_CHANGED","ALERT_RAISED","SCAN_COMPLETED","SECURITY_GRADE_CHANGED","AGENT_INSTALLED","AGENT_UNINSTALLED","TEST"]},"WebhookEnvelopeMetadataDTO":{"type":"object","properties":{"eventType":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"}]},"timestamp":{"type":"string","format":"date-time","description":"Time of this delivery"},"webhookId":{"type":"string","description":"Webhook subscription ID"},"attemptNumber":{"type":"number","description":"Delivery attempt for this subscription, starting at 1. Retries resend the same data with a higher attemptNumber."},"encrypted":{"type":"boolean","description":"When true, `data` is a base64 AES-256-CBC ciphertext of the JSON payload and `iv` carries the base64 IV. The key is HMAC-SHA256(subscription secret, \"encryption-key\")."}},"required":["eventType","timestamp","webhookId","attemptNumber","encrypted"]},"WebhookEnvelopeDTO":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/WebhookEnvelopeMetadataDTO"},"data":{"description":"Event payload. Its schema depends on metadata.eventType. A base64 string when metadata.encrypted is true.","oneOf":[{"type":"object"},{"type":"string"}]},"iv":{"type":"string","description":"Base64 IV, present when encrypted"}},"required":["metadata","data"]},"ScanCompletedWebhookData":{"type":"object","properties":{"agencyId":{"type":"string","description":"Agency that owns the assessment"},"assessmentId":{"type":"string","description":"Assessment ID, the `id` used by the External Scans and Risk Assessments endpoints"},"securityScanId":{"type":"string","description":"External security scan ID"},"domain":{"type":"string","description":"Scanned domain"},"securityGrade":{"description":"Overall grade after this scan","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"completedAt":{"format":"date-time","type":"string"}},"required":["agencyId","assessmentId","securityScanId","domain","securityGrade","completedAt"]},"SecurityGradeChangedWebhookData":{"type":"object","properties":{"agencyId":{"type":"string","description":"Agency that owns the assessment"},"assessmentId":{"type":"string","description":"Assessment ID, the `id` used by the External Scans and Risk Assessments endpoints"},"securityScanId":{"type":"string","description":"External security scan ID"},"domain":{"type":"string","description":"Scanned domain"},"previousGrade":{"nullable":true,"description":"Grade before the change, null on the first graded scan","allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"grade":{"allOf":[{"$ref":"#/components/schemas/SecurityGrade"}]},"changedAt":{"format":"date-time","type":"string"}},"required":["agencyId","assessmentId","securityScanId","domain","previousGrade","grade","changedAt"]},"AgentLifecycleWebhookData":{"type":"object","properties":{"agencyId":{"type":"string","description":"Agency that owns the assessment"},"assessmentId":{"type":"string","description":"Risk assessment ID, the `id` used by the Risk Assessments endpoints"},"deviceId":{"type":"string","description":"Device ID"},"hostname":{"type":"string","nullable":true},"osVersion":{"type":"string","nullable":true},"agentVersion":{"type":"string","nullable":true},"occurredAt":{"format":"date-time","type":"string","description":"When Telivy recorded the install or uninstall"}},"required":["agencyId","assessmentId","deviceId","hostname","osVersion","agentVersion","occurredAt"]}}}}