Demisto Evidence 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 Evidence API
  version: 2.0.0
servers:
- url: https://hostname:443
security:
- api_key: []
- csrf_token: []
- x-xdr-auth-id: []
tags:
- name: Evidence
paths:
  /evidence:
    post:
      description: 'Save an evidence entity

        To update evidence custom fields you should lowercase them and remove all spaces. For example: Scan IP -> scanip'
      summary: Save evidence
      operationId: saveEvidence
      responses:
        '200':
          description: The new / updated Evidence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evidence'
      tags:
      - Evidence
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Evidence'
          application/xml:
            schema:
              $ref: '#/components/schemas/Evidence'
  /evidence/delete:
    post:
      description: Delete an evidence entity
      summary: delete evidence
      operationId: deleteEvidenceOp
      responses:
        '200':
          description: Deleted evidence ID
      tags:
      - Evidence
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deleteEvidence'
          application/xml:
            schema:
              $ref: '#/components/schemas/deleteEvidence'
  /evidence/search:
    post:
      description: Search for an evidence entutiy by filter
      summary: Search evidence
      operationId: searchEvidence
      responses:
        '200':
          description: EvidencesSearchResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidencesSearchResponse'
      tags:
      - Evidence
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/evidencesFilterWrapper'
          application/xml:
            schema:
              $ref: '#/components/schemas/evidencesFilterWrapper'
components:
  schemas:
    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
    EvidencesSearchResponse:
      description: EvidencesSearchResponse returns the response from the evidences search
      type: object
      properties:
        evidences:
          $ref: '#/components/schemas/Evidences'
        total:
          type: integer
          format: int64
          x-go-name: Total
      x-go-package: github.com/demisto/server/repo/entities
    Evidence:
      type: object
      title: Evidence details.
      properties:
        ShardID:
          type: integer
          format: int64
        description:
          description: The description for the resolve
          type: string
          x-go-name: Description
        entryId:
          description: The entry ID
          type: string
          x-go-name: EntryID
        fetched:
          description: when the evidence entry was fetched
          type: string
          format: date-time
          x-go-name: Fetched
        hasRole:
          description: Internal field to make queries on role faster
          type: boolean
          x-go-name: HasRole
        id:
          type: string
          x-go-name: ID
        incidentId:
          description: The incident ID
          type: string
          x-go-name: IncidentID
        markedBy:
          description: the user that marked this evidence
          type: string
          x-go-name: MarkedBy
        markedDate:
          description: when this evidence was marked
          type: string
          format: date-time
          x-go-name: MarkedDate
        modified:
          type: string
          format: date-time
          x-go-name: Modified
        occurred:
          description: When this evidence has occurred
          type: string
          format: date-time
          x-go-name: Occurred
        previousRoles:
          description: PreviousRoleName - do not change this field manually
          type: array
          items:
            type: string
          x-go-name: PreviousRoleName
        roles:
          description: The role assigned to this investigation
          type: array
          items:
            type: string
          x-go-name: RoleName
        sortValues:
          type: array
          items:
            type: string
          x-go-name: SortValues
        tags:
          description: Tags
          type: array
          items:
            type: string
          x-go-name: Tags
        tagsRaw:
          description: TagsRaw
          type: array
          items:
            type: string
          x-go-name: TagsRaw
        taskId:
          description: when the evidence entry was fetched
          type: string
          x-go-name: TaskID
        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
    evidencesFilterWrapper:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/GenericStringDateFilter'
        incidentID:
          type: string
          x-go-name: IncidentID
      x-go-package: github.com/demisto/server/web
    deleteEvidence:
      type: object
      properties:
        evidenceID:
          type: string
          x-go-name: EvidenceID
      x-go-package: github.com/demisto/server/web
    Evidences:
      description: Evidences is a list of evidence entities
      type: array
      items:
        $ref: '#/components/schemas/Evidence'
      x-go-package: github.com/demisto/server/domain
    GenericStringDateFilter:
      description: GenericStringDateFilter is a general filter that will fetch entities using the Query value and a date filter
      type: object
      properties:
        Cache:
          description: Cache of join functions
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        fromDate:
          type: string
          format: date-time
          x-go-name: FromDate
        fromDateLicense:
          type: string
          format: date-time
          x-go-name: FromDateLicenseVal
        page:
          description: 0-based page
          type: integer
          format: int64
          x-go-name: Page
        period:
          $ref: '#/components/schemas/Period'
        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
  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