Demisto Incidents API

swagger: '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
host: hostname:443
schemes:
- https
consumes:
- application/json
- application/xml
produces:
- application/json
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
      parameters:
      - name: filter
        in: body
        required: true
        schema:
          $ref: '#/definitions/SearchIncidentsData'
      responses:
        '200':
          description: incidentSearchResponse
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/Incident'
              total:
                type: integer
      tags:
      - Incidents
definitions:
  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: '#/definitions/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: '#/definitions/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: '#/definitions/RunStatus'
      severity:
        $ref: '#/definitions/Severity'
      sla:
        $ref: '#/definitions/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: '#/definitions/IncidentStatus'
      type:
        description: Incident type
        type: string
        x-go-name: Type
      version:
        type: integer
        format: int64
        x-go-name: Versn
      CustomFields:
        $ref: '#/definitions/CustomFields'
    additionalProperties:
      type: object
    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: '#/definitions/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: '#/definitions/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: '#/definitions/RunStatus'
      severity:
        $ref: '#/definitions/Severity'
      sla:
        $ref: '#/definitions/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: '#/definitions/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
  IncidentStatus:
    description: IncidentStatus is the status of the incident
    type: number
    format: double
    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
  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
  SLAState:
    description: SLAState is the incident sla at closure time
    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
  SearchIncidentsData:
    type: object
    title: SearchIncidentsData ...
    properties:
      filter:
        $ref: '#/definitions/IncidentFilter'
      userFilter:
        type: boolean
        x-go-name: FilterByUser
    x-go-package: github.com/demisto/server/web
  RunStatus:
    description: RunStatus of a job
    type: string
    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
  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
  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: '#/definitions/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: '#/definitions/IncidentWrapper'
      level:
        type: array
        items:
          $ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/Order'
        x-go-name: Sort
      status:
        type: array
        items:
          $ref: '#/definitions/IncidentStatus'
        x-go-name: Status
      systems:
        type: array
        items:
          type: string
        x-go-name: Systems
      timeFrame:
        $ref: '#/definitions/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
  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
  Severity:
    description: Severity is the incident severity
    type: number
    format: double
    x-go-package: github.com/demisto/server/domain
securityDefinitions:
  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