openapi: 3.0.3
info:
  title: AT&T Mobility Threat and Anomaly Detection API
  description: >-
    Uses machine learning to identify threats and unusual activity on mobile
    devices on the AT&T network. Provides real-time threat detection signals to
    applications for enhanced security, fraud prevention, and anomaly detection
    across subscriber devices. Part of the AT&T Network API Accelerator Program.
  version: '1.0'
  contact:
    url: https://devex-web.att.com/developer-hub/docs/network-api-accelerator-program
  termsOfService: https://www.att.com/gen/general?pid=11561
  x-generated-from: documentation
  x-last-validated: '2026-04-19'
servers:
  - url: https://api.att.com/network/threat-detection/v1
    description: AT&T Mobility Threat and Anomaly Detection API endpoint
paths:
  /threats:
    post:
      operationId: getDeviceThreats
      summary: AT&T Get Device Threat Assessment
      description: >-
        Retrieve a threat and anomaly assessment for a specific mobile device
        based on AT&T's machine learning network analysis. Returns threat
        indicators, anomaly scores, and risk levels detected for the device.
      tags:
        - Threat Detection
      security:
        - oauth2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreatAssessmentRequest'
            examples:
              GetDeviceThreatsRequestExample:
                summary: Default getDeviceThreats request
                x-microcks-default: true
                value:
                  device:
                    phoneNumber: '+12125551234'
      responses:
        '200':
          description: Threat assessment retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreatAssessment'
              examples:
                GetDeviceThreats200Example:
                  summary: Default getDeviceThreats 200 response
                  x-microcks-default: true
                  value:
                    riskLevel: LOW
                    anomalyScore: 0.05
                    threats: []
                    assessedAt: '2026-04-19T14:30:00Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /threats/subscribe:
    post:
      operationId: subscribeToThreatAlerts
      summary: AT&T Subscribe to Threat Alerts
      description: >-
        Subscribe to real-time threat and anomaly detection alerts for a device
        or set of devices. Notifications are delivered to the specified webhook
        URL when threat conditions are detected.
      tags:
        - Threat Subscriptions
      security:
        - oauth2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreatSubscriptionRequest'
            examples:
              SubscribeToThreatAlertsRequestExample:
                summary: Default subscribeToThreatAlerts request
                x-microcks-default: true
                value:
                  device:
                    phoneNumber: '+12125551234'
                  notificationUrl: https://webhook.example.com/threats
                  minRiskLevel: MEDIUM
      responses:
        '201':
          description: Threat alert subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreatSubscription'
              examples:
                SubscribeToThreatAlerts201Example:
                  summary: Default subscribeToThreatAlerts 201 response
                  x-microcks-default: true
                  value:
                    subscriptionId: sub-threat-500123
                    device:
                      phoneNumber: '+12125551234'
                    minRiskLevel: MEDIUM
                    status: ACTIVE
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: AT&T OAuth 2.0 for network security APIs
      flows:
        clientCredentials:
          tokenUrl: https://api.att.com/oauth/v4/token
          scopes: {}
  schemas:
    Device:
      type: object
      properties:
        phoneNumber:
          type: string
          description: Mobile phone number in E.164 format
          example: '+12125551234'
    ThreatAssessmentRequest:
      type: object
      required:
        - device
      properties:
        device:
          $ref: '#/components/schemas/Device'
    ThreatIndicator:
      type: object
      properties:
        type:
          type: string
          description: Type of threat detected
          enum:
            - UNUSUAL_LOCATION
            - ABNORMAL_DATA_USAGE
            - KNOWN_MALWARE_TRAFFIC
            - SIM_CLONING
            - ROAMING_ANOMALY
            - CALL_PATTERN_ANOMALY
          example: UNUSUAL_LOCATION
        severity:
          type: string
          description: Severity of the threat indicator
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
          example: MEDIUM
        description:
          type: string
          description: Human-readable description of the threat
          example: Device location changed rapidly from expected home area
        detectedAt:
          type: string
          format: date-time
          description: When the threat indicator was detected
          example: '2026-04-19T14:30:00Z'
    ThreatAssessment:
      type: object
      properties:
        riskLevel:
          type: string
          description: Overall risk level for the device
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
          example: LOW
        anomalyScore:
          type: number
          format: double
          description: Normalized anomaly score from 0.0 (normal) to 1.0 (highly anomalous)
          minimum: 0.0
          maximum: 1.0
          example: 0.05
        threats:
          type: array
          description: List of detected threat indicators
          items:
            $ref: '#/components/schemas/ThreatIndicator'
        assessedAt:
          type: string
          format: date-time
          description: Timestamp of the threat assessment
          example: '2026-04-19T14:30:00Z'
    ThreatSubscriptionRequest:
      type: object
      required:
        - device
        - notificationUrl
      properties:
        device:
          $ref: '#/components/schemas/Device'
        notificationUrl:
          type: string
          format: uri
          description: Webhook URL for threat alert notifications
          example: https://webhook.example.com/threats
        minRiskLevel:
          type: string
          description: Minimum risk level to trigger notifications
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
          example: MEDIUM
        notificationAuthToken:
          type: string
          description: Bearer token for webhook authentication
          example: webhook-token-abc123
    ThreatSubscription:
      type: object
      properties:
        subscriptionId:
          type: string
          description: Unique subscription identifier
          example: sub-threat-500123
        device:
          $ref: '#/components/schemas/Device'
        minRiskLevel:
          type: string
          description: Minimum risk level triggering notifications
          example: MEDIUM
        status:
          type: string
          description: Subscription status
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
    ErrorInfo:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 400
        code:
          type: string
          description: Error code
          example: INVALID_ARGUMENT
        message:
          type: string
          description: Human-readable error message
          example: Invalid device identifier