Demisto Incidents 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 Incidents API
  version: 2.0.0
servers:
- url: https://hostname:443
security:
- api_key: []
- csrf_token: []
- x-xdr-auth-id: []
tags:
- name: Incidents
paths:
  /incidents/search:
    post:
      description: 'This will search incidents across all indices

        You can filter by multiple options'
      summary: Search incidents by filter
      operationId: searchIncidents
      responses:
        '200':
          description: incidentSearchResponse
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Incident'
                  total:
                    type: integer
      tags:
      - Incidents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchIncidentsData'
          application/xml:
            schema:
              $ref: '#/components/schemas/SearchIncidentsData'
        required: true
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
    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
    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
    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
    Incident:
      description: 'An incident can be manually opened algorithmically or arrive from an external source like SIEM.

        If you add fields, make sure to add them to the mapping as well.

        If adding a user controlled field, please

        make sure to add it to the CopyFrom  and getIncidentFieldString (in services package) methods.'
      type: object
      title: Incident details.
      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
        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
        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
    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
    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
    SearchIncidentsData:
      type: object
      title: SearchIncidentsData ...
      properties:
        filter:
          $ref: '#/components/schemas/IncidentFilter'
        userFilter:
          type: boolean
          x-go-name: FilterByUser
      x-go-package: github.com/demisto/server/web
    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: object
      title: Attachment ...
      properties:
        description:
          type: string
          x-go-name: Description
        name:
          type: string
          x-go-name: Name
        path:
          type: string
          x-go-name: Path
        showMediaFile:
          type: boolean
          x-go-name: ShowMediaFile
        type:
          type: string
          x-go-name: Type
      x-go-package: github.com/demisto/server/domain
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    csrf_token:
      type: apiKey
      name: X-XSRF-TOKEN
      in: header
    x-xdr-auth-id:
      type: apiKey
      name: x-xdr-auth-id
      in: header