Dregs Escalations API

openapi: 3.2.0
info:
  title: Dregs Escalations API
  description: 'Customer REST API for sending events and reading fraud scores, identities, devices, escalations, channels, datasets, and mappings.


    Authenticate with a secret key created in the dashboard under Settings > Credentials (security scheme secretKey). Send it as a Bearer token: Authorization: Bearer sk_... The key acts as an admin of that credential''s team. POST /api/events and GET /api/devices/{fingerprint} also accept the credential''s public key (security scheme publicKey, Bearer pk_...). Public keys may be embedded in a browser. Secret keys must not.


    This document is the curated public surface. Dashboard sign-in, billing, team administration, and trainer tools are not included.'
  version: '1.0'
servers:
- url: https://dregs.com
  description: Dregs API
security:
- secretKey: []
tags:
- name: Escalations
  description: Escalation management
paths:
  /api/escalations/{id}:
    get:
      tags:
      - Escalations
      summary: Get escalation
      description: Returns a single escalation by ID
      operationId: getEscalation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Escalation found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1Escalation'
        '404':
          description: Escalation not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1Escalation'
      security:
      - secretKey: []
    patch:
      tags:
      - Escalations
      summary: Update escalation
      description: Acknowledge or resolve an escalation
      operationId: updateEscalation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1UpdateEscalationRequest'
        required: true
      responses:
        '200':
          description: Escalation updated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1Escalation'
        '400':
          description: Invalid status transition
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1Escalation'
        '404':
          description: Escalation not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1Escalation'
      security:
      - secretKey: []
  /api/escalations:
    get:
      tags:
      - Escalations
      summary: List escalations
      description: Returns escalations with optional filtering
      operationId: listEscalations
      parameters:
      - name: request
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/V1ListEscalationsRequest'
      responses:
        '200':
          description: Escalations retrieved successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1PageV1Escalation'
        '401':
          description: Authentication required
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1PageV1Escalation'
      security:
      - secretKey: []
  /api/escalations/summary:
    get:
      tags:
      - Escalations
      summary: Escalation summary
      description: Returns escalation counts grouped by status
      operationId: getEscalationSummary
      responses:
        '200':
          description: Summary retrieved successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1EscalationSummary'
        '401':
          description: Authentication required
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/V1EscalationSummary'
      security:
      - secretKey: []
components:
  schemas:
    V1EscalationSummary:
      type: object
      properties:
        open:
          type: integer
          format: int64
        acknowledged:
          type: integer
          format: int64
        closed:
          type: integer
          format: int64
    V1ListEscalationsRequest:
      type: object
      properties:
        pageNumber:
          type: integer
          format: int32
          minimum: 0
        pageSize:
          type: integer
          format: int32
          maximum: 100
          minimum: 1
        order:
          type: string
          enum:
          - ASC
          - DESC
        sort:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - OPEN
          - ACKNOWLEDGED
          - CLOSED
        severity:
          type: string
          enum:
          - INFO
          - WARNING
          - CRITICAL
        identity:
          type: string
        rule:
          type: string
        includeDeletedRules:
          type: boolean
    BadgeSnapshot:
      type: object
      properties:
        slug:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
          - GOOD
          - BAD
          - NEUTRAL
        explanation:
          type: string
    ScoreSnapshot:
      type: object
      properties:
        humanity:
          type: integer
          format: int32
        authenticity:
          type: integer
          format: int32
        uniqueness:
          type: integer
          format: int32
        behavior:
          type: integer
          format: int32
    V1Reference:
      type: object
      description: Reference to another entity with ID, label, and API path
      properties:
        id:
          type: string
          description: Unique identifier for the entity
          example: abc123
        label:
          type: string
          description: Human-readable label or name
          example: Bob User
        path:
          type: string
          description: API path to the entity resource
          example: /api/identities/abc123
    RuleCondition:
      type: object
      properties:
        condition:
          type: string
        category:
          type: string
        threshold:
          type: integer
          format: int32
        badge:
          type: string
        seconds:
          type: integer
          format: int32
    V1UpdateEscalationRequest:
      type: object
      properties:
        status:
          type: string
          enum:
          - PENDING
          - OPEN
          - ACKNOWLEDGED
          - CLOSED
    V1Escalation:
      type: object
      properties:
        id:
          type: integer
          format: int64
        escalationRule:
          $ref: '#/components/schemas/V1Reference'
        identity:
          $ref: '#/components/schemas/V1Reference'
        identityName:
          type: string
        identityEmail:
          type: string
        identityUsername:
          type: string
        scoreSnapshot:
          $ref: '#/components/schemas/ScoreSnapshot'
        badgeSnapshot:
          type: array
          items:
            $ref: '#/components/schemas/BadgeSnapshot'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/RuleCondition'
        triggeredConditions:
          type: array
          items:
            type: boolean
        severity:
          type: string
          enum:
          - INFO
          - WARNING
          - CRITICAL
        status:
          type: string
          enum:
          - PENDING
          - OPEN
          - ACKNOWLEDGED
          - CLOSED
        openedAt:
          type: string
          format: date-time
        acknowledgedBy:
          type: integer
          format: int64
        acknowledgedAt:
          type: string
          format: date-time
        closedBy:
          type: integer
          format: int64
        closedAt:
          type: string
          format: date-time
        channels:
          type: array
          items:
            type: string
        ruleDeleted:
          type: boolean
        createdAt:
          type: string
          format: date-time
    V1PageV1Escalation:
      type: object
      description: Paginated response wrapper
      properties:
        pageNumber:
          type: integer
          format: int32
          description: Current page number (0-based)
        pageSize:
          type: integer
          format: int32
          description: Number of items per page
        totalPages:
          type: integer
          format: int64
          description: Total number of pages
        totalElements:
          type: integer
          format: int64
          description: Total number of items across all pages
        content:
          type: array
          description: List of items on this page
          items:
            $ref: '#/components/schemas/V1Escalation'
        first:
          type: boolean
          description: Whether this is the first page
        last:
          type: boolean
          description: Whether this is the last page
        numberOfElements:
          type: integer
          format: int32
          description: Number of items on this page
  securitySchemes:
    secretKey:
      type: http
      description: Customer secret key from Settings > Credentials, sent as a Bearer token. The token value starts with sk_. It acts as an admin of that credential's team for every operation in this document. MCP tokens (dmcp_) are refused. Prefer the publicKey scheme on operations that accept a pk_ key.
      scheme: bearer
      bearerFormat: sk_
    publicKey:
      type: http
      description: Customer public key from Settings > Credentials, sent as a Bearer token. The token value starts with pk_. Accepted only by POST /api/events and GET /api/devices/{fingerprint}. It may be embedded in a browser. It cannot call the other operations in this document.
      scheme: bearer
      bearerFormat: pk_