openapi: 3.2.0
info:
description: "## Overview\nThe Riot API is a (mostly) RESTful API. Typically, both POST bodies and responses are JSON-encoded.\n\n## Base URL\nThe base URL for the Riot API is https://public-api.tryriot.com/v1.\n\n## Authentication\n\nEvery API request must include an authentication key in the `x-api-key` header.\n\nTo acquire an API key, customers must contact the technical team.\n\n## Authorization\n\nEach key is scoped to either a single organization or a single workspace, ensuring that access and data are restricted to the appropriate entity.\n\n- **Organization-scoped keys** can access any workspace belonging to the organization. Endpoints that take a `workspace_id` parameter accept any workspace of that organization.\n- **Workspace-scoped keys** are restricted to a single workspace. Requests targeting a different workspace through a `workspace_id` parameter are rejected with a **403** status code.\n\nKeys can also be limited by specific scopes, such as `awareness:read`, `simulation:read`, `breach:read`, or `workspace:read` which define the endpoints that can be accessed.\n\n## Pagination\n\nAll endpoints that return an array of objects support cursor-based pagination.\nEven for endpoints with a limited number of items (e.g., `/courses`), pagination is available to maintain consistency across all endpoints.\n\n**Request**\n\n- **`limit`** (query parameter): Maximum number of items per page. The maximum allowed value is `100`, with a default of `50`.\n- **`cursor`** (query parameter): Pagination cursor for retrieving the next page of results. On the first request, omit this parameter. For subsequent requests, pass the `next_cursor` value from the previous response's `metadata` object unchanged.\n\n**Response**\n\nPaginated responses include a `metadata` object alongside the `data` array:\n\n```json\n{\n \"data\": [...],\n \"metadata\": {\n \"next_cursor\": \"eyJpZCI6...\",\n \"limit\": 50\n }\n}\n```\n\n- **`next_cursor`**: The cursor to pass in the next request. `null` when there are no more pages.\n- **`limit`**: The maximum number of items per page.\n\n**Link header**\n\nPaginated responses also include a standard `link` response header with `rel=\"next\"` when there are more results.\nThis header contains a fully constructed URL for the next page, including the cursor and any query parameters from the original request.\n\nExample: `<https://public-api.tryriot.com/v1/groups?workspace_id=abc&cursor=eyJpZCI6...>; rel=\"next\"`\n\nWhen the last page is reached, the `link` header is omitted.\n\n## Rate limits\n\nRate limiting is enforced across all API endpoints and is scoped by the authentication key. This ensures fair usage and prevents abuse of the system.\n\n- **Scope**: Rate limits are applied **per key**, meaning all requests made with the same key share the same limit.\n- **Configuration**: Specific rate limits are defined and managed by the technical team.\n- **Behavior**: The rate limiting mechanism operates within fixed time intervals. If the limit is exceeded within a given interval, further requests will return **429** status code until the next interval begins.\n\n## Webhooks\n\nRiot can push server-to-server events to a customer-configured HTTPS endpoint when something happens in a workspace (e.g. an inbox email being classified).\n\nThe implementation follows the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks), so any Standard-Webhooks-compatible library can verify and consume payloads without bespoke code.\n\n**Envelope**\n\nEvery event body is wrapped in the Standard Webhooks envelope:\n\n```json\n{\n \"type\": \"inbox_email_analysis.classified\",\n \"timestamp\": \"2026-06-03T08:42:11.812Z\",\n \"data\": { /* event-specific payload */ }\n}\n```\n\n**Headers**\n\n- `webhook-id`: unique event identifier. The same id is sent on every retry; use it as an idempotency key.\n- `webhook-timestamp`: Unix timestamp (seconds) of the delivery attempt.\n- `webhook-signature`: space-delimited list of `v1,<base64-hmac>` signatures, one per active endpoint secret, computed over `<webhook-id>.<webhook-timestamp>.<body>` using HMAC-SHA256 with the raw request body. Multiple signatures support zero-downtime secret rotation.\n\n**Delivery**\n\n- Method: `POST` with `content-type: application/json`.\n- Success: any `2xx` status returned within 15 seconds.\n- Failure: any non-`2xx` status, connection error, or timeout. Retries follow the Standard Webhooks recommended schedule: 10 attempts spread over ~75 hours (immediate, 5s, 5m, 30m, 2h, 5h, 10h, 14h, 20h, 24h).\n\n**Endpoint management**\n\nContact your account manager to add or rotate an endpoint. Self-service management is not available for now.\n\n**Compatibility**\n\nEvent payloads evolve over time. To stay forward-compatible, **ignore unknown fields** in the `data` object — new fields may be added at any time without notice and without a version bump.\n\nThe following changes to an existing event type are **not** considered breaking:\n\n- Adding a new field to the payload.\n- Adding a new event type.\n\nThe following changes **are** breaking and will be shipped under a new event type (e.g. `inbox_email_analysis.classified.v2`), leaving the original event type unchanged:\n\n- Removing or renaming a field.\n- Changing the type of a field.\n- Changing the meaning of an existing value (e.g. repurposing an enum value).\n\n**Event types**\n\nSee the **Webhook Events** section in the sidebar for the list of supported event types and their payload schemas.\n"
title: Riot Simulation API
version: v1
servers:
- url: https://public-api.tryriot.com/
security:
- apiKeyAuth: []
tags:
- description: Provides data about phishing campaigns, corresponding attacks and related events.
name: Simulation
paths:
/v1/attack_login_domains:
get:
description: 'Returns the attack login domains assigned to a workspace, sorted by name. These domains are randomly selected as the link for each attack.
**Scopes required:**
- simulation:read'
operationId: attack_login_domains_get_attack_login_domain_paginated_XU5W4YI
parameters:
- in: header
name: x-item-limit
required: false
schema:
default: 50
deprecated: true
maximum: 100
minimum: 1
type: integer
- in: header
name: x-next-cursor
required: false
schema:
deprecated: true
type: string
- in: query
name: cursor
required: false
schema:
type: string
- in: query
name: limit
required: false
schema:
default: 50
maximum: 100
minimum: 1
type: integer
- in: query
name: workspace_id
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/PaginatedAttackLoginDomainPayload'
type: array
metadata:
properties:
limit:
type: integer
next_cursor:
type:
- string
- 'null'
required:
- next_cursor
- limit
type: object
required:
- data
type: object
description: Attack login domains list
headers:
link:
description: 'Link header with rel="next" pointing to the next page URL. Format: `<url>; rel="next"`'
required: false
schema:
type: string
x-next-cursor:
description: Pagination cursor for the next page
required: false
schema:
deprecated: true
type: string
'401':
$ref: '#/components/responses/UnauthorizedErrorResponse'
'403':
$ref: '#/components/responses/ForbiddenErrorResponse'
'422':
$ref: '#/components/responses/UnprocessableContentErrorResponse'
'429':
$ref: '#/components/responses/RateLimitExceededErrorResponse'
security:
- apiKeyAuth:
- simulation:read
summary: List attack login domains
tags:
- Simulation
x-riot-team-ownership: simulation
/v1/campaigns:
get:
description: 'Lists the campaigns for a workspace with its cycles, sorted by their creation date in descending order (most recent entries first).
A campaign cycle forms a group of attacks sent at a period of time. Periods of two cycles can''t overlap.
Recurring campaigns usually have multiple cycles, whereas one-off campaigns usually have only one.
**Scopes required:**
- simulation:read'
operationId: campaigns_get_paginated_CWCTX3I
parameters:
- in: header
name: x-item-limit
required: false
schema:
default: 50
deprecated: true
maximum: 100
minimum: 1
type: integer
- in: header
name: x-next-cursor
required: false
schema:
deprecated: true
type: string
- in: query
name: cursor
required: false
schema:
type: string
- in: query
name: limit
required: false
schema:
default: 50
maximum: 100
minimum: 1
type: integer
- in: query
name: workspace_id
required: true
schema:
format: uuid
type: string
- explode: false
in: query
name: status
required: false
schema:
items:
$ref: '#/components/schemas/CampaignStatusSchema'
minItems: 1
type: array
uniqueItems: true
style: form
- in: query
name: created_after
required: false
schema:
format: date-time
type: string
- in: query
name: created_before
required: false
schema:
format: date-time
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/PaginatedCampaignPayload'
type: array
metadata:
properties:
limit:
type: integer
next_cursor:
type:
- string
- 'null'
required:
- next_cursor
- limit
type: object
required:
- data
type: object
description: Campaigns list
headers:
link:
description: 'Link header with rel="next" pointing to the next page URL. Format: `<url>; rel="next"`'
required: false
schema:
type: string
x-next-cursor:
description: Pagination cursor for the next page
required: false
schema:
deprecated: true
type: string
'401':
$ref: '#/components/responses/UnauthorizedErrorResponse'
'403':
$ref: '#/components/responses/ForbiddenErrorResponse'
'422':
$ref: '#/components/responses/UnprocessableContentErrorResponse'
'429':
$ref: '#/components/responses/RateLimitExceededErrorResponse'
security:
- apiKeyAuth:
- simulation:read
summary: List campaigns
tags:
- Simulation
x-riot-team-ownership: simulation
/v1/campaigns/statistics:
get:
description: 'Retrieves statistics about campaigns in a workspace including attack events counts.
Description of the events can be found at https://docs.tryriot.com/api-reference/simulation/list-attacks#response-type
**Scopes required:**
- simulation:read'
operationId: campaigns_get_statistics_CWCTX3I
parameters:
- in: query
name: workspace_id
required: true
schema:
format: uuid
type: string
- in: query
name: campaign_id
required: false
schema:
format: uuid
type: string
- in: query
name: campaign_cycle_id
required: false
schema:
format: uuid
type: string
- in: query
name: created_after
required: false
schema:
format: date-time
type: string
- in: query
name: created_before
required: false
schema:
format: date-time
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/CampaignsStatisticsPayload'
required:
- data
type: object
description: Campaign statistics
'401':
$ref: '#/components/responses/UnauthorizedErrorResponse'
'403':
$ref: '#/components/responses/ForbiddenErrorResponse'
'422':
$ref: '#/components/responses/UnprocessableContentErrorResponse'
'429':
$ref: '#/components/responses/RateLimitExceededErrorResponse'
security:
- apiKeyAuth:
- simulation:read
summary: Get campaigns statistics
tags:
- Simulation
x-riot-team-ownership: simulation
/v1/campaigns/{campaign_id}/attacks:
get:
description: 'Retrieves a list of attacks of a campaign with associated events, sorted by their creation date in descending order (most recent entries first).
**Scopes required:**
- simulation:read'
operationId: attacks_get_paginated_KCLEOEQ
parameters:
- in: header
name: x-item-limit
required: false
schema:
default: 50
deprecated: true
maximum: 100
minimum: 1
type: integer
- in: header
name: x-next-cursor
required: false
schema:
deprecated: true
type: string
- in: query
name: cursor
required: false
schema:
type: string
- in: query
name: limit
required: false
schema:
default: 50
maximum: 100
minimum: 1
type: integer
- in: path
name: campaign_id
required: true
schema:
format: uuid
type: string
- in: query
name: workspace_id
required: true
schema:
format: uuid
type: string
- in: query
name: campaign_cycle_id
required: false
schema:
format: uuid
type: string
- in: query
name: created_after
required: false
schema:
format: date-time
type: string
- in: query
name: created_before
required: false
schema:
format: date-time
type: string
- in: query
name: is_tricked
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/PaginatedAttackPayload'
type: array
metadata:
properties:
limit:
type: integer
next_cursor:
type:
- string
- 'null'
required:
- next_cursor
- limit
type: object
required:
- data
type: object
description: Attacks list
headers:
link:
description: 'Link header with rel="next" pointing to the next page URL. Format: `<url>; rel="next"`'
required: false
schema:
type: string
x-next-cursor:
description: Pagination cursor for the next page
required: false
schema:
deprecated: true
type: string
'401':
$ref: '#/components/responses/UnauthorizedErrorResponse'
'403':
$ref: '#/components/responses/ForbiddenErrorResponse'
'422':
$ref: '#/components/responses/UnprocessableContentErrorResponse'
'429':
$ref: '#/components/responses/RateLimitExceededErrorResponse'
security:
- apiKeyAuth:
- simulation:read
summary: List attacks
tags:
- Simulation
x-riot-team-ownership: simulation
components:
schemas:
CampaignsStatisticsPayload:
additionalProperties: false
properties:
active_employees_attacked_count:
description: Number of active employees who were attacked
type: integer
attack_events_per_employee:
$ref: '#/components/schemas/EmployeeEventsSchema'
employees_attacked_count:
description: Number of employees who were attacked, active or not
type: integer
employees_weak_credentials_detected_count:
description: Number of employees with weak credentials detected
type: integer
reporting_rate:
description: 'If filtered by campaing_id and/or campaign_cycle_id: percentage of attacks that were reported by employees rounded to the nearest integer. Otherwise: percentage of employees who have reported rounded to the nearest integer.'
type: integer
vulnerability_rate:
description: 'If filtered by campaign_id and/or campaign_cycle_id: percentage of attacks that successfully tricked employees, rounded to the nearest integer. Otherwise: percentage of employees tricked, rounded to the nearest integer.'
type: integer
required:
- attack_events_per_employee
- reporting_rate
- vulnerability_rate
- employees_weak_credentials_detected_count
- employees_attacked_count
- active_employees_attacked_count
title: CampaignsStatisticsPayload
type: object
CampaignStatusSchema:
enum:
- active
- completed
- draft
- paused
- scheduled
title: CampaignStatusSchema
type: string
ForbiddenErrorResponse:
additionalProperties: false
properties:
errors:
items:
additionalProperties: false
properties:
code:
const: forbidden
detail:
type: string
source:
properties:
pointer:
type: string
required:
- pointer
type: object
title:
const: Forbidden
required:
- title
- source
- detail
type: object
type: array
required:
- errors
title: ForbiddenErrorResponse
type: object
AttackTemplateSchema:
additionalProperties: false
properties:
name:
description: 'This field could be a default template''s name from the library, like ''deleted-files'', or a custom name if a custom template has been used.
'
examples:
- security-issue-detected
type: string
required:
- name
title: AttackTemplateSchema
type: object
EmployeeEventsSchema:
additionalProperties: false
properties:
attachment_opened:
description: Number of attachment_opened events
type: integer
attack_sent:
description: Number of attack_sent events
type: integer
attack_voided:
description: Number of attack_voided events
type: integer
credentials_submitted:
description: Number of credentials_submitted events
type: integer
download_link_clicked:
description: Number of download_link_clicked events
type: integer
email_answered:
description: Number of email_answered events
type: integer
email_opened:
description: Number of email_opened events
type: integer
email_reported:
description: Number of email_reported events
type: integer
employee_tricked:
description: Number of employee_tricked events
type: integer
file_opened:
description: Number of file_opened events
type: integer
manually_reported:
description: Number of manually_reported events
type: integer
manually_retried:
description: Number of manually_retried events
type: integer
mfa_code_submitted:
description: Number of mfa_code_submitted events
type: integer
page_opened:
description: Number of page_opened events
type: integer
phishing_remedial_course_completed:
description: Number of phishing_remedial_course_completed events
type: integer
phone_number_called:
description: Number of phone_number_called events
type: integer
phone_number_code_entered:
description: Number of phone_number_code_entered events
type: integer
qr_code_scanned:
description: Number of qr_code_scanned events
type: integer
remedial_completed:
description: Number of remedial_completed events
type: integer
remedial_started:
description: Number of remedial_started events
type: integer
scope_granted:
description: Number of scope_granted events
type: integer
sms_answered:
description: Number of sms_answered events
type: integer
social_login_clicked:
description: Number of social_login_clicked events
type: integer
required:
- mfa_code_submitted
- scope_granted
- social_login_clicked
- phishing_remedial_course_completed
- remedial_started
- remedial_completed
- qr_code_scanned
- phone_number_code_entered
- phone_number_called
- page_opened
- manually_retried
- manually_reported
- file_opened
- employee_tricked
- email_reported
- email_opened
- sms_answered
- email_answered
- download_link_clicked
- credentials_submitted
- attack_voided
- attack_sent
- attachment_opened
title: EmployeeEventsSchema
type: object
PaginatedCampaignPayload:
additionalProperties: false
properties:
completed_at:
format: date-time
type:
- string
- 'null'
created_at:
format: date-time
type: string
cycles:
description: 'A campaign cycle forms a group of attacks sent at a period of time. Periods of two cycles can''t overlap.
Recurring campaigns usually have multiple cycles, whereas one-off campaigns usually have only one.
'
items:
$ref: '#/components/schemas/CampaignCycleSchema'
type: array
delivery:
$ref: '#/components/schemas/CampaignDelivery'
frequency:
anyOf:
- type: 'null'
- $ref: '#/components/schemas/CampaignFrequency'
id:
format: uuid
type: string
launched_at:
format: date-time
type:
- string
- 'null'
name:
description: Name of the campaign. Returns a custom name if it has been given during the creation, default to a generated name.
examples:
- One-off campaign on 5 employees
type:
- string
- 'null'
status:
$ref: '#/components/schemas/CampaignStatusSchema'
updated_at:
format: date-time
type: string
workspace:
$ref: '#/components/schemas/WorkspaceOverviewSchema'
required:
- cycles
- status
- completed_at
- launched_at
- frequency
- delivery
- name
- updated_at
- created_at
- workspace
- id
title: PaginatedCampaignPayload
type: object
AttackEventSchema:
additionalProperties: false
properties:
created_at:
format: date-time
type: string
data:
anyOf:
- type: 'null'
- $ref: '#/components/schemas/AttackEventDataSchema'
description: Available only for `credentials_submitted' event type.
id:
format: uuid
type: string
type:
$ref: '#/components/schemas/AttackEventTypeSchema'
required:
- data
- type
- created_at
- id
title: AttackEventSchema
type: object
AttackSenderSchema:
additionalProperties: false
properties:
email:
examples:
- marketing@noreply.link
type: string
name:
examples:
- Marketing team
type: string
required:
- email
- name
title: AttackSenderSchema
type: object
PaginatedAttackLoginDomainPayload:
additionalProperties: false
properties:
id:
format: uuid
type: string
name:
description: The attack login domain, used as the link for each attack
examples:
- secure-signin.co
type: string
required:
- name
- id
title: PaginatedAttackLoginDomainPayload
type: object
CampaignCycleOverviewSchema:
additionalProperties: false
properties:
id:
format: uuid
type: string
required:
- id
title: CampaignCycleOverviewSchema
type: object
PaginatedAttackPayload:
additionalProperties: false
properties:
campaign_cycle:
anyOf:
- type: 'null'
- $ref: '#/components/schemas/CampaignCycleOverviewSchema'
description: Nullable only for attacks created before 2023-03-07
created_at:
format: date-time
type: string
difficulty:
$ref: '#/components/schemas/DifficultySchema'
employee:
$ref: '#/components/schemas/EmployeeOverviewSchema'
events:
examples:
- - created_at: '2025-03-06T14:18:18.397000Z'
data: null
id: f28a3b79-1c54-4ef5-a1db-7c48e2d9c4a2
type: remedial_started
- created_at: '2025-03-06T14:18:07.996000Z'
data: null
id: b9c2e7d1-5f3a-42d8-b0e5-9a6d481c7f52
type: employee_tricked
- created_at: '2025-03-06T14:18:07.989000Z'
data:
password_length: 12
score: 4
id: 7d5e8f2a-9b34-4c01-a6d7-1e3f8b952c9a
type: credentials_submitted
- created_at: '2025-03-06T14:17:54.181000Z'
data: null
id: 2c4d6e8f-a3b5-4c7d-9e1f-0a2b4c6d8e0f
type: page_opened
- created_at: '2025-03-06T14:16:58.163000Z'
data: null
id: 5a1b3c7d-9e2f-4a6b-8c0d-2e4f6a8b0c2d
type: email_opened
- created_at: '2025-03-06T14:16:38.716655Z'
data: null
id: 1d3f5e7a-9b2c-4d6e-8f0a-2c4d6e8a0c2e
type: attack_sent
items:
$ref: '#/components/schemas/AttackEventSchema'
type: array
id:
format: uuid
type: string
reported_at:
format: date-time
type:
- string
- 'null'
sender:
anyOf:
- type: 'null'
- $ref: '#/components/schemas/AttackSenderSchema'
sent_at:
format: date-time
type:
- string
- 'null'
service:
$ref: '#/components/schemas/AttackServiceSchema'
template:
$ref: '#/components/schemas/AttackTemplateSchema'
tricked_at:
description: 'When the employee was tricked. If this property is not null, an attack is considered successful.
This typically occurs when the employee submits their credentials on a phishing website of the campaign.
'
format: date-time
type:
- string
- 'null'
required:
- events
- campaign_cycle
- difficulty
- template
- service
- sender
- reported_at
- tricked_at
- sent_at
- created_at
- employee
- id
title: PaginatedAttackPayload
type: object
EmployeeOverviewSchema:
additionalProperties: false
properties:
id:
description: UUID of the employee
format: uuid
type: string
name:
description: Name of the employee
examples:
- John Doe
type:
- string
- 'null'
primary_email_address:
description: Email address
examples:
- john.doe@tryriot.com
format: email
type:
- string
- 'null'
username:
description: Username of the employee
type:
- string
- 'null'
required:
- primary_email_address
- username
- name
- id
title: EmployeeOverviewSchema
type: object
UnauthorizedErrorResponse:
additionalProperties: false
properties:
errors:
items:
additionalProperties: false
properties:
code:
const: unauthorized
detail:
type: string
source:
properties:
pointer:
type: string
required:
- pointer
type: object
title:
const: Unauthorized
required:
- title
- source
- detail
type: object
type: array
required:
- errors
title: UnauthorizedErrorResponse
type: object
CampaignFrequency:
enum:
- custom
- daily
- monthly
- quarterly
- weekly
- yearly
title: CampaignFrequency
type: string
DifficultySchema:
enum:
- easy
- hard
- medium
title: DifficultySchema
type: string
AttackEventDataSchema:
additionalProperties: false
properties:
password_length:
type:
- integer
- 'null'
score:
type:
- integer
- 'null'
required:
- password_length
- score
title: AttackEventDataSchema
type: object
UnprocessableContentErrorResponse:
additionalProperties: false
properties:
errors:
items:
additionalProperties: false
properties:
code:
type: string
detail:
type: string
source:
properties:
pointer:
type: string
required:
- pointer
type: object
title:
type: string
required:
- title
- source
- detail
type: object
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/riot/refs/heads/main/openapi/riot-simulation-api-openapi.yml