Riot Sonar API

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 Sonar API
  version: v1
servers:
- url: https://public-api.tryriot.com/
security:
- apiKeyAuth: []
tags:
- name: Sonar
paths: {}
webhooks:
  revoke_drive_item_permission_request.created:
    post:
      description: 'Fires when Riot decides a third-party permission should be revoked. The customer is expected to perform the revocation on the corresponding provider using the identifiers in `data.provider_data`.

        '
      operationId: RevokeDriveItemPermissionRequestCreatedWebhook
      parameters:
      - description: Unique identifier of this webhook event. The same id is sent on every retry; use it as an idempotency key.
        in: header
        name: webhook-id
        required: true
        schema:
          format: uuid
          type: string
      - description: Unix timestamp (seconds) at which this delivery attempt was made. Used together with `webhook-id` and the body to verify the signature.
        in: header
        name: webhook-timestamp
        required: true
        schema:
          examples:
          - 1780000000
          type: integer
      - description: 'Space-delimited list of signatures, one per active endpoint secret (e.g. `v1,sig1 v1,sig2`).


          Each signature is `v1,<base64(HMAC-SHA256(secret, "<webhook-id>.<webhook-timestamp>.<body>"))>`. Verify against the raw request body; re-serializing the JSON will change the bytes and invalidate the signature.

          '
        in: header
        name: webhook-signature
        required: true
        schema:
          examples:
          - v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeDriveItemPermissionRequestCreatedEvent'
        description: Standard Webhooks envelope describing a permission Riot is asking the customer to revoke.
        required: true
      responses:
        '200':
          description: Event accepted. Any `2xx` status code is treated as success; the receiver does not need to return a body.
      security: []
      summary: revoke_drive_item_permission_request.created
      tags:
      - Sonar
components:
  schemas:
    Provider:
      description: Cloud provider the permission belongs to.
      enum:
      - google
      - microsoft
      examples:
      - google
      title: Provider
      type: string
    RevokeDriveItemPermissionRequestCreatedProviderData:
      additionalProperties: false
      properties:
        drive_item_id:
          description: Provider-side identifier of the drive item the permission grants access to.
          examples:
          - 0BxYzAbCdEfGhIjKlMnOp
          type: string
        owner_id:
          description: Provider-side identifier of the drive item owner.
          examples:
          - owner@example.com
          type: string
        permission_id:
          description: Provider-side identifier of the permission to revoke.
          examples:
          - anyoneWithLink
          type: string
        shared_drive_id:
          description: Provider-side identifier of the shared drive, when the item lives in one (Microsoft only).
          examples:
          - b!abc123
          type: string
      required:
      - drive_item_id
      - permission_id
      - owner_id
      title: RevokeDriveItemPermissionRequestCreatedProviderData
      type: object
    RevokeDriveItemPermissionRequestCreatedData:
      additionalProperties: false
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        provider_data:
          $ref: '#/components/schemas/RevokeDriveItemPermissionRequestCreatedProviderData'
      required:
      - provider_data
      - provider
      title: RevokeDriveItemPermissionRequestCreatedData
      type: object
    RevokeDriveItemPermissionRequestCreatedEvent:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/RevokeDriveItemPermissionRequestCreatedData'
        timestamp:
          description: ISO 8601 timestamp at which the event was created in Riot. This is the event time, not the delivery attempt time. The delivery time is sent in the `webhook-timestamp` header.
          format: date-time
          type: string
        type:
          const: revoke_drive_item_permission_request.created
      required:
      - data
      - timestamp
      - type
      title: RevokeDriveItemPermissionRequestCreatedEvent
      type: object
  securitySchemes:
    apiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey