Demisto Investigations 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 Investigations API
  version: 2.0.0
servers:
- url: https://hostname:443
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
      responses:
        '200':
          description: investigationSearchResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestigationSearchResponse'
      tags:
      - Investigations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvestigationFilter'
          application/xml:
            schema:
              $ref: '#/components/schemas/InvestigationFilter'
components:
  schemas:
    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: '#/components/schemas/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: '#/components/schemas/InvestigationStatus'
        systems:
          description: The systems involved
          type: array
          items:
            $ref: '#/components/schemas/System'
          x-go-name: Systems
        tags:
          description: Tags
          type: array
          items:
            type: string
          x-go-name: Tags
        type:
          $ref: '#/components/schemas/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
    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
    InvestigationSearchResponse:
      description: InvestigationSearchResponse returns the response from the investigation search
      type: object
      properties:
        data:
          description: 'in: body'
          type: array
          items:
            $ref: '#/components/schemas/Investigation'
          x-go-name: Data
        total:
          type: integer
          format: int64
          x-go-name: Total
      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
    RunStatus:
      description: RunStatus of a job
      type: string
      x-go-package: github.com/demisto/server/domain
    System:
      description: System - URL stands for ip or hostname
      type: object
      properties:
        agent:
          $ref: '#/components/schemas/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: '#/components/schemas/TerminalOptions'
        user:
          type: string
          x-go-name: User
        workgroup:
          type: string
          x-go-name: Workgroup
      x-go-package: github.com/demisto/server/domain
    InvestigationType:
      type: number
      format: double
      title: InvestigationType ...
      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
    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: '#/components/schemas/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: '#/components/schemas/Order'
          x-go-name: Sort
        status:
          type: array
          items:
            $ref: '#/components/schemas/InvestigationStatus'
          x-go-name: Status
        timeFrame:
          $ref: '#/components/schemas/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: '#/components/schemas/InvestigationType'
          x-go-name: Type
        user:
          type: array
          items:
            type: string
          x-go-name: User
      x-go-package: github.com/demisto/server/repo/entities
    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
    InvestigationStatus:
      description: InvestigationStatus is the status type
      type: number
      format: double
      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