Demisto Indicators 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 Indicators API
  version: 2.0.0
servers:
- url: https://hostname:443
security:
- api_key: []
- csrf_token: []
- x-xdr-auth-id: []
tags:
- name: Indicators
paths:
  /indicators/batch/export/stix:
    post:
      description: Exports an indicators batch to STIX file (returns file ID)
      summary: Batch export indicators to STIX
      operationId: exportIndicatorsToStixBatch
      responses:
        '200':
          description: STIX file name
          content:
            application/json:
              schema:
                type: string
      tags:
      - Indicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/genericIndicatorUpdateBatch'
          application/xml:
            schema:
              $ref: '#/components/schemas/genericIndicatorUpdateBatch'
  /indicators/batch/exportToCsv:
    post:
      description: Exports an indicators batch to CSV file (returns file ID)
      summary: Batch export indicators to csv
      operationId: exportIndicatorsToCsvBatch
      responses:
        '200':
          description: csv file name
          content:
            application/json:
              schema:
                type: string
      tags:
      - Indicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/genericIndicatorUpdateBatch'
          application/xml:
            schema:
              $ref: '#/components/schemas/genericIndicatorUpdateBatch'
        description: 'Required parameters from `genericIndicatorUpdateBatch`: `columns`,

          `filter`. You should also include either `all` or `ids`

          '
  /indicators/batchDelete:
    post:
      description: 'Batch whitelist or delete indicators entities

        In order to delete indicators and not whitelist, set doNotWhitelist boolean field to true'
      summary: Batch whitelist or delete indicators
      operationId: deleteIndicatorsBatch
      responses:
        '200':
          description: UpdateResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateResponse'
      tags:
      - Indicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/genericIndicatorUpdateBatch'
          application/xml:
            schema:
              $ref: '#/components/schemas/genericIndicatorUpdateBatch'
  /indicators/csv/{id}:
    get:
      description: Get an indicators CSV file that was exported, by ID
      summary: Get indicators as CSV
      operationId: getIndicatorsAsCsv
      parameters:
      - description: CSV file to fetch (returned from batch export to csv call)
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Return Csv file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      tags:
      - Indicators
  /indicators/feed/json:
    post:
      description: 'Create indicators from raw JSON (similar to ingesting from a feed). Builds indicators according to the specified feed classifier,

        or uses the default one if not specified.

        Indicator properties (all optional except for value): **value** (string, required) | **type** (string) | **score** (number, 0-3,

        default `0`, where `0` means None, `1` Good, `2` Suspicious, and `3` Bad) | **sourceBrand** (string, default `"External"`) | **sourceInstance**

        (string, default `"External"`) | **reliability** (string, one of `"A - Completely reliable"`, `"B - Usually reliable"`, `"C - Fairly

        reliable"`, `"D - Not usually reliable"`, `"E - Unreliable"`, `"F - Reliability cannot be judged"`) | **expirationPolicy** (string,

        one of `"never"`, `"interval"`, `"indicatorType"`) | **expirationInterval** (number, in minutes)'
      summary: Create feed indicators from JSON
      operationId: createFeedIndicatorsJson
      responses:
        '201':
          description: Indicators created
      tags:
      - Indicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedIndicatorsRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/FeedIndicatorsRequest'
        required: true
  /indicators/search:
    post:
      description: Search indicators by filter
      summary: Search indicators
      operationId: indicatorsSearch
      responses:
        '200':
          description: indicatorResult
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndicatorResult'
      tags:
      - Indicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndicatorFilter'
          application/xml:
            schema:
              $ref: '#/components/schemas/IndicatorFilter'
  /indicators/stix/v2/{id}:
    get:
      description: Get an indicators STIX V2 file that was exported, by ID
      summary: Get indicators as STIX V2
      operationId: getIndicatorsAsSTIX
      parameters:
      - description: STIX V2 file to fetch (returned from batch export to STIX call)
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Return STIX V2 file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      tags:
      - Indicators
  /indicators/upload:
    post:
      description: Create indicators from a file
      summary: Create indicators
      operationId: indicatorsCreateBatch
      responses:
        '200':
          description: IocObjects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IocObjects'
      tags:
      - Indicators
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fileName:
                  type: string
                  description: file name
                file:
                  type: string
                  description: file
                  format: binary
              required:
              - file
components:
  schemas:
    UpdateResponse:
      type: object
      title: UpdateResponse ...
      properties:
        notUpdated:
          type: integer
          format: int64
          x-go-name: NotUpdated
        updatedIds:
          type: array
          items:
            type: string
          x-go-name: UpdatedIds
      x-go-package: github.com/demisto/server/repo/entities
    IocObjects:
      type: array
      title: IocObjects ...
      items:
        $ref: '#/components/schemas/IocObject'
      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
    genericIndicatorUpdateBatch:
      type: object
      properties:
        all:
          type: boolean
          x-go-name: All
        columns:
          type: array
          items:
            type: string
          x-go-name: Columns
        doNotWhitelist:
          type: boolean
          x-go-name: DoNotWhitelist
        filter:
          $ref: '#/components/schemas/IndicatorFilter'
        ids:
          type: array
          items:
            type: string
          x-go-name: IDs
        reason:
          type: string
          x-go-name: Reason
        reputations:
          type: array
          items:
            type: string
          x-go-name: Reputations
      x-go-package: github.com/demisto/server/web
    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
    IndicatorResult:
      type: object
      title: IndicatorResult ...
      properties:
        iocObjects:
          $ref: '#/components/schemas/IocObjects'
        total:
          type: integer
          format: int64
          x-go-name: Total
      x-go-package: github.com/demisto/server/web
    InsightCache:
      description: InsightCache - map insight name to all its metadata, name will be case insensitive
      type: object
      properties:
        id:
          type: string
          x-go-name: ID
        modified:
          type: string
          format: date-time
          x-go-name: Modified
        scores:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DBotScore'
          x-go-name: Scores
        sequenceNumber:
          type: integer
          format: int64
          x-go-name: SeqNum
        sortValues:
          type: array
          items:
            type: string
          x-go-name: SortValues
        version:
          type: integer
          format: int64
          x-go-name: Versn
      x-go-package: github.com/demisto/server/domain
    IocObject:
      description: IocObject - represents an Ioc (or simply an indicator) object
      type: object
      properties:
        CustomFields:
          $ref: '#/components/schemas/CustomFields'
        account:
          type: string
          x-go-name: Account
        calculatedTime:
          description: Do not set the fields bellow this line
          type: string
          format: date-time
          x-go-name: CalculatedTime
        comment:
          type: string
          x-go-name: Comment
        firstSeen:
          type: string
          format: date-time
          x-go-name: FirstSeen
        firstSeenEntryID:
          type: string
          x-go-name: FirstSeenEntryID
        id:
          type: string
          x-go-name: ID
        indicator_type:
          type: string
          x-go-name: IndicatorType
        insightCache:
          $ref: '#/components/schemas/InsightCache'
        investigationIDs:
          type: array
          items:
            type: string
          x-go-name: InvestigationIDs
        lastReputationRun:
          type: string
          format: date-time
          x-go-name: LastReputationRun
        lastSeen:
          type: string
          format: date-time
          x-go-name: LastSeen
        lastSeenEntryID:
          type: string
          x-go-name: LastSeenEntryID
        manualScore:
          type: boolean
          x-go-name: ManualScore
        manualSetTime:
          type: string
          format: date-time
          x-go-name: ManualSetTime
        manuallyEditedFields:
          type: array
          items:
            type: string
          x-go-name: ManuallyEditedFields
        modified:
          type: string
          format: date-time
          x-go-name: Modified
        score:
          type: integer
          format: int64
          x-go-name: Score
        setBy:
          type: string
          x-go-name: SetBy
        sortValues:
          type: array
          items:
            type: string
          x-go-name: SortValues
        source:
          type: string
          x-go-name: Source
        timestamp:
          type: string
          format: date-time
          x-go-name: TimeStamp
        value:
          type: string
          x-go-name: Value
        version:
          type: integer
          format: int64
          x-go-name: Versn
      x-go-package: github.com/demisto/server/domain
    DateRangeFilter:
      description: DateRangeFilter provides common fields for date filtering
      type: object
      properties:
        fromDate:
          type: string
          format: date-time
          x-go-name: FromDate
        fromDateLicense:
          type: string
          format: date-time
          x-go-name: FromDateLicenseVal
        period:
          $ref: '#/components/schemas/Period'
        timeFrame:
          $ref: '#/components/schemas/Duration'
        toDate:
          type: string
          format: date-time
          x-go-name: ToDate
      x-go-package: github.com/demisto/server/repo/entities
    FeedIndicatorsRequest:
      description: FeedIndicatorsRequest is the input for JSON feed indicator ingestion
      type: object
      properties:
        bypassExclusionList:
          type: boolean
          x-go-name: ShouldBypassExclusionList
        classifierId:
          type: string
          x-go-name: ClassifierID
        indicators:
          type: array
          items:
            $ref: '#/components/schemas/RawFeedIndicator'
          x-go-name: Indicators
        mapperId:
          type: string
          x-go-name: MapperID
      x-go-package: github.com/demisto/server/web
    IndicatorFilter:
      description: IndicatorFilter is a general filter that fetches entities using a query string query using the Query value
      type: object
      properties:
        Cache:
          description: Cache of join functions
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        earlyTimeInPage:
          type: string
          format: date-time
          x-go-name: EarlyTimeInPage
        firstSeen:
          $ref: '#/components/schemas/DateRangeFilter'
        fromDate:
          type: string
          format: date-time
          x-go-name: FromDate
        fromDateLicense:
          type: string
          format: date-time
          x-go-name: FromDateLicenseVal
        lastSeen:
          $ref: '#/components/schemas/DateRangeFilter'
        laterTimeInPage:
          type: string
          format: date-time
          x-go-name: LaterTimeInPage
        page:
          description: 0-based page
          type: integer
          format: int64
          x-go-name: Page
        period:
          $ref: '#/components/schemas/Period'
        prevPage:
          description: MT support - these fields are for indicator search according to calculatedTime
          type: boolean
          x-go-name: PrevPage
        query:
          type: string
          x-go-name: Query
        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
        timeFrame:
          $ref: '#/components/schemas/Duration'
        toDate:
          type: string
          format: date-time
          x-go-name: ToDate
      x-go-package: github.com/demisto/server/repo/entities
    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
    DBotScore:
      description: DBotScore - Contain the score of a specific brand for a specific insight
      type: object
      properties:
        content:
          type: string
          x-go-name: Content
        contentFormat:
          type: string
          x-go-name: ContentFormat
        context:
          type: object
          additionalProperties:
            type: object
          x-go-name: Context
        isTypedIndicator:
          type: boolean
          x-go-name: IsTypedIndicator
        score:
          type: integer
          format: int64
          x-go-name: Score
        scoreChangeTimestamp:
          description: We need to track when the score changes to know if we need to re-calculate the overall score
          type: string
          format: date-time
          x-go-name: ScoreChangeTimeStamp
        timestamp:
          type: string
          format: date-time
          x-go-name: TimeStamp
        type:
          type: string
          x-go-name: Type
      x-go-package: github.com/demisto/server/domain
    RawFeedIndicator:
      description: RawFeedIndicator is an unparsed feed indicator from JSON ingestion
      type: object
      additionalProperties:
        type: object
      x-go-package: github.com/demisto/server/web
  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