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 Evidence 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: 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
      parameters:
      - name: Evidence
        in: body
        schema:
          $ref: '#/definitions/Evidence'
      responses:
        '200':
          description: The new / updated Evidence
          schema:
            $ref: '#/definitions/Evidence'
      tags:
      - Evidence
  /evidence/delete:
    post:
      description: Delete an evidence entity
      summary: delete evidence
      operationId: deleteEvidenceOp
      parameters:
      - name: deleteEvidence id
        in: body
        schema:
          $ref: '#/definitions/deleteEvidence'
      responses:
        '200':
          description: Deleted evidence ID
      tags:
      - Evidence
  /evidence/search:
    post:
      description: Search for an evidence entutiy by filter
      summary: Search evidence
      operationId: searchEvidence
      parameters:
      - name: evidencesFilterWrapper
        in: body
        schema:
          $ref: '#/definitions/evidencesFilterWrapper'
      responses:
        '200':
          description: EvidencesSearchResponse
          schema:
            $ref: '#/definitions/EvidencesSearchResponse'
      tags:
      - Evidence
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
  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
  deleteEvidence:
    type: object
    properties:
      evidenceID:
        type: string
        x-go-name: EvidenceID
    x-go-package: github.com/demisto/server/web
  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
  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: '#/definitions/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: '#/definitions/Order'
        x-go-name: Sort
      timeFrame:
        $ref: '#/definitions/Duration'
      toDate:
        type: string
        format: date-time
        x-go-name: ToDate
    x-go-package: github.com/demisto/server/repo/entities
  EvidencesSearchResponse:
    description: EvidencesSearchResponse returns the response from the evidences search
    type: object
    properties:
      evidences:
        $ref: '#/definitions/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
  Evidences:
    description: Evidences is a list of evidence entities
    type: array
    items:
      $ref: '#/definitions/Evidence'
    x-go-package: github.com/demisto/server/domain
  evidencesFilterWrapper:
    type: object
    properties:
      filter:
        $ref: '#/definitions/GenericStringDateFilter'
      incidentID:
        type: string
        x-go-name: IncidentID
    x-go-package: github.com/demisto/server/web
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