openapi: 3.1.0
info:
  title: Internal BIN Attack Alert WS Server
  description: |
    Internal BIN Attack Alert WS Server
    
    | Changes | Version | Date |
    |---------|---------|------|
    | - Correction of field name THREEDSREQUESTORAPPURL by  THREEDSREQUESTORURL | 26R1_1.1 | 19/12/2025 |
    | - Replaced 'IP_V4' and "IP_V6" with "IP" in the MatchingAttack object. | 26R1_1.0 | 25/11/2025 |

  version: ""
paths:
  /alerts/attacks:
    get:
      tags:
        - attacks
      summary: Returns information about all ongoing attack alerts.
      responses:
        '200':
          description: Alerts correctly retrieved and returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Attack'
        '500':
          description: Any unexpected server error
  /alerts/attacks/{attackId}:
    get:
      tags:
        - attacks
      summary: Returns information about an ongoing attack alert.
      parameters:
        - name: attackId
          in: path
          description: ID of the attack alert.
          required: true
          schema:
            type: string
            format: UUID
            examples:
              - 62ed1c0a-b952-4461-9296-91434fff20ef
      responses:
        '200':
          description: Alert correctly retrieved and returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attack'
        '404':
          description: Alert ID not found
        '500':
          description: Any unexpected server error
    post:
      tags:
        - attacks
      summary: Creation of an attack alert, linked to the given ID.
      parameters:
        - name: attackId
          in: path
          required: true
          description: ID of the attack alert.
          schema:
            type: string
            format: UUID
            examples:
              - 62ed1c0a-b952-4461-9296-91434fff20ef
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Attack'
      responses:
        '204':
          description: Alert correctly created
        '400':
          description: Incorrectly formatted request or missing fields
        '403':
          description: Alert ID already exists
        '500':
          description: Any unexpected server error
    patch:
      tags:
        - attacks
      summary: Update of an attack alert (extend its end time, and potentially update instance score).
      parameters:
        - name: attackId
          in: path
          required: true
          description: ID of the attack alert.
          schema:
            type: string
            format: UUID
            examples:
              - 62ed1c0a-b952-4461-9296-91434fff20ef
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/partialAttack'
      responses:
        '204':
          description: Alert correctly updated
        '400':
          description: Incorrectly formatted request or missing fields
        '404':
          description: Alert ID not found
        '500':
          description: Any unexpected server error
    delete:
      tags:
        - attacks
      summary: Deletion of an attack alert.
      parameters:
        - name: attackId
          in: path
          required: true
          description: ID of the attack alert.
          schema:
            type: string
            format: UUID
            examples:
              - 62ed1c0a-b952-4461-9296-91434fff20ef
      responses:
        '204':
          description: Alert correctly deleted
        '404':
          description: Alert ID not found
        '500':
          description: Any unexpected server error

components:
  schemas:
    Attack:
      properties:
        attackId:
          type: string
          format: UUID
          description: ID of the attack alert.
          examples:
            - 62ed1c0a-b952-4461-9296-91434fff20ef
        type:
          type: string
          enum:
            - BIN
          description: type of the attack.
          examples:
            - "BIN"
        pattern:
          type: object
          properties:
            BROWSER:
              type: string
              examples:
                - "Microsoft Edge"
            OS:
              type: string
              examples:
                - "Windows 10"
            TRANSACTION_AMOUNT:
              type: string
              examples:
                - "29900"
            TRANSACTION_CURRENCY_CODE:
              type: string
              examples:
                - "978"
            IP:
              type: string
              examples:
                - "160.92.186.211"
            EXPIRY_DATE:
              type: string
              examples:
                - "2029-02"
            BINRANGE:
              type: string
            THREEDSREQUESTORURL:
              type: string
            PRINCIPAL:
              type: string
            DEVICE_CHANNEL:
              type: string
          examples:
            - BROWSER: "Firefox"
              TRANSACTION_CURRENCY_CODE: "978"
              EXPIRY_DATE: "2029-02"
        duration:
          type: number
          format: long Unix timestamp UTC
          description: Date-time of the end of the alert (if not extended or deleted earlier).
          examples:
            - 1717771924
        instanceScore:
          type: number
          format: float 6 digits after the decimal point, between 0 and 1
          description: 6 digits after the decimal point, between 0 and 1, Probability for the instance to be currently under an attack
          examples:
            - 0.002355
        patternSelectivity:
          type: number
          format: float 6 digits after the decimal point
          description: Selectivity of the pattern, related to fraudulent transactions among all transactions
          examples:
            - 1.445965
      required:
        - attackId
        - pattern
        - type
        - duration
        - instanceScore
        - patternSelectivity
    partialAttack:
      properties:
        duration:
          type: number
          format: long
          description: Attack duration in milliseconds
          examples:
            - 120000
        instanceScore:
          type: number
          format: float 6 digits after the decimal point, between 0 and 1
          description: Probability for the instance to be currently under an attack
          examples:
            - 0.002310
      required:
        - duration
        - instanceScore