Demisto Incident 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 Incident 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: 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
      parameters:
      - name: CreateIncidentRequest
        in: body
        schema:
          $ref: '#/definitions/CreateIncidentRequest'
      responses:
        '200':
          description: IncidentWrapper
          schema:
            $ref: '#/definitions/IncidentWrapper'
      tags:
      - Incident
  /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
      parameters:
      - name: UpdateDataBatch
        in: body
        schema:
          $ref: '#/definitions/UpdateDataBatch'
      responses:
        '200':
          description: IncidentSearchResponseWrapper
          schema:
            $ref: '#/definitions/IncidentSearchResponseWrapper'
      tags:
      - Incident
  /incident/batch/exportToCsv:
    post:
      description: Exports an incidents batch to CSV file (returns file ID)
      summary: Batch export incidents to csv
      operationId: exportIncidentsToCsvBatch
      parameters:
      - name: UpdateDataBatch
        in: body
        schema:
          $ref: '#/definitions/UpdateDataBatch'
      responses:
        '200':
          description: csv file name
          schema:
            type: string
      tags:
      - Incident
  /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
      parameters:
      - name: UpdateDataBatch
        in: body
        schema:
          $ref: '#/definitions/UpdateDataBatch'
      responses:
        '200':
          description: IncidentSearchResponseWrapper
          schema:
            $ref: '#/definitions/IncidentSearchResponseWrapper'
      tags:
      - Incident
  /incident/batchDelete:
    post:
      description: Deletes an incidents batch
      summary: Batch delete incidents
      operationId: deleteIncidentsBatch
      parameters:
      - name: UpdateDataBatch
        in: body
        schema:
          $ref: '#/definitions/UpdateDataBatch'
      responses:
        '200':
          description: IncidentSearchResponseWrapper
          schema:
            $ref: '#/definitions/IncidentSearchResponseWrapper'
      tags:
      - Incident
  /incident/csv/{id}:
    get:
      description: Get an incident CSV file that was exported, by ID
      produces:
      - application/octet-stream
      summary: Get incident as CSV
      operationId: getIncidentAsCsv
      parameters:
      - type: string
        description: CSV file to fetch (returned from batch export to csv call)
        name: id
        in: path
        required: true
      responses:
        '200':
          description: Return Csv file
          schema:
            type: file
      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
          schema:
            $ref: '#/definitions/IncidentWrapper'
      tags:
      - Incident
  /incident/upload/{id}:
    post:
      description: Add file attachement to an incidents
      consumes:
      - multipart/form-data
      operationId: incidentFileUpload
      parameters:
      - type: string
        description: Incident id to update
        name: id
        in: path
      - type: string
        description: file name
        name: fileName
        in: formData
      - type: string
        description: file comment
        name: fileComment
        in: formData
      - type: string
        description: field name to hold the attachment details. If not specified, `attachment` will be used.
        name: field
        in: formData
      - type: boolean
        description: show media file
        name: showMediaFile
        in: formData
      - type: boolean
        description: If set to true will create an investigation. Used for uploading after creating incident.
        name: last
        in: formData
      - type: file
        description: file
        name: file
        in: formData
        required: true
      responses:
        '200':
          description: IncidentWrapper
          schema:
            $ref: '#/definitions/IncidentWrapper'
      tags:
      - Incident
definitions:
  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: '#/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
  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
  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: '#/definitions/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
  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
  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: '#/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
  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
  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: '#/definitions/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
  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
  IncidentStatus:
    description: IncidentStatus is the status of the incident
    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