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 Team simulation API
version: v1
servers:
- url: https://public-api.tryriot.com/
security:
- apiKeyAuth: []
tags:
- name: Team simulation
x-scalar-ignore: true
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:
- Team simulation
x-riot-team-ownership: simulation
/v1/breaches:
get:
description: 'Lists all breaches for a workspace with their affected employees count and status.
**Scopes required:**
- breaches:read'
operationId: breaches_get_paginated_FAUE35Y
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/BreachStatusSchema'
minItems: 1
type: array
uniqueItems: true
style: form
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/PaginatedBreachPayload'
type: array
metadata:
properties:
limit:
type: integer
next_cursor:
type:
- string
- 'null'
required:
- next_cursor
- limit
type: object
required:
- data
type: object
description: Breaches 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:
- breaches:read
summary: List breaches
tags:
- Team simulation
x-riot-team-ownership: simulation
/v1/breaches/statistics:
get:
description: 'Retrieves statistics about breaches for a given workspace, including impacted employees count, acknowledged employees count, and warned employees count.
**Scopes required:**
- breaches:read'
operationId: breaches_get_statistics_FAUE35Y
parameters:
- in: query
name: workspace_id
required: true
schema:
format: uuid
type: string
- in: query
name: breached_after
required: false
schema:
format: date-time
type: string
- in: query
name: breached_before
required: false
schema:
format: date-time
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/BreachesStatisticsPayload'
required:
- data
type: object
description: Breaches statistics
'401':
$ref: '#/components/responses/UnauthorizedErrorResponse'
'403':
$ref: '#/components/responses/ForbiddenErrorResponse'
'422':
$ref: '#/components/responses/UnprocessableContentErrorResponse'
'429':
$ref: '#/components/responses/RateLimitExceededErrorResponse'
security:
- apiKeyAuth:
- breaches:read
summary: Get breaches statistics
tags:
- Team simulation
x-riot-team-ownership: simulation
/v1/breaches/{breach_id}/compromised-employees:
get:
description: 'Lists all employees affected by a specific breach, ordered by their compromise date in descending order (most recent first).
The breach notification and acknowledgement dates, and breached email accounts are provided.
**Scopes required:**
- breaches:read'
operationId: breaches_get_breach_compromised_employees_FAUE35Y
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: breach_id
required: true
schema:
format: uuid
type: string
- in: query
name: workspace_id
required: true
schema:
format: uuid
type: string
- in: query
name: warned
required: false
schema:
type: boolean
- in: query
name: acknowledged
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/PaginatedBreachCompromisedEmployeePayload'
type: array
metadata:
properties:
limit:
type: integer
next_cursor:
type:
- string
- 'null'
required:
- next_cursor
- limit
type: object
required:
- data
type: object
description: Compromised employees list for a breach
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'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/BreachNotFoundErrorResponse'
description: no description
'422':
$ref: '#/components/responses/UnprocessableContentErrorResponse'
'429':
$ref: '#/components/responses/RateLimitExceededErrorResponse'
security:
- apiKeyAuth:
- breaches:read
summary: List compromised employees for a breach
tags:
- Team 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:
- Team 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:
- Team 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:
- Team simulation
x-riot-team-ownership: simulation
/v1/domains:
get:
description: 'Retrieves the domains sorted by name in ascending order.
**Scopes required:**
- workspace:read'
operationId: domains_get_paginated_domains_OOWLIAA
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
responses:
'200':
content:
application/json:
examples:
default:
data:
- id: 9f1c2a3b-4d5e-6f70-8192-a3b4c5d6e7f8
name: acme.com
simulation_spoofed_domains:
- micr0osoft.com
- noreply.link
- slack-notifications.com
status: verified
- id: 1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809
name: my-company-domain.com
simulation_spoofed_domains:
- acccounts-google.com
- secure-login.help
status: pending
metadata:
limit: 50
next_cursor: null
schema:
properties:
data:
items:
$ref: '#/components/schemas/PaginatedDomainPayload'
type: array
metadata:
properties:
limit:
type: integer
next_cursor:
type:
- string
- 'null'
required:
- next_cursor
- limit
type: object
required:
- data
type: object
description: 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:
- workspace:read
summary: List domains
tags:
- Team 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
PaginatedBreachCompromisedEmployeePayload:
additionalProperties: false
properties:
acknowledged_at:
description: When the employee acknowledged the breach
format: date-time
type:
- string
- 'null'
breached_accounts:
description: List of compromised email accounts
items:
$ref: '#/components/schemas/BreachedAccountPayload'
type: array
compromised_at:
description: When the employee was last compromised for the breach domain
format: date-time
type: string
employee:
$ref: '#/components/schemas/EmployeeOverviewSchema'
warned_at:
description: When the employee was warned about the breach
format: date-time
type:
- string
- 'null'
required:
- breached_accounts
- acknowledged_at
- warned_at
- compromised_at
- employee
title: PaginatedBreachCompromisedEmployeePayload
type: object
BreachesStatisticsPayload:
additionalProperties: false
properties:
acknowledged_employees_count:
description: Number of employees that have acknowledged breaches
type: integer
breaches_count:
description: Total number of breaches
type: integer
impacted_employees_count:
description: Number of employees impacted by breaches
type: integer
warned_employees_count:
description: Number of employees warned about a breach
type: integer
required:
- breaches_count
- acknowledged_employees_count
- warned_employees_count
- impacted_employees_count
title: BreachesStatisticsPayload
type: object
ForbiddenErrorResponse:
additionalProperties: false
properties:
errors:
items:
additionalProperties: false
properties:
code:
const: forbidden
detail:
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/riot/refs/heads/main/openapi/riot-team-simulation-api-openapi.yml