Doppel alerts API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Doppel Alerts API
  description: APIs to interface with Doppel's core system for social engineering defense — Brand Protection alerts, URL scanning, reports, protected assets, and Human Risk Management campaigns.
  contact:
    name: Doppel API Support
    url: https://doppel.readme.io/
servers:
- url: https://api.doppel.com/v1
tags:
- name: alerts
paths:
  /alert:
    post:
      description: 'Creates an alert for a specific entity (URL or phone number) within Doppel''s Brand Protection product.


        **Behavior:**

        - If an alert already exists for the entity, the existing alert is returned (HTTP 200).

        - If the alert exists but with a different brand than requested, returns HTTP 409.

        - After creation, the alert is automatically processed through Doppel''s triage workflow.

        - If `source` is provided, it must exactly match the "API value" field of an external source configured in your organization''s settings in Doppel Vision.


        **Returns HTTP 400 when:**

        - `entity` is missing, not a valid URL, or not a valid phone number.

        - `entity` is a protected asset (e.g. google.com).

        - `tags` is not a list of non-empty strings.

        - `source` does not match any configured external source for the organization.

        - `files` contains more than 10 items, duplicate file names, or is missing `file_to_upload`.

        '
      summary: Create Alert
      operationId: create_alert
      tags:
      - alerts
      x-google-backend:
        address: https://external-api-gateway-725058953679.us-west1.run.app
        jwt_audience: https://external-api-gateway-725058953679.us-west1.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 180
      parameters:
      - $ref: '#/components/parameters/XOrganizationCodeHeader'
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
          enum:
          - application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - entity
              properties:
                entity:
                  type: string
                  description: URL or phone number to be alerted.
                  example: https://suspicious-site.example.com
                brand:
                  type: string
                  description: The brand name to associate with the alert. Must match an active (non-archived) brand in your organization. Case-insensitive.
                  example: Acme Corp
                tags:
                  type: array
                  items:
                    type: string
                  description: 'Array of tag names to associate with the alert. Tags must already exist for your organization or be global tags.

                    Tags that don''t exist will be silently ignored.

                    '
                  example:
                  - Credential Theft
                  - NSFW
                  - Malicious
                  - Spam
                source:
                  type: string
                  description: Custom API source identifier configured in organization settings in Doppel Vision. Must exactly match the "API value" field of the desired source.
                  example: slack-integration
                files:
                  type: array
                  maxItems: 10
                  description: 'Optional list of files to upload with the alert. Each file must include base64-encoded content. Maximum 10 files per request.

                    For Telco alerts, uploaded image files may also be used as the alert''s canonical screenshot. If an uploaded Telco image is selected as the screenshot, Doppel stores a separate screenshot copy for alert review and downstream enforcement workflows while preserving the original Uploaded Files copy. Only upload image files that are appropriate to display as alert evidence.'
                  items:
                    $ref: '#/components/schemas/FileInput'
        required: true
      responses:
        '200':
          description: Alert already exists
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertCreatedResponse'
        '201':
          description: Submitted report successfully
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertCreatedResponse'
        '400':
          description: Invalid input
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Brand not found or archived for this organization
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Alert already exists with a different brand
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertCreatedResponse'
        '429':
          description: Rate limit exceeded
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
        user_api_key: []
      x-google-quota:
        metricCosts:
          create-alert-request: 1
    get:
      description: 'Retrieves the details of a single alert by its ID or entity value.


        **You must provide exactly one of `id` or `entity`**. Providing neither or both returns HTTP 400.


        Returns the full alert object including audit logs, tags, entity content, and a signed screenshot URL (expires in 1 hour).

        '
      summary: Get Alert
      operationId: get-alert
      tags:
      - alerts
      x-google-backend:
        address: https://external-api-gateway-725058953679.us-west1.run.app
        jwt_audience: https://external-api-gateway-725058953679.us-west1.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
      parameters:
      - $ref: '#/components/parameters/XOrganizationCodeHeader'
      - name: id
        in: query
        required: false
        description: The alert ID (format ORG-1234). Mutually exclusive with `entity`.
        example: ACM-1234
        schema:
          type: string
      - name: entity
        in: query
        required: false
        description: The URL, phone number, or email of the alert to retrieve. Mutually exclusive with `id`.
        example: https://suspicious-site.example.com
        schema:
          type: string
      responses:
        '200':
          description: Alert successfully retrieved
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertResponse'
        '400':
          description: Invalid input
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Alert not found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
        user_api_key: []
      x-google-quota:
        metricCosts:
          get-alert-request: 1
    put:
      description: 'Updates an alert''s information in Doppel''s system. Works across all modules.


        **You must provide exactly one of `id` or `entity`** to identify the alert. At least one field to update must be provided in the request body.


        **Paired parameters:**

        - `tag_action` and `tag_name` must both be provided together.

        - `file_action` and `files` must both be provided together.

        '
      summary: Update Alert
      operationId: update_alert
      tags:
      - alerts
      x-google-backend:
        address: https://external-api-gateway-725058953679.us-west1.run.app
        jwt_audience: https://external-api-gateway-725058953679.us-west1.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 30
      parameters:
      - $ref: '#/components/parameters/XOrganizationCodeHeader'
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
          enum:
          - application/json
      - name: id
        in: query
        required: false
        description: The alert ID (format ORG-1234). Mutually exclusive with `entity`.
        example: ACM-1234
        schema:
          type: string
      - name: entity
        in: query
        required: false
        description: The URL, phone number, or email of the alert to update. Mutually exclusive with `id`.
        example: https://suspicious-site.example.com
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                queue_state:
                  description: 'New queue state to update the alert with.

                    (Note: taken_down is equivalent to Resolved in the Doppel Vision App)

                    '
                  type: string
                  enum:
                  - doppel_review
                  - needs_confirmation
                  - actioned
                  - taken_down
                  - monitoring
                  - archived
                  example: actioned
                entity_state:
                  $ref: '#/components/schemas/EntityState'
                comment:
                  type: string
                  description: A new comment to add to the alert.
                  example: Confirmed phishing — proceeding with takedown.
                tag_action:
                  $ref: '#/components/schemas/TagActionType'
                tag_name:
                  type: string
                  description: Name of the tag to add or remove. Must be provided together with `tag_action`.
                  example: Credential Theft
                file_action:
                  $ref: '#/components/schemas/FileActionType'
                files:
                  type: array
                  maxItems: 10
                  description: 'List of files to upload or delete. Must be provided together with `file_action`. Maximum 10 files per request. When file_action is "upload", each file must include base64-encoded content in file_to_upload. When file_action is "delete", only file_name is required.

                    For Telco alerts, uploaded image files may also be used as the alert''s canonical screenshot. If an uploaded Telco image is selected as the screenshot, Doppel stores a separate screenshot copy for alert review and downstream enforcement workflows while preserving the original Uploaded Files copy. Deleting the uploaded-file copy does not delete the canonical screenshot copy.'
                  items:
                    $ref: '#/components/schemas/FileInput'
        description: 'Fields to update on the alert. At least one field is required.

          `tag_action`/`tag_name` and `file_action`/`files` are paired — both in each pair must be provided together.

          '
      responses:
        '200':
          description: Updated alert successfully
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertResponse'
        '400':
          description: Invalid input
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Alert or tag not found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
        user_api_key: []
      x-google-quota:
        metricCosts:
          update-alert-request: 1
  /alert/referrer:
    post:
      description: This endpoint submits referrer logs to Doppel for processing. These logs capture URLs that direct visitors to a site and may help identify threats or suspicious activity. Submitting a referrer log does not guarantee that an alert will be generated. Instead, the submitted URL will be analyzed as part of Doppel's referrer log processing.
      summary: Submit Referrer Logs
      operationId: submit-referrer-logs
      tags:
      - alerts
      x-google-backend:
        address: https://external-api-gateway-725058953679.us-west1.run.app
        jwt_audience: https://external-api-gateway-725058953679.us-west1.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 30
      security:
      - api_key: []
        user_api_key: []
      parameters:
      - $ref: '#/components/parameters/XOrganizationCodeHeader'
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
          enum:
          - application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - referrer_url
              properties:
                referrer_url:
                  type: string
                  description: The referrer URL where the user came from (required). Must not be a known protected asset for your organization.
                  example: https://suspicious-referrer.example.com/phish
                destination_url:
                  type: string
                  description: The URL where the user navigated to (optional). If provided and not already a known protected asset, it will be automatically added as a protected asset for your organization.
                  example: https://your-company.com/login
        description: Referrer log information to be submitted
        required: true
      x-google-quota:
        metricCosts:
          submit-referrer-logs-request: 1
      responses:
        '202':
          description: Request accepted for processing - URL has been submitted for potential alert creation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successful referrer log submission.
        '400':
          description: Bad request - missing required field, invalid URL format, or URL is a known internal asset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /alerts:
    get:
      description: 'Returns a paginated list of alerts across all modules, with support for filtering and sorting.


        **Sorting:** If `sort_type` is provided, `sort_order` must also be provided. If neither is provided, defaults to `date_sourced` descending.


        **Pagination:** Zero-indexed. Default page_size is 30, maximum is 200.


        **Note:** In this endpoint''s response, the alert timestamp field is named `last_activity_timestamp` (instead of `last_activity` as returned by GET /alert, PUT /alert, and POST /alert).

        '
      summary: Get Alerts
      operationId: get-alerts
      x-google-backend:
        address: https://external-api-gateway-725058953679.us-west1.run.app
        jwt_audience: https://external-api-gateway-725058953679.us-west1.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 60
      tags:
      - alerts
      parameters:
      - $ref: '#/components/parameters/XOrganizationCodeHeader'
      - name: search_key
        in: query
        description: Search alerts by URL. Currently only URL search is supported.
        required: false
        example: example.com
        schema:
          type: string
      - $ref: '#/components/parameters/QueueStateFilter'
      - $ref: '#/components/parameters/Product'
      - name: created_before
        in: query
        description: Filter alerts created before this date (ISO 8601 format).
        required: false
        example: '2024-01-05T13:45:30'
        schema:
          type: string
          format: date-time
      - name: created_after
        in: query
        description: Filter alerts created after this date (ISO 8601 format).
        required: false
        example: '2024-01-01T00:00:00'
        schema:
          type: string
          format: date-time
      - name: last_activity_timestamp
        in: query
        description: Filter alerts with last activity at or after this date (ISO 8601 format).
        required: false
        example: '2024-01-05T13:45:30'
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/SortType'
      - $ref: '#/components/parameters/SortOrder'
      - name: page
        in: query
        description: Page number for pagination (zero-indexed). Defaults to 0.
        required: false
        schema:
          type: integer
          default: 0
      - name: page_size
        in: query
        description: Number of alerts per page (default 30, max 200)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 30
      - name: tags
        in: query
        description: Comma-separated list of tag names to filter alerts by.
        required: false
        example: Credential Theft,Malicious
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  alerts:
                    type: array
                    items:
                      $ref: '#/components/schemas/AlertResponse'
                  metadata:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Total count of alerts
                      page:
                        type: integer
                        description: Current page number
                      total_pages:
                        type: integer
                        description: Total number of pages
                      page_size:
                        type: integer
                        description: Number of alerts per page
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
        user_api_key: []
      x-google-quota:
        metricCosts:
          get-alerts-request: 1
webhooks:
  alert_updated:
    post:
      operationId: alert_updated
      summary: Alert Updated
      description: This webhook is fired when an alert is updated in our system.
      tags:
      - alerts
      requestBody:
        description: Information about the Alert that was updated. The alert ID, the alert's Doppel URL, its display ID, and other relevant miscellaeneous fields are also included.
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Top-level webhook payload, containing the event type and the event-specific payload.
              required:
              - event_type
              - timestamp
              - updated_values
              - initial_values
              - alert
              properties:
                event_type:
                  type: string
                  description: The type of event that occurred.
                  enum:
                  - alert_updated
                timestamp:
                  type: string
                  format: date-time
                  description: Timestamp of the alert update.
                updated_values:
                  type: object
                  description: Key-value pairs of fields that were updated in the alert.
                  properties:
                    queue_state:
                      example: doppel_review
                      type: string
                    entity_state:
                      example: active
                      type: string
                    notes:
                      example: Custom alert notes here.
                      type: string
                    tag_add:
                      example: example_tag
                      type: string
                    tag_remove:
                      example: example_tag
                      type: string
                    file_action:
                      example: Uploaded file.txt
                      type: string
                    severity:
                      example: high
                      type: string
                initial_values:
                  type: object
                  description: Initial key-value pairs of fields that were updated in the alert.
                  properties:
                    queue_state:
                      example: monitoring
                      type: string
                    entity_state:
                      example: down
                      type: string
                    notes:
                      example: Custom alert notes here.
                      type: string
                    tag_add:
                      example: example_tag
                      type: string
                    tag_remove:
                      example: example_tag
                      type: string
                    file_action:
                      example: Uploaded file.txt
                      type: string
                    severity:
                      example: low
                      type: string
                alert:
                  $ref: '#/components/schemas/AlertUpdatedPayload'
      responses:
        '201':
          description: Webhook notification received successfully, and acted upon synchronously.
        '202':
          description: Webhook notification received successfully, but will be acted upon asynchronously.
        '400':
          description: Invalid payload received.
components:
  schemas:
    AuditLog:
      title: AuditLog
      description: A log of the changes on a report.
      type: object
      properties:
        changed_by:
          type: string
          description: Email of the user who made the change, or "Doppel".
        value:
          type: string
          description: New log value
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the change was made.
        type:
          type: string
          description: Type of audit log.
        metadata:
          title: Metadata
          description: Metadata for audit log.
          type: object
          properties:
            enforcement_request:
              description: Enforcement request information.
              type: object
              properties:
                platform:
                  description: Platform where the enforcement request was made.
                  type: string
                type:
                  description: Type of enforcement request.
                  type: string
            match:
              description: Match information.
              type: object
              properties:
                domain:
                  description: Domain information.
                  type: object
                  properties:
                    url:
                      description: URL associated with metadata.
                      type: string
    TagActionType:
      description: 'Action to take on a tag for an alert.

        - `add`: Associate the named tag with the alert.

        - `remove`: Remove the named tag from the alert.

        '
      type: string
      enum:
      - add
      - remove
    ReportSource:
      description: How the report was sourced.
      type: string
      enum:
      - Manual Upload
      - API Upload
      - Social Media API
      - Web Search API
      - Domains Feed
      - Phishing Feed
      - Marketplace API
      - Ads Feed
      - Dark Web Feed
      - SSL Transparency Logs
      - Pivot
      - Abuse Box
      - Brand Abusebox
      - Email Inbox
      - Web Beacon
      - Other
      - Crawler
    QueueState:
      description: 'The workflow queue an alert is currently in. Maps to the status columns in Doppel Vision.

        - `doppel_review`: Under review by Doppel''s internal team.

        - `needs_confirmation`: Awaiting customer confirmation before enforcement action.

        - `actioned`: Enforcement action has been taken (e.g. takedown request sent).

        - `taken_down`: Threat has been resolved. Equivalent to "Resolved" in Doppel Vision.

        - `monitoring`: Being actively monitored but no enforcement action taken yet.

        - `archived`: Dismissed or no longer relevant.

        '
      type: string
      enum:
      - doppel_review
      - needs_confirmation
      - actioned
      - taken_down
      - monitoring
      - archived
    FileActionType:
      description: 'Type of file operation to perform on an alert.

        - `upload`: Upload new files (file_to_upload is required for each file).

        - `delete`: Delete existing files (only file_name is required).

        '
      type: string
      enum:
      - upload
      - delete
    EntityState:
      description: 'The live status of the entity (URL, phone number, etc.) that the alert is tracking.

        - `active`: The entity is currently live/accessible.

        - `down`: The entity is no longer accessible (e.g. domain taken down).

        - `parked`: The domain is parked (registered but not hosting active content).

        - `suspicious`: The entity appears to be malicious or suspicious.

        - `unclassified`: The entity has not yet been classified.

        - `unrelated`: The entity has been determined to be unrelated to the brand.

        - `related`: The entity is related to the brand but not necessarily malicious.

        - `unknown`: The entity''s status cannot be determined.

        '
      type: string
      enum:
      - active
      - down
      - parked
      - suspicious
      - unclassified
      - unrelated
      - related
      - unknown
    AlertCreatedResponse:
      title: AlertCreatedResponse
      description: 'Lightweight response returned by POST /alert. Contains the alert ID and link but not the full alert details.

        Use GET /alert with the returned `id` to retrieve the full alert object.

        '
      type: object
      properties:
        id:
          type: string
          description: Alert ID in the format ORG-NUMBER (e.g. ACM-1234).
          example: ACM-1234
        entity:
          description: The URL or phone number submitted for the alert.
          type: string
          example: https://suspicious-site.example.com
        doppel_link:
          description: Direct link to the alert in the Doppel Vision web app.
          type: string
          example: https://app.doppel.com/alerts/ACM-1234
        last_activity:
          description: Timestamp of the most recent activity on this alert (ISO 8601).
          type: string
          format: date-time
          example: '2024-06-15T10:30:00'
        message:
          description: Additional context about the response. Present when the alert already exists (e.g. "Alert exists but with different brand. To update brand contact support.").
          type: string
        file_results:
          description: Results of file operations, only present when files were included in the request.
          type: array
          items:
            $ref: '#/components/schemas/FileResult'
    ErrorResponse:
      title: ErrorResponse
      description: Standard error response returned for all non-2xx responses. Contains a single `message` field with a human-readable error description.
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error description.
          example: This is an error message
    Product:
      description: Product category the report belongs to.
      type: string
      enum:
      - domains
      - social_media
      - mobile_apps
      - ecommerce
      - crypto
      - email
      - paid_ads
      - telco
      - darkweb
    AlertResponse:
      title: AlertResponse
      description: 'Full alert object returned by GET /alert, GET /alerts, and PUT /alert.

        Represents a single threat alert tracked by Doppel across any product type (domains, social media, mobile apps, etc.).

        '
      type: object
      properties:
        id:
          type: string
          description: Alert ID in the format ORG-NUMBER (e.g. ACM-1234). The prefix is your organization's abbreviation.
          example: ACM-1234
        entity:
          description: The URL, phone number, or email being tracked by this alert.
          type: string
          example: https://suspicious-site.example.com
        brand:
          description: The brand name this alert is associated with.
          type: string
          example: Acme Corp
        doppel_link:
          description: Direct link to this alert in the Doppel Vision web app.
          type: string
          exam

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/doppel/refs/heads/main/openapi/doppel-alerts-api-openapi.yml