Riot Simulation API

openapi: 3.2.0
info:
  description: '## Overview

    The Riot API is a (mostly) RESTful API.'
  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:
    AttackEventDataSchema:
      additionalProperties: false
      properties:
        password_length:
          type:
          - integer
          - 'null'
        score:
          type:
          - integer
          - 'null'
      required:
      - password_length
      - score
      title: AttackEventDataSchema
      type: object
    CampaignDelivery:
      enum:
      - one_off
      - recurring
      title: CampaignDelivery
      type: string
    RateLimitExceededErrorResponse:
      additionalProperties: false
      properties:
        errors:
          items:
            additionalProperties: false
            properties:
              code:
                const: too_many_requests
              detail:
                type: string
              source:
                properties:
                  pointer:
                    type: string
                required:
                - pointer
                type: object
              title:
                const: Too Many Requests
            required:
            - title
            - source
            - detail
            type: object
          type: array
      required:
      - errors
      title: RateLimitExceededErrorResponse
      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
    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
    CampaignCycleSchema:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        ends_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        name:
          examples:
          - Batch 1
          type: string
        starts_at:
          format: date-time
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - ends_at
      - starts_at
      - updated_at
      - created_at
      - name
      - id
      title: CampaignCycleSchema
      type: object
    WorkspaceOverviewSchema:
      additionalProperties: false
      properties:
        id:
          format: uuid
          type: string
      required:
      - id
      title: WorkspaceOverviewSchema
      type: object
    CampaignStatusSchema:
      enum:
      - active
      - completed
      - draft
      - paused
      - scheduled
      title: CampaignStatusSchema
      type: string
    AttackEventTypeSchema:
      enum:
      - attachment_opened
      - attack_sent
      - attack_voided
      - credentials_submitted
      - download_link_clicked
      - email_answered
      - email_opened
      - email_reported
      - employee_tricked
      - file_opened
      - manually_reported
      - manually_retried
      - mfa_code_submitted
      - page_opened
      - phishing_remedial_course_completed
      - phone_number_called
      - phone_number_code_entered
      - qr_code_scanned
      - remedial_completed
      - remedial_started
      - scope_granted
      - sms_answered
      - social_login_clicked
      title: AttackEventTypeSchema
      type: string
    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
    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
    DifficultySchema:
      enum:
      - easy
      - hard
      - medium
      title: DifficultySchema
      type: string
    AttackServiceSchema:
      additionalProperties: false
      properties:
        name:
          description: Name of the service being used in the phishing attack. Returns 'This service is no longer available' for services that have been deprecated.
          examples:
          - Microsoft
          type: string
      required:
      - name
      title: AttackServiceSchema
      type: object
    CampaignCycleOverviewSchema:
      additionalProperties: false
      properties:
        id:
          format: uuid
          type: string
      required:
      - id
      title: CampaignCycleOverviewSchema
      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
    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
    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
          type: array
      required:
      - errors
      title: UnprocessableContentErrorResponse
      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
    CampaignFrequency:
      enum:
      - custom
      - daily
      - monthly
      - quarterly
      - weekly
      - yearly
      title: CampaignFrequency
      type: string
    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
    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
    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
  responses:
    UnauthorizedErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedErrorResponse'
      description: Missing API key or the key is invalid
    ForbiddenErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenErrorResponse'
      description: Requested resource cannot be accessed
    RateLimitExceededErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitExceededErrorResponse'
      description: Rate limit is exceeded
    UnprocessableContentErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnprocessableContentErrorResponse'
      description: Unprocessable content
  securitySchemes:
    apiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey