Riot General API

openapi: 3.2.0
info:
  description: '## Overview

    The Riot API is a (mostly) RESTful API.'
  title: Riot General API
  version: v1
servers:
- url: https://public-api.tryriot.com/
security:
- apiKeyAuth: []
tags:
- description: Provides an overview of the organization and employees' data.
  name: General
paths:
  /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:
      - General
      x-riot-team-ownership: simulation
  /v1/employees:
    get:
      description: 'Retrieves a list of workspace employees, sorted by their creation date in descending order (most recent entries first).


        **Scopes required:**

        - workspace:read'
      operationId: employees_get_paginated_LRY7OLI
      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/EmployeeStatusSchema'
          minItems: 1
          type: array
          uniqueItems: true
        style: form
      - in: query
        name: karma_score_gte
        required: false
        schema:
          minimum: 0
          type: integer
      - in: query
        name: karma_score_lte
        required: false
        schema:
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/PaginatedEmployeePayload'
                    type: array
                  metadata:
                    properties:
                      limit:
                        type: integer
                      next_cursor:
                        type:
                        - string
                        - 'null'
                    required:
                    - next_cursor
                    - limit
                    type: object
                required:
                - data
                type: object
          description: Employees 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 employees
      tags:
      - General
      x-riot-team-ownership: platform
  /v1/employees/statistics:
    get:
      description: 'Retrieves statistics about employees in a workspace grouped by status.


        **Scopes required:**

        - workspace:read'
      operationId: employees_get_statistics_LRY7OLI
      parameters:
      - in: query
        name: workspace_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/EmployeeStatisticsPayload'
                required:
                - data
                type: object
          description: Employee statistics
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceNotFoundErrorResponse'
          description: no description
        '422':
          $ref: '#/components/responses/UnprocessableContentErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimitExceededErrorResponse'
      security:
      - apiKeyAuth:
        - workspace:read
      summary: Get employee statistics
      tags:
      - General
      x-riot-team-ownership: platform
  /v1/employees/{employee_id}:
    get:
      description: 'Retrieves details for a specific employee by ID.


        **Scopes required:**

        - workspace:read'
      operationId: employees_get_LRY7OLI
      parameters:
      - in: path
        name: employee_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PaginatedEmployeePayload'
                required:
                - data
                type: object
          description: Employee details
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeNotFoundErrorResponse'
          description: no description
        '422':
          $ref: '#/components/responses/UnprocessableContentErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimitExceededErrorResponse'
      security:
      - apiKeyAuth:
        - workspace:read
      summary: Get employee details
      tags:
      - General
      x-riot-team-ownership: platform
  /v1/organization:
    get:
      description: 'Returns the organization with its workspaces.


        **Scopes required:**

        - workspace:read'
      operationId: organizations_get_XEBQFJQ
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/OrganizationPayload'
                required:
                - data
                type: object
          description: Organization
        '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: Get organization
      tags:
      - General
      x-riot-team-ownership: platform
components:
  schemas:
    EmployeeStatusSchema:
      description: "        - `active`: default status.\n        - `deactivated`: employee has been manually deactivated.\n        - `pending`: employee is currently being synced via workspace's AD\n"
      enum:
      - active
      - deactivated
      - pending
      - unlicensed
      title: EmployeeStatusSchema
      type: string
    EmployeeCyberPostureGrade:
      enum:
      - a
      - b
      - c
      - d
      title: EmployeeCyberPostureGrade
      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
    EmployeeNotFoundErrorResponse:
      additionalProperties: false
      properties:
        error:
          const: Employee not found
      required:
      - error
      title: EmployeeNotFoundErrorResponse
      type: object
    OrganizationWorkspaceSchema:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        cyber_posture:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/CyberPostureSchema'
          description: Latest cyber posture summary for the workspace.
        id:
          format: uuid
          type: string
        name:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - cyber_posture
      - updated_at
      - created_at
      - name
      - id
      title: OrganizationWorkspaceSchema
      type: object
    EmployeeKarmaSchema:
      additionalProperties: false
      properties:
        score:
          type: integer
        security_level:
          $ref: '#/components/schemas/EmployeeSecurityLevel'
      required:
      - security_level
      - score
      title: EmployeeKarmaSchema
      type: object
    EmployeeStatisticsPayload:
      additionalProperties: false
      properties:
        activated:
          description: Number of active employees
          type: integer
        archived:
          description: Number of archived employees
          type: integer
        deactivated:
          description: Number of deactivated employees
          type: integer
        total:
          description: Total number of employees
          type: integer
      required:
      - archived
      - deactivated
      - activated
      - total
      title: EmployeeStatisticsPayload
      type: object
    PaginatedDomainPayload:
      additionalProperties: false
      properties:
        id:
          description: UUID of the domain
          format: uuid
          type: string
        name:
          description: Domain name
          examples:
          - acme.com
          type: string
        simulation_spoofed_domains:
          description: Alphabetically sorted sender domains that simulation may spoof when sending phishing or smishing attacks.
          examples:
          - - micr0osoft.com
            - noreply.link
            - slack-notifications.com
          items:
            type: string
          type: array
        status:
          $ref: '#/components/schemas/DomainStatus'
      required:
      - simulation_spoofed_domains
      - status
      - name
      - id
      title: PaginatedDomainPayload
      type: object
    EmployeeEmailAddressSource:
      description: ' Source of the email.

        `custom` - the email is provided by the employee''s admin or set during CSV import

        `employee` - the email is provided by the employee via portal

        `google`, `microsoft`, `okta`, `slack` - imported via corresponding synchronization

        '
      enum:
      - custom
      - employee
      - google
      - microsoft
      - okta
      - slack
      examples:
      - google
      title: EmployeeEmailAddressSource
      type: string
    CyberPostureSchema:
      additionalProperties: false
      properties:
        grade:
          $ref: '#/components/schemas/CyberPostureGrade'
        percentage:
          description: Cyber posture score (0-100).
          type: integer
      required:
      - grade
      - percentage
      title: CyberPostureSchema
      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
    CyberPostureGrade:
      enum:
      - a
      - b
      - c
      - d
      title: CyberPostureGrade
      type: string
    PaginatedEmployeePayload:
      additionalProperties: false
      properties:
        aura_score:
          description: Employee's current aura score.
          type: integer
        country_code:
          description: Alpha-2 ISO 3166-1 country code of the employee.
          examples:
          - FR
          maxLength: 2
          type:
          - string
          - 'null'
        created_at:
          description: Riot employee creation date
          format: date-time
          type: string
        current_mission:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/EmployeeCurrentMissionSchema'
          description: The employee's live mission, or `null` when no mission is running.
        cyber_posture:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/CyberPostureOverviewSchema'
          description: Latest cyber posture summary for the employee.
        department:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/EmployeeDepartmentSchema'
        email_addresses:
          description: Professional email addresses of the employee. No personal email address is returned
          items:
            $ref: '#/components/schemas/EmployeeEmailAddressSchema'
          type: array
        google_user_id:
          description: Google Workspace user ID, when the employee is synced from Google.
          examples:
          - '112233445566778899000'
          type:
          - string
          - 'null'
        id:
          description: UUID of the employee
          format: uuid
          type: string
        job_title:
          description: The employee's job title.
          examples:
          - Account manager
          type:
          - string
          - 'null'
        karma:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/EmployeeKarmaSchema'
        language:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/EmployeeLanguage'
        manager:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/EmployeeOverviewSchema'
        microsoft_user_id:
          description: Microsoft Entra ID (Azure AD) user object ID, when the employee is synced from Microsoft.
          examples:
          - f9a7ceeb-6c82-48b1-a522-faf335c7d623
          type:
          - string
          - 'null'
        mission_stats:
          $ref: '#/components/schemas/EmployeeMissionStatsSchema'
        name:
          description: Name of the employee
          examples:
          - John Doe
          type:
          - string
          - 'null'
        okta_user_id:
          description: Okta user ID, when the employee is synced from Okta.
          examples:
          - 00u1abcdef2GhIjKlMn3
          type:
          - string
          - 'null'
        primary_email_address:
          description: Primary email address of the employee
          examples:
          - john.doe@tryriot.com
          format: email
          type:
          - string
          - 'null'
        slack_user_id:
          description: Slack user ID, when the employee is synced from Slack.
          examples:
          - U01234ABCDE
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/EmployeeStatusSchema'
        timezone:
          description: Timezone of the employee.
          examples:
          - Europe/Paris
          type: string
        updated_at:
          description: When the last update occurred
          format: date-time
          type: string
        username:
          description: Username of the employee
          type:
          - string
          - 'null'
        workspace:
          $ref: '#/components/schemas/WorkspaceOverviewSchema'
      required:
      - okta_user_id
      - slack_user_id
      - google_user_id
      - microsoft_user_id
      - job_title
      - country_code
      - manager
      - department
      - current_mission
      - mission_stats
      - aura_score
      - cyber_posture
      - karma
      - email_addresses
      - primary_email_address
      - status
      - timezone
      - language
      - username
      - name
      - updated_at
      - created_at
      - workspace
      - id
      title: PaginatedEmployeePayload
      type: object
    EmployeeDepartmentSchema:
      additionalProperties: false
      properties:
        name:
          description: Name of the department
          examples:
          - Devs
          type: string
      required:
      - name
      title: EmployeeDepartmentSchema
      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
    EmployeeSecurityLevel:
      enum:
      - bad
      - dangerous
      - excellent
      - exceptional
      - good
      - great
      - ok
      title: EmployeeSecurityLevel
      type: string
    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
    WorkspaceOverviewSchema:
      additionalProperties: false
      properties:
        id:
          format: uuid
          type: string
      required:
      - id
      title: WorkspaceOverviewSchema
      type: object
    EmployeeMissionStatsSchema:
      additionalProperties: false
      properties:
        streak_count:
          description: Current consecutive completed-missions streak
          type: integer
      required:
      - streak_count
      title: EmployeeMissionStatsSchema
      type: object
    CyberPostureOverviewSchema:
      additionalProperties: false
      properties:
        grade:
          $ref: '#/components/schemas/EmployeeCyberPostureGrade'
        score_percentage:
          description: Employee cyber posture score (0-100)
          examples:
          - 87.5
          type: number
      required:
      - grade
      - score_percentage
      title: CyberPostureOverviewSchema
      type: object
    WorkspaceNotFoundErrorResponse:
      additionalProperties: false
      properties:
        errors:
          items:
            additionalProperties: false
            properties:
              code:
                const: workspace_not_found
              detail:
                type: string
              source:
                properties:
                  pointer:
                    type: string
                required:
                - pointer
                type: object
              title:
                const: Workspace not found
            required:
            - title
            - source
            - detail
            type: object
          type: array
      required:
      - errors
      title: WorkspaceNotFoundErrorResponse
      type: object
    EmployeeEmailAddressSchema:
      additionalProperties: false
      properties:
        address:
          description: Email address
          examples:
          - john.doe@tryriot.com
          format: email
          type: string
        is_primary:
          type: boolean
        source:
          $ref: '#/components/schemas/EmployeeEmailAddressSource'
      required:
      - is_primary
      - source
      - address
      title: EmployeeEmailAddressSchema
      type: object
    OrganizationPayload:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        cyber_posture:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/CyberPostureSchema'
          description: Latest cyber posture summary for the organization.
        id:
          format: uuid
          type: string
        updated_at:
          format: date-time
          type: string
        workspaces:
          items:
            $ref: '#/components/schemas/OrganizationWorkspaceSchema'
          type: array
      required:
      - workspaces
      - cyber_posture
      - updated_at
      - created_at
      - id
      title: OrganizationPayload
      type: object
    EmployeeCurrentMissionSchema:
      additionalProperties: false
      properties:
        completed_at:
          description: When the employee completed the mission
          format: date-time
          type:
          - string
          - 'null'
        completion_percentage:
          description: Share of the mission's tasks the employee has completed
          maximum: 100
          minimum: 0
          type: integer
        end_at:
          description: When the mission ends
          format: date-time
          type: string
        id:
          description: UUID of the mission
          format: uuid
          type: string
        start_at:
          description: When the mission starts
          format: date-time
          type: string
      required:
      - completion_percentage
      - completed_at
      - end_at
      - start_at
      - id
      title: EmployeeCurrentMissionSchema
      type: object
    DomainStatus:
      description: 'Verification status of the domain.

        - `verified`: the domain has been verified.

        - `pending`: verification is in progress.

        - `unverified`: the domain has not been verified.

        - `unsupported`: the domain cannot be used.

        '
      enum:
      - pending
      - unsupported
      - unverified
      - verified
      title: DomainStatus
      type: string
    EmployeeLanguage:
      description: Language of the employee
      enum:
      - arabic
      - bulgarian
      - catalan
      - chinese
      - chinese_traditional_taiwan
      - czech
      - danish
      - dutch
      - english
      - finnish
      - french
      - french_quebec
      - german
      - greek
      - hindi
      - hungarian
      - indonesian
      - italian
      - japanese
      - korean
      - norwegian_bokmal
      - polish
      - portuguese
      - portuguese_brazilian
      - romanian
      - russian
      - slovak
      - slovenian
      - spanish
      - thai
      - turkish
      - ukrainian
      - vietnamese
      examples:
      - english
      title: EmployeeLanguage
      type: string
  responses:
    RateLimitExceededErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitExceededErrorResponse'
      description: Rate limit is exceeded
    UnauthorizedErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedErrorResponse'
      description: Missing API key or the key is invalid
    UnprocessableContentErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnprocessableContentErrorResponse'
      description: Unprocessable content
    ForbiddenErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenErrorResponse'
      description: Requested resource cannot be accessed
  securitySchemes:
    apiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey