Abnormal AI URL Rewrite API

openapi: 3.2.0
info:
  title: Abnormal Security Client URL Rewrite API
  version: 1.4.3
  description: 'This is the specification for Abnormal Security Client API which can be used for managing security threats detected by Abnormal Security.

    <h2>Who is this API for?</h2>

    This API is for managing threats to an organization identified by Abnormal Security. The organization should be integrated with Abnormal Security and enabled for real-time detection of malicious emails.

    <h2> Integration Steps </h2>

    Go to `https://portal.abnormalsecurity.com/home/settings/integrations` & click on `Abnormal REST API`

    <h3> Step 1: Generating the authentication token </h3>


    Retrieve your authentication token via the <a href="https://portal.abnormalsecurity.com/home/settings/integrations">Abnormal portal</a>. You will use this token to view and modify your Abnormal-detected threats and cases.


    Keep the token safe, as it grants access to sensitive threat data related to your organization. Store it in a secure place, such as an encrypted password vault, and do not share it unless absolutely necessary. If you feel that the token has been compromised, please contact your Account Manager immediately.


    Once obtained, the token can be used in a request from any HTTP client, such as cURL:

    <pre> curl -H "Authorization: Bearer  << ACCESS_TOKEN >>" https://api.abnormalplatform.com/v1/threats </pre>


    <h3> Step 2: IP allowlisting </h3>


    IP allowlisting ensures that API access is only possible from IP addresses explicitly belonging to your organization. It prevents users from unauthorized networks to access your Abnormal SOAR data. This second layer of security helps keep your data safe from unauthorized users, and protects you in the event of a token compromise.


    To allowlist your organization''s IPs, please provide enter into the <a href="https://portal.abnormalsecurity.com/home/settings/integrations">Abnormal portal</a> specific IPv4 / IPv6 addresses, or a range of addresses using a <a href="https://www.ipaddressguide.com/cidr"> CIDR block</a>.


    <h3> Step 3: Try it out with Test Data </h3>


    To confirm that <b>Steps 1 & 2</b> have been configured properly, send a request to the server with the following header set:


    <pre> curl -H "Authorization: Bearer  << ACCESS_TOKEN >>" <b>-H "Mock-Data: True"</b> https://api.abnormalplatform.com/v1/threats </pre>


    The server should respond with a body payload similar to the examples specified in this documentation.


    <h3> Note for EU Customers </h3>


    If you''re a customer in the EU, you''ll need to make API requests to our EU host `https://eu.rest.abnormalsecurity.com`. If you''d like to test the API through SwaggerHub, you''ll find both the default host and the EU host in the Servers dropdown menu below.

    '
  termsOfService: https://legal.abnormalsecurity.com/legal-hub/abnormal-security-api-terms-of-service-6feee5e3
  contact:
    name: Abnormal Security Support
    email: support@abnormalsecurity.com
servers:
- url: https://api.abnormalplatform.com/v1
  description: Production Server for managing threats
- url: https://eu.rest.abnormalsecurity.com/v1
  description: EU Production Server for managing threats.
security:
- BearerAuth: []
tags:
- name: URL Rewrite
paths:
  /url-rewrite/clicked-events:
    get:
      operationId: v1_url_rewrite_clicked_events_retrieve
      description: Retrieve paginated click and clickthrough events for URL rewrites. Supports filtering by Unix time range, user email, and event type. Returns events where users clicked on rewritten URLs in email messages.
      summary: Get URL rewrite click and clickthrough events
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
        description: 'Number of results to return per page (default: 20, max: 100)'
      - in: query
        name: start
        schema:
          type: integer
        description: Start time of the time range to filter by (Unix timestamp)
      - in: query
        name: end
        schema:
          type: integer
        description: End time of the time range to filter by (Unix timestamp)
      - in: query
        name: recipient
        schema:
          type: string
        description: Email address recipient of the email message to filter by
      - in: query
        name: event_type
        schema:
          type: string
        description: Event type to filter by (Click/Clickthrough)
      - in: query
        name: offset
        schema:
          type: string
        description: Offset to use for pagination
      tags:
      - URL Rewrite
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickedEventsResponse'
          description: A paginated list of clicked events
        '400':
          $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        '500':
          $ref: '#/components/schemas/Error'
components:
  responses:
    UnauthorizedError:
      description: Access token is missing or invalid
    TooManyRequestsError:
      description: Request count exceeds allowed number of concurrent requests for this resource type
    ForbiddenError:
      description: Access to the resource is forbidden (e.g. IP not in allowlist)
  schemas:
    ClickedEventsResponseMetadata:
      type: object
      description: Serializer for response metadata containing pagination information.
      properties:
        pagination:
          allOf:
          - $ref: '#/components/schemas/ClickedEventsPaginationMetadata'
          description: Pagination information for the response
        requestId:
          type:
          - string
          - 'null'
          description: Request ID for the API request
      required:
      - pagination
    SoarMessageMetadata:
      type: object
      description: 'Serializer for message metadata.


        Note: the "from" field is injected below via `_declared_fields` because

        `from` is a Python keyword and cannot be declared as a class attribute.'
      properties:
        subject:
          type:
          - string
          - 'null'
          description: Subject of the email message
        sender:
          allOf:
          - $ref: '#/components/schemas/SoarUserAddress'
          description: Sender of the email message
        to:
          type: array
          items:
            $ref: '#/components/schemas/SoarUserAddress'
          description: Recipients of the email message
        cc:
          type: array
          items:
            $ref: '#/components/schemas/SoarUserAddress'
          description: CC recipients of the email message
        from:
          allOf:
          - $ref: '#/components/schemas/SoarUserAddress'
          description: Sender of the email message
      required:
      - cc
      - from
      - sender
      - to
    ClickedEventsResponse:
      type: object
      description: 'Serializer for clicked events response.


        Note: the "data" field is injected below via `_declared_fields` because a

        class attribute named `data` would shadow DRF''s `Serializer.data` property

        (basedpyright also flags the conflict).'
      properties:
        metadata:
          allOf:
          - $ref: '#/components/schemas/ClickedEventsResponseMetadata'
          description: Response metadata including pagination
        data:
          type: array
          items:
            $ref: '#/components/schemas/SoarClickedEvent'
          description: List of clicked events
      required:
      - data
      - metadata
    ClickedEventsPaginationMetadata:
      type: object
      description: Serializer for pagination metadata on the clicked events response.
      properties:
        nextOffset:
          type:
          - string
          - 'null'
          description: Offset token for the next page if more results exist
        limit:
          type:
          - integer
          - 'null'
          description: Limit of the results
    SoarClickedEvent:
      type: object
      description: Serializer for clicked event representation in responses.
      properties:
        type:
          type: string
          description: Type of click event (click or clickthrough)
        link:
          type: string
          description: The URL that was clicked
        insights:
          type: array
          items:
            type: string
          description: List of insights about the click
        messageMetadata:
          allOf:
          - $ref: '#/components/schemas/SoarMessageMetadata'
          description: Metadata about the email message
        user:
          allOf:
          - $ref: '#/components/schemas/SoarUserAddress'
          description: Information about the user who clicked
        clickedTime:
          type: integer
          description: Unix timestamp when the click occurred
      required:
      - clickedTime
      - insights
      - link
      - messageMetadata
      - type
      - user
    Error:
      type: object
      description: Serializer for bad request error response.
      properties:
        error:
          type: string
          description: Error message
      required:
      - error
    SoarUserAddress:
      type: object
      description: Serializer for user address information.
      properties:
        name:
          type:
          - string
          - 'null'
          description: Display name of the user
        emailAddress:
          type: string
          description: Email address of the user who clicked the link
      required:
      - emailAddress
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer