Demisto Investigations 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 Investigations 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: Investigations
paths:
  /investigations/search:
    post:
      description: 'This will search investigations across all indices

        You can filter by multiple options'
      summary: Search investigations by filter
      operationId: searchInvestigations
      parameters:
      - name: filter
        in: body
        schema:
          $ref: '#/definitions/InvestigationFilter'
      responses:
        '200':
          description: investigationSearchResponse
          schema:
            $ref: '#/definitions/InvestigationSearchResponse'
      tags:
      - Investigations
definitions:
  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
  InvestigationFilter:
    type: object
    title: InvestigationFilter 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
      fromCloseDate:
        type: string
        format: date-time
        x-go-name: FromCloseDate
      fromDate:
        type: string
        format: date-time
        x-go-name: FromDate
      fromDateLicense:
        type: string
        format: date-time
        x-go-name: FromDateLicenseVal
      id:
        type: array
        items:
          type: string
        x-go-name: ID
      idsOnly:
        type: boolean
        x-go-name: IdsOnly
      includeChildInv:
        type: boolean
        x-go-name: IncludeChildInv
      name:
        type: array
        items:
          type: string
        x-go-name: Name
      notCategory:
        type: array
        items:
          type: string
        x-go-name: NotCategory
      notIDs:
        type: array
        items:
          type: string
        x-go-name: NotIDs
      page:
        description: 0-based page
        type: integer
        format: int64
        x-go-name: Page
      period:
        $ref: '#/definitions/Period'
      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
      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/InvestigationStatus'
        x-go-name: Status
      timeFrame:
        $ref: '#/definitions/Duration'
      toCloseDate:
        type: string
        format: date-time
        x-go-name: ToCloseDate
      toDate:
        type: string
        format: date-time
        x-go-name: ToDate
      type:
        type: array
        items:
          $ref: '#/definitions/InvestigationType'
        x-go-name: Type
      user:
        type: array
        items:
          type: string
        x-go-name: User
    x-go-package: github.com/demisto/server/repo/entities
  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
  System:
    description: System - URL stands for ip or hostname
    type: object
    properties:
      agent:
        $ref: '#/definitions/SystemAgent'
      arch:
        type: string
        x-go-name: Arch
      ciphers:
        type: array
        items:
          type: string
        x-go-name: Ciphers
      credentials:
        type: string
        x-go-name: CredentialsName
      engineId:
        type: string
        x-go-name: EngineID
      host:
        type: string
        x-go-name: Host
      integrationinstanceid:
        type: string
        x-go-name: IntegrationInstanceID
      issharedagent:
        type: boolean
        x-go-name: IsSharedAgent
      name:
        type: string
        x-go-name: Name
      os:
        type: string
        x-go-name: OS
      password:
        type: string
        x-go-name: Password
      smb:
        type: integer
        format: int64
        x-go-name: SMBv
      smbport:
        type: integer
        format: uint16
        x-go-name: SMBPort
      sshkey:
        type: string
        x-go-name: SSHKey
      sshport:
        type: integer
        format: uint16
        x-go-name: SSHPort
      terminalOptions:
        $ref: '#/definitions/TerminalOptions'
      user:
        type: string
        x-go-name: User
      workgroup:
        type: string
        x-go-name: Workgroup
    x-go-package: github.com/demisto/server/domain
  SystemAgent:
    description: SystemAgent - represents agent status and holds server context
    type: object
    properties:
      servercontext:
        type: array
        items:
          type: integer
          format: uint8
        x-go-name: ServerContext
    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
  InvestigationSearchResponse:
    description: InvestigationSearchResponse returns the response from the investigation search
    type: object
    properties:
      data:
        description: 'in: body'
        type: array
        items:
          $ref: '#/definitions/Investigation'
        x-go-name: Data
      total:
        type: integer
        format: int64
        x-go-name: Total
    x-go-package: github.com/demisto/server/repo/entities
  InvestigationType:
    type: number
    format: double
    title: InvestigationType ...
    x-go-package: github.com/demisto/server/domain
  Investigation:
    description: A special investigation called playground is created for each user-project combination and is a private space for the researcher to play in.
    type: object
    title: Investigation contains the investigation of a particular incident.
    properties:
      ShardID:
        type: integer
        format: int64
      category:
        description: Category of the investigation
        type: string
        x-go-name: Category
      childInvestigations:
        description: ChildInvestigations id's
        type: array
        items:
          type: string
        x-go-name: ChildInvestigations
      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
      creatingUserId:
        description: The user ID that created this investigation
        type: string
        x-go-name: CreatingUserID
      details:
        description: User defined free text details
        type: string
        x-go-name: Details
      entitlements:
        description: One time entitlements
        type: array
        items:
          type: string
        x-go-name: Entitlements
      entryUsers:
        description: EntryUsers
        type: array
        items:
          type: string
        x-go-name: EntryUsers
      hasRole:
        description: Internal field to make queries on role faster
        type: boolean
        x-go-name: HasRole
      id:
        type: string
        x-go-name: ID
      isChildInvestigation:
        description: IsChildInvestigation
        type: boolean
        x-go-name: IsChildInvestigation
      lastOpen:
        type: string
        format: date-time
        x-go-name: LastOpen
      mirrorAutoClose:
        description: MirrorAutoClose will tell us to close the Chat Module channel if we close investigation
        type: object
        additionalProperties:
          type: boolean
        x-go-name: MirrorAutoClose
      mirrorTypes:
        description: 'MirrorTypes holds info about mirror direction and message type to be mirrored

          message type can be either ''all'' or ''chat''

          direction can be either ''FromDemisto'', ''ToDemisto'' or ''Both'' if this investigation is mirrored'
        type: object
        additionalProperties:
          type: string
        x-go-name: MirrorTypes
      modified:
        type: string
        format: date-time
        x-go-name: Modified
      name:
        description: The name of the investigation, which is unique to the project
        type: string
        x-go-name: Name
      openDuration:
        description: Duration from open to close time
        type: integer
        format: int64
        x-go-name: OpenDuration
      parentInvestigation:
        description: ParentInvestigation - parent id, in case this is a child investigation of another investigation
        type: string
        x-go-name: ParentInvestigation
      persistentEntitlements:
        description: Persistent entitlement per tag. Empty tag will also return an entitlement
        type: object
        additionalProperties:
          type: string
        x-go-name: PersistentEntitlements
      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
      reason:
        description: The reason for the status (resolve)
        type: object
        additionalProperties:
          type: string
        x-go-name: Reason
      roles:
        description: The role assigned to this investigation
        type: array
        items:
          type: string
        x-go-name: RoleName
      runStatus:
        $ref: '#/definitions/RunStatus'
      slackMirrorAutoClose:
        description: DEPRECATED - DeprecatedSlackMirrorAutoClose will tell us to close the Slack channel if we close investigation
        type: boolean
        x-go-name: DeprecatedSlackMirrorAutoClose
      slackMirrorType:
        description: 'DEPRECATED - DeprecatedSlackMirrorType holds info about mirror direction and message type to be mirror

          message type can be either ''all'' or ''chat''

          direction can be either ''demisto2Slack'', ''slack2Demisto'' or ''both'' if this investigation is mirrored to Slack'
        type: string
        x-go-name: DeprecatedSlackMirrorType
      sortValues:
        type: array
        items:
          type: string
        x-go-name: SortValues
      status:
        $ref: '#/definitions/InvestigationStatus'
      systems:
        description: The systems involved
        type: array
        items:
          $ref: '#/definitions/System'
        x-go-name: Systems
      tags:
        description: Tags
        type: array
        items:
          type: string
        x-go-name: Tags
      type:
        $ref: '#/definitions/InvestigationType'
      users:
        description: The users who share this investigation
        type: array
        items:
          type: string
        x-go-name: Users
      version:
        type: integer
        format: int64
        x-go-name: Versn
    x-go-package: github.com/demisto/server/domain
  TerminalOptions:
    description: TerminalOptions - terminal options to use in case of using pty
    type: object
    properties:
      Echo:
        type: integer
        format: uint32
      Terminal:
        type: boolean
      TerminalHeight:
        type: integer
        format: int64
      TerminalType:
        type: string
      TerminalWidth:
        type: integer
        format: int64
      TyISpeed:
        type: integer
        format: uint32
      TyOSpeed:
        type: integer
        format: uint32
    x-go-package: github.com/demisto/server/domain
  RunStatus:
    description: RunStatus of a job
    type: string
    x-go-package: github.com/demisto/server/domain
  InvestigationStatus:
    description: InvestigationStatus is the status type
    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