Demisto Incident API

openapi: 3.2.0
info:
  description: 'This is the public REST API to integrate with the demisto server.

    HTTP request can be sent using any HTTP-client.


    For an example dedicated client take a look at: https://github.com/demisto/demisto-py.


    Requests must include API-key that can be generated in the Demisto web client under ''Settings'' -> ''Integrations'' -> ''API keys''



    Optimistic Locking and Versioning\:


    When using Demisto REST API, you will need to make sure to work on the latest version of the item (incident, entry, etc.), otherwise, you will get a DB version error (which not allow you to override a newer item).

    In addition, you can pass ''version\: -1'' to force data override (make sure that other users data might be lost).


    Assume that Alice and Bob both read the same data from Demisto server, then they both changed the data, and then both tried to write the new versions back to the server. Whose changes should be saved? Alice’s? Bob’s?

    To solve this, each data item in Demisto has a numeric incremental version.

    If Alice saved an item with version 4 and Bob trying to save the same item with version 3, Demisto will rollback Bob request and returns a DB version conflict error.

    Bob will need to get the latest item and work on it so Alice work will not get lost.


    Example request using ''curl''\:


    ```

    curl ''https://hostname:443/incidents/search'' -H ''content-type: application/json'' -H ''accept: application/json'' -H ''Authorization: <API Key goes here>'' --data-binary ''{"filter":{"query":"-status:closed -category:job","period":{"by":"day","fromValue":7}}}'' --compressed

    ```'
  title: Demisto Apikeys Incident API
  version: 2.0.0
servers:
- url: https://hostname:443
security:
- api_key: []
- csrf_token: []
- x-xdr-auth-id: []
tags:
- name: Incident
paths:
  /incident:
    post:
      description: 'Create or update incident according to JSON structure.

        To update incident custom fields you should lowercase them and remove all spaces. For example: Scan IP -> scanip

        To get the actual key name you can also go to Demisto CLI and run /incident_add and look for the key that you would like to update


        Use the ''createInvestigation\: True'' to start the investigation process automatically. (by running a playbook based on incident type.)'
      summary: Create single incident
      operationId: createIncident
      responses:
        '200':
          description: IncidentWrapper
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentWrapper'
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIncidentRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/CreateIncidentRequest'
  /incident/batch:
    post:
      description: 'Create or update an incidents batch

        To update incident custom fields you should lowercase them and remove all spaces. For example: Scan IP -> scanip

        To get the actual key name you can also go to Demisto CLI and run /incident_add and look for the key that you would like to update'
      summary: Batch create incidents
      operationId: createIncidentsBatch
      responses:
        '200':
          description: IncidentSearchResponseWrapper
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentSearchResponseWrapper'
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDataBatch'
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateDataBatch'
  /incident/batch/exportToCsv:
    post:
      description: Exports an incidents batch to CSV file (returns file ID)
      summary: Batch export incidents to csv
      operationId: exportIncidentsToCsvBatch
      responses:
        '200':
          description: csv file name
          content:
            application/json:
              schema:
                type: string
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDataBatch'
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateDataBatch'
  /incident/batchClose:
    post:
      description: 'Closes an incidents batch

        To update incident custom fields you should lowercase them and remove all spaces. For example: Scan IP -> scanip

        To get the actual key name you can also go to Demisto CLI and run /incident_add and look for the key that you would like to update'
      summary: Batch close incidents
      operationId: closeIncidentsBatch
      responses:
        '200':
          description: IncidentSearchResponseWrapper
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentSearchResponseWrapper'
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDataBatch'
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateDataBatch'
  /incident/batchDelete:
    post:
      description: Deletes an incidents batch
      summary: Batch delete incidents
      operationId: deleteIncidentsBatch
      responses:
        '200':
          description: IncidentSearchResponseWrapper
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentSearchResponseWrapper'
      tags:
      - Incident
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDataBatch'
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateDataBatch'
  /incident/csv/{id}:
    get:
      description: Get an incident CSV file that was exported, by ID
      summary: Get incident as CSV
      operationId: getIncidentAsCsv
      parameters:
      - description: CSV file to fetch (returned from batch export to csv call)
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Return Csv file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      tags:
      - Incident
  /incident/json:
    post:
      description: Create single incident from raw JSON, builds incident according to default mapping
      summary: Create incident from JSON
      operationId: createIncidentJson
      responses:
        '200':
          description: IncidentWrapper
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentWrapper'
      tags:
      - Incident
  /incident/upload/{id}:
    post:
      description: Add file attachement to an incidents
      operationId: incidentFileUpload
      parameters:
      - description: Incident id to update
        name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: IncidentWrapper
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentWrapper'
      tags:
      - Incident
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fileName:
                  type: string
                  description: file name
                fileComment:
                  type: string
                  description: file comment
                field:
                  type: string
                  description: field name to hold the attachment details. If not specified, `attachment` will be used.
                showMediaFile:
                  type: boolean
                  description: show media file
                last:
                  type: boolean
                  description: If set to true will create an investigation. Used for uploading after creating incident.
                file:
                  type: string
                  description: file
                  format: binary
              required:
              - file
components:
  schemas:
    Period:
      type: object
      title: Period holds the 'Period' query, such as last 3 days, last 6 hours, between 6 days from now until 3 days from now.
      properties:
        by:
          description: By is used for legacty, and if exists it will override ByTo and ByFrom
          type: string
          x-go-name: By
        byFrom:
          type: string
          x-go-name: ByFrom
        byTo:
          type: string
          x-go-name: ByTo
        field:
          type: string
          x-go-name: Field
        fromValue:
          type: string
          format: duration
          x-go-name: FromValue
        toValue:
          type: string
          format: duration
          x-go-name: ToValue
      x-go-package: github.com/demisto/server/domain
    UpdateDataBatch:
      type: object
      title: UpdateDataBatch ...
      properties:
        CustomFields:
          type: object
          additionalProperties:
            type: object
        all:
          type: boolean
          x-go-name: All
        closeNotes:
          type: string
          x-go-name: CloseNotes
        closeReason:
          type: string
          x-go-name: CloseReason
        columns:
          type: array
          items:
            type: string
          x-go-name: Columns
        data:
          type: object
          additionalProperties:
            type: object
          x-go-name: Data
        filter:
          $ref: '#/components/schemas/IncidentFilter'
        force:
          type: boolean
          x-go-name: Force
        ids:
          type: array
          items:
            type: string
          x-go-name: IDs
        line:
          type: string
          x-go-name: Line
        originalIncidentId:
          type: string
          x-go-name: OriginalIncidentID
        overrideInvestigation:
          type: boolean
          x-go-name: OverrideInvestigation
      x-go-package: github.com/demisto/server/web
    IncidentSearchResponseWrapper:
      description: IncidentSearchResponseWrapper is an extension for the IncidentSearchResponse type, which holds list of IncidentWrapper(s)
      type: object
      properties:
        data:
          description: 'in: body'
          type: array
          items:
            $ref: '#/components/schemas/IncidentWrapper'
          x-go-name: Data
        notUpdated:
          type: integer
          format: uint64
          x-go-name: NotUpdated
        total:
          type: integer
          format: int64
          x-go-name: Total
      x-go-package: github.com/demisto/server/domain
    Label:
      type: object
      title: Label ...
      properties:
        type:
          type: string
          x-go-name: Type
        value:
          type: string
          x-go-name: Value
      x-go-package: github.com/demisto/server/domain
    Order:
      description: Order struct holds a sort field and the direction of sorting
      type: object
      properties:
        asc:
          type: boolean
          x-go-name: Asc
        field:
          type: string
          x-go-name: Field
        fieldType:
          type: string
          x-go-name: FieldType
      x-go-package: github.com/demisto/server/domain
    Duration:
      description: 'A Duration represents the elapsed time between two instants

        as an int64 nanosecond count. The representation limits the

        largest representable duration to approximately 290 years.'
      type: integer
      format: int64
      x-go-package: time
    RunStatus:
      description: RunStatus of a job
      type: string
      x-go-package: github.com/demisto/server/domain
    IncidentFilter:
      type: object
      title: IncidentFilter allows for very simple filtering.
      properties:
        Cache:
          description: Cache of join functions
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        andOp:
          type: boolean
          x-go-name: AndOp
        category:
          type: array
          items:
            type: string
          x-go-name: Category
        details:
          type: string
          x-go-name: Details
        files:
          type: array
          items:
            type: string
          x-go-name: Files
        firstIncidentInPage:
          $ref: '#/components/schemas/IncidentWrapper'
        fromActivatedDate:
          type: string
          format: date-time
          x-go-name: FromActivatedDate
        fromClosedDate:
          type: string
          format: date-time
          x-go-name: FromClosedDate
        fromDate:
          type: string
          format: date-time
          x-go-name: FromDate
        fromDateLicense:
          type: string
          format: date-time
          x-go-name: FromDateLicenseVal
        fromDueDate:
          type: string
          format: date-time
          x-go-name: FromDueDate
        fromReminder:
          type: string
          format: date-time
          x-go-name: FromReminder
        id:
          type: array
          items:
            type: string
          x-go-name: ID
        includeTmp:
          type: boolean
          x-go-name: IncludeTmp
        investigation:
          type: array
          items:
            type: string
          x-go-name: Investigation
        lastIncidentInPage:
          $ref: '#/components/schemas/IncidentWrapper'
        level:
          type: array
          items:
            $ref: '#/components/schemas/Severity'
          x-go-name: Level
        name:
          type: array
          items:
            type: string
          x-go-name: Name
        nextPage:
          type: boolean
          x-go-name: NextPage
        notCategory:
          type: array
          items:
            type: string
          x-go-name: NotCategory
        notInvestigation:
          type: array
          items:
            type: string
          x-go-name: NotInvestigation
        notStatus:
          type: array
          items:
            $ref: '#/components/schemas/IncidentStatus'
          x-go-name: NotStatus
        page:
          description: 0-based page
          type: integer
          format: int64
          x-go-name: Page
        parent:
          type: array
          items:
            type: string
          x-go-name: Parent
        period:
          $ref: '#/components/schemas/Period'
        query:
          type: string
          x-go-name: Query
        reason:
          type: array
          items:
            type: string
          x-go-name: Reason
        searchAfter:
          description: Efficient next page, pass max sort value from previous page
          type: array
          items:
            type: string
          x-go-name: SearchAfter
        searchBefore:
          description: Efficient prev page, pass min sort value from next page
          type: array
          items:
            type: string
          x-go-name: SearchBefore
        sequentialPagesSearch:
          type: boolean
          x-go-name: SequentialPagesSearch
        size:
          description: Size is limited to 1000, if not passed it defaults to 0, and no results will return
          type: integer
          format: int64
          x-go-name: Size
        sort:
          description: The sort order
          type: array
          items:
            $ref: '#/components/schemas/Order'
          x-go-name: Sort
        status:
          type: array
          items:
            $ref: '#/components/schemas/IncidentStatus'
          x-go-name: Status
        systems:
          type: array
          items:
            type: string
          x-go-name: Systems
        timeFrame:
          $ref: '#/components/schemas/Duration'
        toActivatedDate:
          type: string
          format: date-time
          x-go-name: ToActivatedDate
        toClosedDate:
          type: string
          format: date-time
          x-go-name: ToClosedDate
        toDate:
          type: string
          format: date-time
          x-go-name: ToDate
        toDueDate:
          type: string
          format: date-time
          x-go-name: ToDueDate
        toReminder:
          type: string
          format: date-time
          x-go-name: ToReminder
        totalOnly:
          type: boolean
          x-go-name: TotalOnly
        type:
          type: array
          items:
            type: string
          x-go-name: Type
        urls:
          type: array
          items:
            type: string
          x-go-name: Urls
        users:
          type: array
          items:
            type: string
          x-go-name: Users
      x-go-package: github.com/demisto/server/repo/entities
    CreateIncidentRequest:
      description: CreateIncidentRequest is an extension for Incident entity, with additional field of changed-status for the web client
      type: object
      properties:
        ShardID:
          type: integer
          format: int64
        account:
          description: Account holds the tenant name so that slicing and dicing on the master can leverage bleve
          type: string
          x-go-name: Account
        activated:
          description: When was this activated
          type: string
          format: date-time
          x-go-name: Activated
        activatingingUserId:
          description: The user that activated this investigation
          type: string
          x-go-name: ActivatingUserID
        autime:
          description: AlmostUniqueTime is an attempt to have a unique sortable ID for an incident
          type: integer
          format: int64
          x-go-name: AlmostUniqueTime
        canvases:
          description: Canvases of the incident
          type: array
          items:
            type: string
          x-go-name: Canvases
        category:
          description: Category
          type: string
          x-go-name: Category
        closeNotes:
          description: Notes for closing the incident
          type: string
          x-go-name: CloseNotes
        closeReason:
          description: The reason for closing the incident (select from existing predefined values)
          type: string
          x-go-name: ArchiveReason
        closed:
          description: When was this closed
          type: string
          format: date-time
          x-go-name: Closed
        closingUserId:
          description: The user ID that closed this investigation
          type: string
          x-go-name: ClosingUserID
        createInvestigation:
          type: boolean
          x-go-name: CreateInvestigation
        created:
          description: When was this created
          type: string
          format: date-time
          x-go-name: Created
        details:
          description: The details of the incident - reason, etc.
          type: string
          x-go-name: Details
        droppedCount:
          description: DroppedCount ...
          type: integer
          format: int64
          x-go-name: DroppedCount
        dueDate:
          description: SLA
          type: string
          format: date-time
          x-go-name: DueDate
        hasRole:
          description: Internal field to make queries on role faster
          type: boolean
          x-go-name: HasRole
        id:
          type: string
          x-go-name: ID
        investigationId:
          description: Investigation that was opened as a result of the incoming event
          type: string
          x-go-name: Investigation
        isPlayground:
          description: IsPlayGround
          type: boolean
          x-go-name: IsPlayGround
        labels:
          description: Labels related to incident - each label is composed of a type and value
          type: array
          items:
            $ref: '#/components/schemas/Label'
          x-go-name: Labels
        lastOpen:
          type: string
          format: date-time
          x-go-name: LastOpen
        linkedCount:
          description: LinkedCount ...
          type: integer
          format: int64
          x-go-name: LinkedCount
        linkedIncidents:
          description: LinkedIncidents incidents that were marked as linked by user
          type: array
          items:
            type: string
          x-go-name: LinkedIncidents
        modified:
          type: string
          format: date-time
          x-go-name: Modified
        name:
          description: Incident Name - given by user
          type: string
          x-go-name: Name
        notifyTime:
          description: Incdicates when last this field was changed with a value that supposed to send a notification
          type: string
          format: date-time
          x-go-name: NotifyTime
        occurred:
          description: When this incident has really occurred
          type: string
          format: date-time
          x-go-name: Occurred
        openDuration:
          description: Duration incident was open
          type: integer
          format: int64
          x-go-name: OpenDuration
        owner:
          description: The user who owns this incident
          type: string
          x-go-name: OwnerID
        parent:
          description: Parent
          type: string
          x-go-name: Parent
        phase:
          description: Phase
          type: string
          x-go-name: Phase
        playbookId:
          description: The associated playbook for this incident
          type: string
          x-go-name: PlaybookID
        previousRoles:
          description: PreviousRoleName - do not change this field manually
          type: array
          items:
            type: string
          x-go-name: PreviousRoleName
        rawCategory:
          type: string
          x-go-name: RawCategory
        rawCloseReason:
          description: The reason for closing the incident (select from existing predefined values)
          type: string
          x-go-name: RawArchiveReason
        rawJSON:
          type: string
          x-go-name: RawJSONData
        rawName:
          description: Incident RawName
          type: string
          x-go-name: RawName
        rawPhase:
          description: RawPhase
          type: string
          x-go-name: RawPhase
        rawType:
          description: Incident raw type
          type: string
          x-go-name: RawType
        reason:
          description: The reason for the resolve
          type: string
          x-go-name: Reason
        reminder:
          description: When if at all to send a reminder
          type: string
          format: date-time
          x-go-name: Reminder
        roles:
          description: The role assigned to this investigation
          type: array
          items:
            type: string
          x-go-name: RoleName
        runStatus:
          $ref: '#/components/schemas/RunStatus'
        severity:
          $ref: '#/components/schemas/Severity'
        sla:
          $ref: '#/components/schemas/SLAState'
        sortValues:
          type: array
          items:
            type: string
          x-go-name: SortValues
        sourceBrand:
          description: SourceBrand ...
          type: string
          x-go-name: SourceBrand
        sourceInstance:
          description: SourceInstance ...
          type: string
          x-go-name: SourceInstance
        status:
          $ref: '#/components/schemas/IncidentStatus'
        type:
          description: Incident type
          type: string
          x-go-name: Type
        version:
          type: integer
          format: int64
          x-go-name: Versn
        CustomFields:
          $ref: '#/components/schemas/CustomFields'
      additionalProperties:
        type: object
      x-go-package: github.com/demisto/server/domain
    Severity:
      description: Severity is the incident severity
      type: number
      format: double
      x-go-package: github.com/demisto/server/domain
    IncidentStatus:
      description: IncidentStatus is the status of the incident
      type: number
      format: double
      x-go-package: github.com/demisto/server/domain
    CustomFields:
      description: 'The keys should be the field''s display name all lower and without spaces. For example: Scan IP -> scanip

        To get the actual key name you can also go to Demisto CLI and run /incident_add and look for the key that you would like to update'
      type: object
      title: CustomFields ...
      additionalProperties:
        type: object
      x-go-package: github.com/demisto/server/domain
    SLAState:
      description: SLAState is the incident sla at closure time
      type: number
      format: double
      x-go-package: github.com/demisto/server/domain
    IncidentWrapper:
      description: IncidentWrapper is an extension of the Incident entity, which includes an additional field of changed-status for the web client
      type: object
      properties:
        ShardID:
          type: integer
          format: int64
        account:
          description: Account holds the tenant name so that slicing and dicing on the master can leverage bleve
          type: string
          x-go-name: Account
        activated:
          description: When was this activated
          type: string
          format: date-time
          x-go-name: Activated
        activatingingUserId:
          description: The user that activated this investigation
          type: string
          x-go-name: ActivatingUserID
        attachment:
          description: Attachments
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          x-go-name: Attachments
        autime:
          description: AlmostUniqueTime is an attempt to have a unique sortable ID for an incident
          type: integer
          format: int64
          x-go-name: AlmostUniqueTime
        canvases:
          description: Canvases of the incident
          type: array
          items:
            type: string
          x-go-name: Canvases
        category:
          description: Category
          type: string
          x-go-name: Category
        changeStatus:
          type: string
          x-go-name: ChangeStatus
        closeNotes:
          description: Notes for closing the incident
          type: string
          x-go-name: CloseNotes
        closeReason:
          description: The reason for closing the incident (select from existing predefined values)
          type: string
          x-go-name: ArchiveReason
        closed:
          description: When was this closed
          type: string
          format: date-time
          x-go-name: Closed
        closingUserId:
          description: The user ID that closed this investigation
          type: string
          x-go-name: ClosingUserID
        created:
          description: When was this created
          type: string
          format: date-time
          x-go-name: Created
        details:
          description: The details of the incident - reason, etc.
          type: string
          x-go-name: Details
        droppedCount:
          description: DroppedCount ...
          type: integer
          format: int64
          x-go-name: DroppedCount
        dueDate:
          description: SLA
          type: string
          format: date-time
          x-go-name: DueDate
        hasRole:
          description: Internal field to make queries on role faster
          type: boolean
          x-go-name: HasRole
        id:
          type: string
          x-go-name: ID
        insights:
          type: integer
          format: uint64
          x-go-name: Insights
        investigationId:
          description: Investigation that was opened as a result of the incoming event
          type: string
          x-go-name: Investigation
        isPlayground:
          description: IsPlayGround
          type: boolean
          x-go-name: IsPlayGround
        labels:
          description: Labels related to incident - each label is composed of a type and value
          type: array
          items:
            $ref: '#/components/schemas/Label'
          x-go-name: Labels
        lastOpen:
          type: string
          format: date-time
          x-go-name: LastOpen
        linkedCount:
          description: LinkedCount ...
          type: integer
          format: int64
          x-go-name: LinkedCount
        linkedIncidents:
          description: LinkedIncidents incidents that were marked as linked by user
          type: array
          items:
            type: string
          x-go-name: LinkedIncidents
        modified:
          type: string
          format: date-time
          x-go-name: Modified
        name:
          description: Incident Name - given by user
          type: string
          x-go-name: Name
        notifyTime:
          description: Incdicates when last this field was changed with a value that supposed to send a notification
          type: string
          format: date-time
          x-go-name: NotifyTime
        occurred:
          description: When this incident has really occurred
          type: string
          format: date-time
          x-go-name: Occurred
        openDuration:
          description: Duration incident was open
          type: integer
          format: int64
          x-go-name: OpenDuration
        owner:
          description: The user who owns this incident
          type: string
          x-go-name: OwnerID
        parent:
          description: Parent
          type: string
          x-go-name: Parent
        phase:
          description: Phase
          type: string
          x-go-name: Phase
        playbookId:
          description: The associated playbook for this incident
          type: string
          x-go-name: PlaybookID
        previousRoles:
          description: PreviousRoleName - do not change this field manually
          type: array
          items:
            type: string
          x-go-name: PreviousRoleName
        rawCategory:
          type: string
          x-go-name: RawCategory
        rawCloseReason:
          description: The reason for closing the incident (select from existing predefined values)
          type: string
          x-go-name: RawArchiveReason
        rawJSON:
          type: string
          x-go-name: RawJSONData
        rawName:
          description: Incident RawName
          type: string
          x-go-name: RawName
        rawPhase:
          description: RawPhase
          type: string
          x-go-name: RawPhase
        rawType:
          description: Incident raw type
          type: string
          x-go-name: RawType
        reason:
          description: The reason for the resolve
          type: string
          x-go-name: Reason
        reminder:
          description: When if at all to send a reminder
          type: string
          format: date-time
          x-go-name: Reminder
        roles:
          description: The role assigned to this investigation
          type: array
          items:
            type: string
          x-go-name: RoleName
        runStatus:
          $ref: '#/components/schemas/RunStatus'
        severity:
          $ref: '#/components/schemas/Severity'
        sla:
          $ref: '#/components/schemas/SLAState'
        sortValues:
          type: array
          items:
            type: string
          x-go-name: SortValues
        sourceBrand:
          description: SourceBrand ...
          type: string
          x-go-name: SourceBrand
        sourceInstance:
          description: SourceInstance ...
          type: string
          x-go-name: SourceInstance
        status:
          $ref: '#/components/schemas/IncidentStatus'
        type:
          description: Incident type
          type: string
          x-go-name: Type
        version:
          type: integer
          format: int64
          x-go-name: Versn
      additionalProperties:
        type: object
      x-go-package: github.com/demisto/server/domain
    Attachment:
      type: objec

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