openapi: 3.1.0
info:
version: 0.1.0
title: References
description: |
API for CybelAngel's Platform.
Authentication uses standard [OAuth2 Bearer Tokens](https://tools.ietf.org/html/rfc6750).
[Activate your API access](docs/Activate-API-service.md) to obtain your credentials.
You will be communicated a client `client_id` and a `client_secret` that will allow you to fetch tokens for our API.
These tokens expire 24 hours.
Here is a simple example of how to fetch such a token with curl:
```shell
curl -XPOST https://auth.cybelangel.com/oauth/token -H 'content-type: application/json' -d '{"client_id": "client_id", "client_secret": "client_secret", "audience": "https://platform.cybelangel.com/", "grant_type": "client_credentials"}'
```
The received access token can then be used as a Bearer token to request our API.
contact:
email: support@cybelangel.com
license:
url: 'https://cybelangel.com/'
name: Proprietary
servers:
- url: 'https://platform.cybelangel.com/api'
paths:
/v1/reports/permissions:
get:
tags:
- Reports
summary: Get user permissions for reports
description: |
Retrieves the list of permissions that the authenticated user has for reports.
This endpoint requires user authentication.
operationId: getReportPermissions
responses:
'200':
description: Successfully retrieved user permissions
content:
application/json:
schema:
type: array
items:
type: string
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token: []
servers:
- url: 'https://platform.cybelangel.com/api'
/v2/reports:
get:
tags:
- Incident reports
summary: Get reports (V2)
description: Return the list of reports between the specified dates. The range between start-date and end-date must be less than or equal to 1 year The reports are returned in ascending order by date.
operationId: get-v2-reports
parameters:
- name: start-date
in: query
description: Filter the reports that have been sent before this date
required: true
schema:
type: string
format: date-time
examples:
- '2021-10-15T13:45:30'
- name: end-date
in: query
description: Filter the reports that have been sent after this date
required: true
schema:
type: string
format: date-time
examples:
- '2009-06-18T13:45:30'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
reports:
type: array
items:
$ref: '#/components/schemas/Report-v2'
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.read
servers:
- url: 'https://platform.cybelangel.com/api'
x-internal: false
'/v2/reports/{report-id}':
get:
tags:
- Incident reports
summary: Get reports by ID (V2)
description: Return a report with a particular ID.
operationId: get-v2-reports-by-id
parameters:
- name: report-id
in: path
description: UUID of the report
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report-v2'
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
description: Report can't be found
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.read
servers:
- url: 'https://platform.cybelangel.com/api'
x-internal: false
'/v1/reports/{report-id}/mirror':
get:
tags:
- Incident reports
summary: Get mirror details of a report (by ID)
description: |
Get mirror details information about the report identified by `report-id`.
Your teams can leverage this API endpoint to retrieve:
- **Russian Market incident report attachments**, as part of our Dark Web Monitoring module
- **Sensitive documents downloaded through the Access to Cache** feature of our Data Breach Prevention module
**Recommendation**: Upgrade your connector to query both the "attachments" endpoint and this one to ensure you are always receiving all available data.
operationId: get-mirror-by-report-id
parameters:
- name: report-id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReportMirror'
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.read
servers:
- url: 'https://platform.cybelangel.com/api'
'/v1/reports/{report-id}/mirror/csv':
get:
tags:
- Incident reports
summary: Get mirror details in CSV of a report (by ID)
description: |
Get a csv containing information about files related to report identified by `report-id`.
Your teams can leverage this API endpoint to retrieve:
- **Russian Market incident report attachments**, as part of our Dark Web Monitoring module
- **Sensitive documents downloaded through the Access to Cache** feature of our Data Breach Prevention module
**Recommendation**: Upgrade your connector to query both the "attachments" endpoint and this one to ensure you are always receiving all available data.
operationId: get-mirror-csv-by-report-id
parameters:
- name: report-id
in: path
required: true
schema:
type: string
format: uuid
responses:
'302':
description: Redirect to the csv file
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.read
servers:
- url: 'https://platform.cybelangel.com/api'
'/v1/reports/{report-id}/mirror/archive':
get:
tags:
- Incident reports
summary: Get archive from report (by ID)
description: |
Get the archive containing files related to report identified by `report-id`.
Your teams can leverage this API endpoint to retrieve:
- **Russian Market incident report attachments**, as part of our Dark Web Monitoring module
- **Sensitive documents downloaded through the Access to Cache** feature of our Data Breach Prevention module
**Recommendation**: Upgrade your connector to query both the "attachments" endpoint and this one to ensure you are always receiving all available data.
operationId: get-mirror-archive-by-report-id
parameters:
- name: report-id
in: path
required: true
schema:
type: string
format: uuid
responses:
'302':
description: Redirect to the archive file
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.read
servers:
- url: 'https://platform.cybelangel.com/api'
'/v1/reports/{report-id}/status':
put:
tags:
- Incident reports
summary: Update status of a report
description: Update status of a specific report identified by `report-id`
operationId: update-report-status-by-report-id
parameters:
- name: report-id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/ReportStatus'
required:
- status
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
result:
type: string
examples:
- updated
id:
type: string
description: The id of the report
format: uuid
examples:
- 670e7227-74c9-4579-b6e3-f91ad0169a08
status:
$ref: '#/components/schemas/ReportStatus'
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.move
servers:
- url: 'https://platform.cybelangel.com/api'
/v1/reports/status:
post:
tags:
- Incident reports
summary: Update multiple statuses (bulk)
description: Update multiple reports statuses
operationId: update-multiple-reports-statuses
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/ReportStatus'
ids:
type: array
items:
type: string
format: uuid
examples:
- 670e7227-74c9-4579-b6e3-f91ad0169a08
required:
- status
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
updated:
type: integer
examples:
- 1
total:
type: integer
description: Number of updated reports
examples:
- 1
required:
- updated
- total
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.move
servers:
- url: 'https://platform.cybelangel.com/api'
x-codegen-request-body-name: body
'/v1/reports/{report-id}/comments':
get:
tags:
- Incident reports
summary: Get comments of a report
description: Get the list of comments on a specific report
operationId: get-report-comments
parameters:
- name: report-id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description: Total number of comments returned
examples:
- 1
new:
type: integer
description: Number of comments which are new to current user
examples:
- 0
comments:
type: array
items:
$ref: '#/components/schemas/ReportComment'
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports_global_comments.read
servers:
- url: 'https://platform.cybelangel.com/api'
post:
tags:
- Incident reports
summary: Post a comment on a report
description: Create a new comments attached to a specific report
operationId: post-report-comments
parameters:
- name: report-id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
content:
type: string
examples:
- This is a comment message
discussion_id:
type: string
description: Deprecated property. The discussion_id will be ignored. The discussion_id is computed automatically.
parent_id:
type:
- string
- 'null'
description: 'Defining the id of the previous comment if it''s a reply, null for top-level comments'
format: uuid
examples:
- 3500bb64-6081-4cf5-8e6f-dca82dab4983
assigned:
type: boolean
description: boolean describing if this message was assigned to the analysts
required:
- content
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddReportCommentResponse'
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports_global_comments.write
servers:
- url: 'https://platform.cybelangel.com/api'
'/v1/reports/{report-id}/attachments/{attachment-id}':
get:
tags:
- Incident reports
summary: Get Attachments
description: Get an attachment on a specific report
operationId: get-attachments-by-report-id
parameters:
- name: report-id
in: path
required: true
schema:
type: string
format: uuid
- name: attachment-id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/octet-stream:
schema:
type: string
contentMediaType: application/octet-stream
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.read
servers:
- url: 'https://platform.cybelangel.com/api'
'/v1/reports/{report-id}/pdf':
get:
tags:
- Incident reports
summary: Get PDF version of a report (by ID)
description: Return a specified report as a PDF file
operationId: get-pdf-by-report-id
parameters:
- name: report-id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/pdf:
schema:
type: string
contentMediaType: application/octet-stream
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.read
servers:
- url: 'https://platform.cybelangel.com/api'
/v1/reports/remediation-request:
post:
tags:
- Incident reports
summary: Create a Remediation Request
description: Create a remediation request
operationId: create-remediation-request
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
report_id:
type: string
format: uuid
examples:
- d334220f-0f41-48e5-b01a-129d2b0a73f5
requester_email:
type: string
format: email
examples:
- john.doe@corp.com
requester_fullname:
type: string
examples:
- John Doe
required:
- report_id
- requester_email
- requester_fullname
responses:
'201':
description: OK
content:
application/json:
schema:
type: object
properties:
report_id:
type: string
format: uuid
examples:
- d334220f-0f41-48e5-b01a-129d2b0a73f5
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- reports.read
servers:
- url: 'https://platform.cybelangel.com/api'
x-codegen-request-body-name: body
/v1/reports_credentials/count:
get:
tags:
- Credential watchlist
summary: Get Number of Credentials Reports
description: |-
Return the number of credentials reports matching the specified filters.
⚠️ **Account Takeover Prevention module is required.**
operationId: get-reports-credentials-count
parameters:
- name: query
in: query
description: A text to look up in the credentials reports.
schema:
type: string
- name: start
in: query
schema:
$ref: '#/components/schemas/Date'
- name: end
in: query
schema:
$ref: '#/components/schemas/Date'
- name: email
in: query
schema:
type: string
- name: severity
in: query
style: form
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
all:
type: integer
description: Total number of reports matching these criteria (without `draft` one)
examples:
- 1
discarded:
type: integer
description: Total number of *discarded* reports matching these criteria
examples:
- 1
draft:
type: integer
description: Total number of *draft* reports matching these criteria if user has permission to see them
examples:
- 1
in_progress:
type: integer
description: Total number of *in_progress* reports matching these criteria
examples:
- 1
open:
type: integer
description: Total number of *open* reports matching these criteria
examples:
- 1
resolved:
type: integer
description: Total number of *resolved* reports matching these criteria
examples:
- 1
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token: []
servers:
- url: 'https://platform.cybelangel.com/api'
/v1/credentials:
get:
tags:
- Credential watchlist
summary: Get credential watchlist
description: |
Return the list of monitored credentials matching the specified filters.
⚠️ **Account Takeover Protection module is required.**
operationId: get-credential-watchlist
parameters:
- name: status
in: query
style: form
explode: false
schema:
type: array
default:
- compromised
- addressed
items:
$ref: '#/components/schemas/CredentialStatus'
- name: start
in: query
schema:
$ref: '#/components/schemas/Date'
- name: end
in: query
schema:
$ref: '#/components/schemas/Date'
- name: email
in: query
schema:
type: string
- name: skip
in: query
description: The number of results that are skipped.
schema:
type: integer
default: 0
- name: limit
in: query
description: The number of results that are returned.
schema:
type: integer
default: 10
- name: sort_by
in: query
description: The field on which we sort the results.
schema:
type: string
default: last_detection_date
- name: order
in: query
description: The sort order.
schema:
type: string
enum:
- asc
- desc
default: desc
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Credential'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- credentials.read
servers:
- url: 'https://platform.cybelangel.com/api'
/v1/credentials/count:
get:
tags:
- Credential watchlist
summary: Get volume of credentials
description: |
Return the number of credentials matching the specified filters.
⚠️ **Account Takeover Protection module is required.**
operationId: get-volume-of-credentials
parameters:
- name: start
in: query
schema:
$ref: '#/components/schemas/Date'
- name: end
in: query
schema:
$ref: '#/components/schemas/Date'
- name: email
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
addressed:
type: integer
all:
type: integer
compromised:
type: integer
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token: []
servers:
- url: 'https://platform.cybelangel.com/api'
/v1/credentials/export:
get:
tags:
- Credential watchlist
summary: Get export credential watchlist (CSV file)
description: |
Export a CSV that contains the list of Account Takeover Protection reports matching the specified filters.
⚠️ **Account Takeover Protection module is required.**
operationId: get-export-credential-watchlist
parameters:
- name: email
in: query
schema:
type: string
examples:
- john.doe@acme.fr
- name: end
in: query
schema:
$ref: '#/components/schemas/Date'
- name: start
in: query
schema:
$ref: '#/components/schemas/Date'
- name: status
in: query
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ReportStatus'
responses:
'200':
description: OK
content:
text/csv:
schema:
type: string
examples:
- |
Email,Password,Incident id,Source,Category,Severity,Published date,Keywords
john.doe@acme.fr,MZIzNDU2,333e67ff-2aef-4367-8b62-8fb2c74efe3e,Gist.githubusercontent.com,paste,4,14/12/2020,['test.com']
jane.doe@acme.fr,DZlJDK34,333e67ff-2aef-4367-8b62-8fb2c74efe3e,Gist.githubusercontent.com,paste,4,14/12/2020,['test.com']
examples:
default:
value: |
Email,Password,Incident id,Source,Category,Severity,Published date,Keywords
john.doe@acme.fr,MZIzNDU2,333e67ff-2aef-4367-8b62-8fb2c74efe3e,Gist.githubusercontent.com,paste,4,14/12/2020,['test.com']
jane.doe@acme.fr,DZlJDK34,333e67ff-2aef-4367-8b62-8fb2c74efe3e,Gist.githubusercontent.com,paste,4,14/12/2020,['test.com']
headers:
Content-Disposition:
schema:
type: string
example: attachment; filename=credentials.csv
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- credentials.export
servers:
- url: 'https://platform.cybelangel.com/api'
/v1/credentials/status:
post:
tags:
- Credential watchlist
summary: Update status of credential
description: |
Update status of the specified credentials
⚠️ **Account Takeover Protection module is required.**
operationId: update-status-of-credential
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ids:
type: array
description: The ids of the credentials to update
items:
type: string
format: uuid
examples:
- 670e7227-74c9-4579-b6e3-f91ad0169a08
status:
$ref: '#/components/schemas/CredentialStatus'
required:
- ids
- status
responses:
'200':
description: OK
content:
application/json:
schema:
type: integer
description: Number of updated credentials
examples:
- 27
examples:
default:
value: 27
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'500':
$ref: '#/components/responses/Error500'
security:
- bearer_token:
- credentials.move
servers:
- url: 'https://platform.cybelangel.com/api'
x-codegen-request-body-name: body
/v1/domains:
get:
tags:
- Domain watchlist
summary: Get Domain watchlist
description: |
Return the list of the monitored domains (domain watchlist), in descending order.
⚠️ **Domain Protection module is required**
operationId: get-domain-watchlist
parameters:
- name: status
in: query
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/DomainStatus'
- name: min-date
in: query
schema:
type: string
format: date
- name: max-date
in: query
schema:
type: string
format: date
- name: query
in: query
description: A text to look up in the domains.
schema:
type: string
- name: skip
in: query
description: The number of results that are skipped.
schema:
type: integer
default: 0
- name: limit
in: query
description: The number of results that are returned.
schema:
type: integer
default: 100
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description: Total number of domains matching these criteria
examples:
- 42
results:
type: array
description: A list of domains (in desc order)
items:
$ref: '#/components/schemas/Domain'
'400':
$ref: '#/
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybelangel/refs/heads/main/openapi/cybelangel-platform-reports-openapi.yml