IRONSCALES Incident API

openapi: 3.2.0
info:
  title: IRONSCALES Management Incident API
  description: The Incident operations of the IRONSCALES Management API, split by tag from the provider-published Swagger 2.0 document at https://appapi.ironscales.com/appapi/docs/?format=openapi. Operations, parameters, responses and definitions are carried verbatim from the source specification.
  version: v1
servers:
- url: https://appapi.ironscales.com/appapi
security:
- JWT: []
tags:
- name: Incident
paths:
  /incident/{company_id}/account-takeover/{incident_id}/details/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: incident_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get Account Takeover incident details
      description: "\nRetrieve detailed information about a specific Account Takeover incident.\n<br/><br/>\n<b>Query Parameters:</b>\n<ul>\n    <li><b>page:</b> Page number for pagination (default: 1)</li>\n    <li><b>items_per_page:</b> Number of items per page (min: 1, max: 500, default: 50)</li>\n    <li><b>title:</b> Filter by alert titles (can specify multiple)</li>\n    <li><b>location:</b> Filter by locations (can specify multiple)</li>\n    <li><b>ip:</b> Filter by IP addresses with validation (can specify multiple)</li>\n</ul>\n<br/><b>Response Data:</b>\n<ul>\n    <li><b>incident_details:</b> Complete incident information with account details and alerts</li>\n    <li><b>filter_options:</b> Available filter values for dropdown menus</li>\n    <li><b>pagination:</b> Page count and current page information</li>\n</ul>\n<br/><b>Scopes:</b>\n<ul>\n    <li>company.all</li>\n    <li>company.view</li>\n</ul>\n"
      parameters:
      - name: page
        in: query
        description: Page number for pagination results. Starts at 1.
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: items_per_page
        in: query
        description: 'Number of items per page. Min: 1, Max: 500, Default: 50.'
        required: false
        schema:
          type: integer
          default: 50
          maximum: 500
          minimum: 1
      - name: title
        in: query
        description: List of alert titles to filter by.
        required: false
        schema:
          type: array
          items:
            type: string
            maxLength: 200
            minLength: 1
      - name: location
        in: query
        description: List of locations to filter by.
        required: false
        schema:
          type: array
          items:
            type: string
            maxLength: 200
            minLength: 1
      - name: ip
        in: query
        description: List of IPv4 or IPv6 addresses to filter by.
        required: false
        schema:
          type: array
          items:
            type: string
            minLength: 1
      responses:
        '200':
          description: Successfully retrieved Account Takeover incident details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTakeoverDetailsResponse'
              example:
                incident_details:
                  id: 123
                  account_details:
                    name: John Doe
                    email: john.doe@company.com
                    title: Manager
                    department: IT Security
                    country: United States
                    phone_number: +1-555-0123
                  alerts:
                  - id: 456
                    title: Suspicious Login
                    description: Login from unusual location detected
                    type: 1
                    details:
                    - ip: 127.0.0.0
                      location: New York, NY
                      logon_time: '2024-01-15T10:30:00Z'
                    created: '2024-01-15T10:25:00Z'
                  state: 1
                  original_state: 1
                  resolved_by: Jane Smith
                  resolved_on: '2024-01-15T14:30:00Z'
                  created: '2024-01-15T10:25:00Z'
                  assignee:
                    id: 789
                    email: security@company.com
                    first_name: Security
                    last_name: Team
                filter_options:
                  titles:
                  - Suspicious Login
                  - Rule Created
                  locations:
                  - New York
                  - California
                  ips:
                  - 127.0.0.0
                  - 127.0.0.1
                pages_count: 3
                page: 1
                items_per_page: 50
        '400':
          description: Invalid query parameters - validation errors
          content:
            application/json:
              example:
                page:
                - Ensure this value is greater than or equal to 1.
                ip:
                - Enter a valid IPv4 or IPv6 address.
        '403':
          description: Permission Denied
          content:
            application/json:
              example:
              - detail: Missing JWT
              - detail: You do not have permission to perform this action.
              - message: You do not have permission for company <company_id>
        '404':
          description: Company was not found
          content:
            application/json:
              example:
              - message: Company not found
      tags:
      - Incident
  /incident/{company_id}/account-takeover/{incident_id}/remediation/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: incident_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: Create Account Takeover remediation
      description: "\nCreate remediation for the specified Account Takeover incident.\n<br/><br/>\n<b>State Options:</b>\n<ul>\n    <li><b>2 (Safe):</b> Mark the incident as safe/false positive</li>\n    <li><b>3 (Compromised):</b> Mark the incident as compromised and apply remediation actions</li>\n</ul>\n<br/><b>Remediation Actions:</b>\n<ul>\n    <li><b>3 (SIGN_OUT):</b> Revoke user's Microsoft 365 sessions - only allowed for state 3 (Compromised)</li>\n    <li><b>4 (DISABLE_ACCOUNT):</b> Disable user's Microsoft 365 account - only allowed for state 3 (Compromised)</li>\n</ul>\n<br/><b>Validation Rules:</b>\n<ul>\n    <li>Remediation actions can only be applied when marking incident as compromised (state=3)</li>\n    <li>When marking incident as safe (state=2), no action should be provided</li>\n</ul>\n<br/><b>Scopes:</b>\n<ul>\n    <li>company.all</li>\n    <li>company.edit</li>\n</ul>\n"
      responses:
        '200':
          description: Successfully updated incident state and applied remediation actions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTakeoverRemediationResponse'
              example:
                state: 3
        '400':
          description: Invalid request body - validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTakeoverRemediationError'
              example:
                data:
                  state:
                  - This field is required.
                  action:
                  - Remediation actions are only allowed when marking incident as compromised (state=3).
        '404':
          description: Company was not found
          content:
            application/json:
              example:
              - message: Company not found
        '403':
          description: Permission Denied
          content:
            application/json:
              example:
              - detail: Missing JWT
              - detail: You do not have permission to perform this action.
              - message: You do not have permission for company <company_id>
        '429':
          description: Too many requests
          content:
            application/json:
              example:
              - detail: Request was throttled. Expected available in 60 seconds.
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountTakeoverRemediation'
        required: true
  /incident/{company_id}/classify/{incident_id}:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: incident_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: Classify specific incident
      description: Classify specific incident<br/><b>Scopes:</b><ul><li>partner.company.classify</li><li>company.classify</li></ul>
      parameters:
      - name: company_id
        in: path
        description: company id
        required: true
        schema:
          type: integer
      - name: incident_id
        in: path
        description: incident id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              example:
                success: true
        '400':
          description: Error explanation in error_message
          content:
            application/json:
              example:
                error_message: explanation
        '404':
          description: Incident/company were not found
        '403':
          description: No permissions
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentClassification'
        required: true
  /incident/{company_id}/details/{incident_id}:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: incident_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get details of specific incident
      description: "Get details of specific incident<br/>\n<br/><b>Scopes:</b>\n<ul>\n    <li>partner.all</li>\n    <li>partner.company.view</li>\n    <li>company.view</li>\n</ul>"
      parameters:
      - name: company_id
        in: path
        description: company id
        required: true
        schema:
          type: integer
      - name: incident_id
        in: path
        description: incident id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentDetails'
        '404':
          description: Incident/company were not found
        '403':
          description: No permissions
      tags:
      - Incident
  /incident/{company_id}/list/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get list of Incidents
      description: "List of Incidents\n<br/><b>Scopes:</b>\n<ul>\n    <li>partner.all</li>\n    <li>company.all</li>\n    <li>partner.company.view</li>\n    <li>company.view</li>\n</ul>"
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: items_per_page
        in: query
        description: Number of items per page (optional, overrides default)
        required: false
        schema:
          type: integer
          default: 100
          minimum: 1
      - name: sort
        in: query
        description: 'Options: created | latestEmailDate | incidentID | emailSubject | senderName | senderEmail | recipientName | recipientEmail | classification | firstChallengedDate | noSorting'
        required: false
        schema:
          type: string
          enum:
          - created
          - latestEmailDate
          - incidentID
          - emailSubject
          - senderName
          - senderEmail
          - recipientName
          - recipientEmail
          - classification
          - firstChallengedDate
          - noSorting
          default: noSorting
      - name: order
        in: query
        description: 'Options: desc | asc'
        required: false
        schema:
          type: string
          enum:
          - desc
          - asc
          default: desc
      - name: created_start_time
        in: query
        description: Start of created date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: created_end_time
        in: query
        description: End of created date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: incidentID
        in: query
        description: The incident ID
        required: false
        schema:
          type: integer
      - name: search_email_subject
        in: query
        description: Search Email Subject
        required: false
        schema:
          type: string
          default: ''
      - name: search_sender_name
        in: query
        description: Search Sender Name
        required: false
        schema:
          type: string
          default: ''
      - name: search_sender_email
        in: query
        description: Search Sender Email
        required: false
        schema:
          type: string
          default: ''
      - name: search_recipient_name
        in: query
        description: Search Recipient Name
        required: false
        schema:
          type: string
          default: ''
      - name: search_recipient_email
        in: query
        description: Search Recipient Email
        required: false
        schema:
          type: string
          default: ''
      - name: classification
        in: query
        description: 'Options: all | phishing | spam | compromised | safe | open | silent(can select multiple by repeating fields (field1=value1&field1=value2&field1=value3...))'
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - all
            - phishing
            - spam
            - compromised
            - safe
            - open
            - silent
          default:
          - all
      - name: challenged_type
        in: query
        description: 'Filter by challenge type. Options: release_request, end_user_report'
        required: false
        schema:
          type: string
          enum:
          - release_request
          - end_user_report
      - name: challenged_start_date
        in: query
        description: Start of challenged date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: challenged_end_date
        in: query
        description: End of challenged date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: state
        in: query
        description: 'Options: all | classified | unclassified | challenged(can select multiple by repeating fields (field1=value1&field1=value2&field1=value3...))'
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - all
            - classified
            - unclassified
            - challenged
          default:
          - all
      - name: reportType
        in: query
        description: 'Options: all | email | ato | teams | msft_quarantine'
        required: false
        schema:
          type: string
          enum:
          - all
          - email
          - ato
          - teams
          - msft_quarantine
          default: all
      - name: last_update_start_time
        in: query
        description: Start of last update date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: last_update_end_time
        in: query
        description: End of last update date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: period
        in: query
        description: 'The period to show. Deprecated in favor of created_start_time/created_end_time. Options: <br />0: Last 24 hours<br />1: Last 7 days<br />2: Last 90 days<br />3: Last 180 days<br />4: Last 360 days<br />5: Current year to date<br />6: All time'
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
      - name: company_id
        in: path
        description: company id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentListPage'
        '400':
          description: Error explanation in error_message
          content:
            application/json:
              example:
                error_message: explanation
        '404':
          description: Incident or page were not found
        '403':
          description: No permissions
      tags:
      - Incident
  /incident/{company_id}/recluster/{incident_id}:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: incident_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: Recluster incident
      description: "Recluster (revert) mitigations back to the original incident they were unclustered from.<br/>\nThis reverses a previous uncluster operation by moving mitigations back to their original incident.<br/>\n<br/><b>Scopes:</b>\n<ul>\n    <li>partner.company.classify</li>\n    <li>company.classify</li>\n</ul>"
      parameters:
      - name: company_id
        in: path
        description: company id
        required: true
        schema:
          type: integer
      - name: incident_id
        in: path
        description: incident id (the unclustered incident to recluster from)
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              example:
                report_id: 12345
                mitigation_id: 67890
                count: 5
                newState: Attack
        '400':
          description: Error explanation in error_message
          content:
            application/json:
              example:
                error_message: explanation
        '404':
          description: Incident/company were not found or incident was not unclustered
        '403':
          description: No permissions
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReclusterIncident'
        required: true
  /incident/{company_id}/scanback-list/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get list of Scanback Incidents
      description: "List of Incidents\n<br/><b>Scopes:</b>\n<ul>\n    <li>partner.all</li>\n    <li>company.all</li>\n    <li>partner.company.view</li>\n    <li>company.view</li>\n</ul>"
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: items_per_page
        in: query
        description: Number of items per page (optional, overrides default)
        required: false
        schema:
          type: integer
          default: 100
          minimum: 1
      - name: sort
        in: query
        description: 'Options: created | incidentID | emailSubject | senderName | senderEmail | recipientName | recipientEmail | classification | noSorting'
        required: false
        schema:
          type: string
          enum:
          - created
          - incidentID
          - emailSubject
          - senderName
          - senderEmail
          - recipientName
          - recipientEmail
          - classification
          - noSorting
          default: noSorting
      - name: order
        in: query
        description: 'Options: desc | asc'
        required: false
        schema:
          type: string
          enum:
          - desc
          - asc
          default: desc
      - name: created_start_time
        in: query
        description: Start of created date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: created_end_time
        in: query
        description: End of created date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: incidentID
        in: query
        description: The incident ID
        required: false
        schema:
          type: integer
      - name: search_email_subject
        in: query
        description: Search Email Subject
        required: false
        schema:
          type: string
          default: ''
      - name: search_sender_name
        in: query
        description: Search Sender Name
        required: false
        schema:
          type: string
          default: ''
      - name: search_sender_email
        in: query
        description: Search Sender Email
        required: false
        schema:
          type: string
          default: ''
      - name: search_recipient_name
        in: query
        description: Search Recipient Name
        required: false
        schema:
          type: string
          default: ''
      - name: search_recipient_email
        in: query
        description: Search Recipient Email
        required: false
        schema:
          type: string
          default: ''
      - name: classification
        in: query
        description: 'Options: all | phishing | spam | compromised | safe | open | silent(can select multiple by repeating fields (field1=value1&field1=value2&field1=value3...))'
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - all
            - phishing
            - spam
            - compromised
            - safe
            - open
            - silent
          default:
          - all
      - name: challenged_type
        in: query
        description: 'Filter by challenge type. Options: release_request, end_user_report'
        required: false
        schema:
          type: string
          enum:
          - release_request
          - end_user_report
      - name: challenged_start_date
        in: query
        description: Start of challenged date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: challenged_end_date
        in: query
        description: End of challenged date range, ISO Date with percent encoding. For example 2025-03-18T13:45:30.635993%2B00:00
        required: false
        schema:
          type: string
          format: date-time
      - name: state
        in: query
        description: 'Options: all | classified | unclassified(can select multiple by repeating fields (field1=value1&field1=value2&field1=value3...))'
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - all
            - classified
            - unclassified
          default:
          - all
      - name: company_id
        in: path
        description: company id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanBackPage'
        '400':
          description: Error explanation in error_message
          content:
            application/json:
              example:
                error_message: explanation
        '404':
          description: Incident or page were not found
        '403':
          description: No permissions
      tags:
      - Incident
  /incident/{company_id}/stats/remediation-statuses/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Remediation statuses stats
      description: '<b>Rate Limit</b>: 20 requests per second<br /><b>Scopes:</b><ul><li>company.view</li></ul>'
      parameters:
      - name: start_time
        in: query
        description: iso-8601 format
        required: true
        schema:
          type: string
          format: date-time
      - name: end_time
        in: query
        description: iso-8601 format
        required: true
        schema:
          type: string
          format: date-time
      - name: include_scanback
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemediationStatusesStats'
        '400':
          description: Validation Errors
          content:
            application/json:
              example:
              - end_time:
                - This field is required.
                start_time:
                - This field is required.
              - end_time:
                - 'Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z].'
                start_time:
                - 'Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z].'
              - end_time:
                - The `end_time` must be later than the `start_time`.
              - end_time:
                - The time range between `start_time` and `end_time` cannot exceed 365 days.
              - include_scanback:
                - Must be a valid boolean.
        '404':
          description: Company was not found
          content:
            application/json:
              example:
              - message: Company not found
        '403':
          description: Permission Denied
          content:
            application/json:
              example:
              - detail: Missing JWT
              - detail: You do not have permission to perform this action.
              - message: You do not have permission for company <company_id>
        '429':
          description: Too many requests
          content:
            application/json:
              example:
              - detail: Request was throttled. Expected available in 60 seconds.
      tags:
      - Incident
  /incident/{company_id}/uncluster/{incident_id}:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: incident_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: Uncluster incident
      description: "Uncluster mitigations from an incident to create a new incident with a different classification.<br/>\n<br/><b>Scopes:</b>\n<ul>\n    <li>partner.company.classify</li>\n    <li>company.classify</li>\n</ul>"
      parameters:
      - name: company_id
        in: path
        description: company id
        required: true
        schema:
          type: integer
      - name: incident_id
        in: path
        description: incident id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              example:
                report_id: 12345
                mitigation_id: 67890
                count: 5
                newState: Attack
        '400':
          description: Error explanation in error_message
          content:
            application/json:
              example:
                error_message: explanation
        '404':
          description: Incident/company were not found
        '403':
          description: No permissions
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnclusterIncident'
        required: true
  /incident/{company_id}/{status}/:
    parameters:
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    - name: status
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: Get IDs list of unclassified incidents
      description: "Get ids of open incidents<br/>\n<br/><b>Scopes:</b>\n<ul>\n    <li>partner.all</li>\n    <li>partner.company.view</li>\n    <li>company.view</li>\n</ul>\n<br/><b>Status:</b>\n<ul><li>open</li></ul>"
      parameters:
      - name: company_id
        in: path
        description: company id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              example:
                incident_ids:
                - 1
                - 2
                - 3
        '404':
          description: No company were found that matching the query
        '403':
          description: No permissions
      tags:
      - Incident
components:
  schemas:
    ScanBackPage:
      required:
      - page
      - total_pages
      - total_count
      - incidents
      type: object
      properties:
        page:
          title: Page
          type: integer
        total_pages:
          title: Total pages
          type: integer
        total_count:
          title: Total count
          type: integer
        incidents:
          type: array
          items:
            $ref: '#/components/schemas/ScanBackList'
    Link:
      required:
      - url
      - name
      - scan_result
      type: object
      properties:
        url:
          title: Url
          type: string
          minLength: 1
        name:
          title: Name
          type: string
          minLength: 1
        scan_result:
          title: Scan result
          type:
          - string
          - 'null'
          minLength: 1
    AccountTakeoverRemediationResponse:
      required:
      - state
      type: object
      properties:
        state:
          title: State
          description: 'Updated incident state: 2 (Safe), 3 (Compromised)'
          type: integer
          enum:
          - 2
          - 3
    UnclusterIncident:
      required:
      - classification
      type: object
      properties:
        mitigationsList:
          description: List of mitigation IDs to move.
          type: array
          items:
            type: integer
        excludeMitigations:
          description: List of mitigation IDs to exclude when using the 'all' flag.
          type: array
          items:
            type: integer
          default: []
        notFoundFilter:
          title: Notfoundfilter
          description: Filter mitigations that were not found in mailbox.
          type: boolean
          default: false

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