Cisco XDR Event API

openapi: 3.2.0
info:
  title: Cisco Xdr Event API
  version: '1.0'
  description: 'Operations tagged Event across 2 of this provider''s published API definitions: cisco-xdr-ctia-openapi.json, cisco-xdr-iroh-event-openapi.json. Each path carries the servers of the definition it was published in.'
  x-provenance:
    method: harvested
    authored_by: Cisco XDR (CTIA)
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    note: Published by Cisco. Retrieved unmodified except for this x-provenance block.
    provider_published: true
    derived_view: Per-tag view of cisco-xdr-ctia-openapi.json, the provider's source document. Operations and schemas are the provider's, unmodified; only the partition is ours.
    derived_from: cisco-xdr-ctia-openapi.json
    operation_coverage: 6/9
  x-evidence:
  - type: source
    url: https://private.intel.amp.cisco.com/index.html
  - type: raw
    url: https://private.intel.amp.cisco.com/swagger.json
servers:
- url: /
- url: https://visibility.amp.cisco.com/
tags:
- name: Event
  description: Events operations
paths:
  /ctia/event/history/{entity_id}:
    servers:
    - url: /
    get:
      tags:
      - Event
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventBucket'
            application/x-yaml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventBucket'
            application/edn:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventBucket'
            application/transit+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventBucket'
            application/transit+msgpack:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventBucket'
      parameters:
      - in: path
        name: entity_id
        description: ''
        required: true
        schema:
          type: string
      summary: Timeline history of an entity
      description: Requires capability search-event.
      security:
      - JWT: []
      - oauth2:
        - private-intel
        - private-intel:read
        - private-intel:write
        - casebook
        - casebook:read
        - casebook:write
  /ctia/event/search:
    servers:
    - url: /
    get:
      tags:
      - Event
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartialEvent'
            application/x-yaml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartialEvent'
            application/edn:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartialEvent'
            application/transit+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartialEvent'
            application/transit+msgpack:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartialEvent'
      summary: Search for Event entities using a ES query syntax and field filters
      description: Requires capability search-event.
      parameters:
      - in: query
        name: sort_order
        description: Sort direction
        required: false
        schema:
          type: string
          enum:
          - desc
          - asc
      - in: query
        name: tlp
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: from
        description: ''
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: sort_by
        description: 'Sort result on fields.


          The following fields are supported: id, language, revision, schema_version, source, source_uri, timestamp, title, tlp


          Fields can be combined with '','' and sort order can be specified by '':asc'' and '':desc''. For example:


          -  id       # sort by id ascending

          -  id:desc  # sort by id descending

          -  id,language:desc  # sort by id ascending, then language descending'
        required: false
        schema:
          type: string
      - in: query
        name: fields
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - id
            - event_type
            - groups
            - timestamp
            - entity.type
            - owner
            - entity.id
      - in: query
        name: search_after
        description: Pagination stateless cursor
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - in: query
        name: language
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: id
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: limit
        description: Pagination Limit
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: offset
        description: Pagination Offset
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: query
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: simple_query
        description: Query String with simple query format
        required: false
        schema:
          type: string
      - in: query
        name: revision
        description: ''
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: to
        description: ''
        required: false
        schema:
          type: string
          format: date-time
      security:
      - JWT: []
      - oauth2:
        - private-intel
        - private-intel:read
        - private-intel:write
        - casebook
        - casebook:read
        - casebook:write
    delete:
      tags:
      - Event
      description: Requires capabilities delete-event, developer, search-event.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: integer
                format: int64
            application/x-yaml:
              schema:
                type: integer
                format: int64
            application/edn:
              schema:
                type: integer
                format: int64
            application/transit+json:
              schema:
                type: integer
                format: int64
            application/transit+msgpack:
              schema:
                type: integer
                format: int64
      summary: Delete Event entities matching given Lucene/ES query string or/and field filters
      parameters:
      - in: query
        name: tlp
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: from
        description: ''
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: search_after
        description: Pagination stateless cursor
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - in: query
        name: language
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: id
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: REALLY_DELETE_ALL_THESE_ENTITIES
        description: ' If you do not set this value or set it to false this route will perform a dry run. Set this value to true to perform the deletion. You MUST confirm you will fix the mess after the inevitable disaster that will occur after you perform that operation. DO NOT FORGET TO SET THAT TO FALSE AFTER EACH DELETION IF YOU INTEND TO USE THAT ROUTE MULTIPLE TIMES.'
        required: false
        schema:
          type: boolean
      - in: query
        name: wait_for
        description: wait for matched entity to be deleted
        required: false
        schema:
          type: boolean
      - in: query
        name: query
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: simple_query
        description: Query String with simple query format
        required: false
        schema:
          type: string
      - in: query
        name: revision
        description: ''
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: to
        description: ''
        required: false
        schema:
          type: string
          format: date-time
      security:
      - JWT: []
      - oauth2:
        - private-intel
        - private-intel:read
        - private-intel:write
        - casebook
        - casebook:read
        - casebook:write
  /ctia/event/search/count:
    servers:
    - url: /
    get:
      tags:
      - Event
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: integer
                format: int64
            application/x-yaml:
              schema:
                type: integer
                format: int64
            application/edn:
              schema:
                type: integer
                format: int64
            application/transit+json:
              schema:
                type: integer
                format: int64
            application/transit+msgpack:
              schema:
                type: integer
                format: int64
      summary: Count Event matching a Lucene/ES query string and field filters
      description: Requires capability search-event.
      parameters:
      - in: query
        name: tlp
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: from
        description: ''
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: search_after
        description: Pagination stateless cursor
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - in: query
        name: language
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: id
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: query
        description: ''
        required: false
        schema:
          type: string
      - in: query
        name: simple_query
        description: Query String with simple query format
        required: false
        schema:
          type: string
      - in: query
        name: revision
        description: ''
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: to
        description: ''
        required: false
        schema:
          type: string
          format: date-time
      security:
      - JWT: []
      - oauth2:
        - private-intel
        - private-intel:read
        - private-intel:write
        - casebook
        - casebook:read
        - casebook:write
  /ctia/event/{id}:
    servers:
    - url: /
    get:
      tags:
      - Event
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartialEvent'
            application/x-yaml:
              schema:
                $ref: '#/components/schemas/PartialEvent'
            application/edn:
              schema:
                $ref: '#/components/schemas/PartialEvent'
            application/transit+json:
              schema:
                $ref: '#/components/schemas/PartialEvent'
            application/transit+msgpack:
              schema:
                $ref: '#/components/schemas/PartialEvent'
      summary: Get one Event by ID
      parameters:
      - in: path
        name: id
        description: ''
        required: true
        schema:
          type: string
      - in: query
        name: fields
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - id
            - event_type
            - groups
            - timestamp
            - entity.type
            - owner
            - entity.id
      description: Requires capability read-event.
      security:
      - JWT: []
      - oauth2:
        - private-intel
        - private-intel:read
        - private-intel:write
        - casebook
        - casebook:read
        - casebook:write
    delete:
      tags:
      - Event
      responses:
        '204':
          description: ''
      x-no-doc: false
      parameters:
      - in: path
        name: id
        description: ''
        required: true
        schema:
          type: string
      - in: query
        name: wait_for
        description: wait for deleted entity to no more be available for search
        required: false
        schema:
          type: boolean
      summary: Delete one Event
      description: Requires capabilities delete-event, developer.
      security:
      - JWT: []
      - oauth2:
        - private-intel
        - private-intel:read
        - private-intel:write
        - casebook
        - casebook:read
        - casebook:write
  /iroh/iroh-event/event/{id}:
    servers:
    - url: https://visibility.amp.cisco.com/
    get:
      x-no-doc: false
      tags:
      - Event
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
            application/x-yaml:
              schema:
                $ref: '#/components/schemas/Event'
            application/edn:
              schema:
                $ref: '#/components/schemas/Event'
            application/transit+json:
              schema:
                $ref: '#/components/schemas/Event'
            application/transit+msgpack:
              schema:
                $ref: '#/components/schemas/Event'
      description: '[required scopes](/iroh/doc/iroh-auth/#scopes): `event:read`


        '
      parameters:
      - in: path
        name: id
        description: ''
        required: true
        schema:
          type: string
      summary: Get an `Event`
      security:
      - iroh: []
      - AuthorizationHeader: []
      - oauth2:
        - telemetry
        - integration
        - private-intel
        - admin
        - cognitive
        - profile
        - inspect
        - asset
        - event
        - feedback
        - sse
        - registry
        - users
        - investigation
        - invite
        - casebook
        - orbital
        - enrich
        - oauth
        - vault
        - response
        - notification
        - global-intel:read
        - webhook
        - ao
  /iroh/iroh-event/event/search:
    servers:
    - url: https://visibility.amp.cisco.com/
    post:
      x-no-doc: false
      tags:
      - Event
      summary: Search for Events
      description: '[required scopes](/iroh/doc/iroh-auth/#scopes): `event:read`


        '
      parameters:
      - in: query
        name: offset
        description: ''
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: limit
        description: ''
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: search_after
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            x-oneOf:
            - type: string
            - type: number
              format: double
            - type: string
      - in: query
        name: sort_by
        description: ''
        required: false
        x-oneOf:
        - type: string
        - type: number
          format: double
        - type: string
      - in: query
        name: sort_order
        description: ''
        required: false
        schema:
          type: string
          enum:
          - desc
          - asc
      - in: query
        name: fields
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEventsResult'
            application/x-yaml:
              schema:
                $ref: '#/components/schemas/SearchEventsResult'
            application/edn:
              schema:
                $ref: '#/components/schemas/SearchEventsResult'
            application/transit+json:
              schema:
                $ref: '#/components/schemas/SearchEventsResult'
            application/transit+msgpack:
              schema:
                $ref: '#/components/schemas/SearchEventsResult'
      requestBody:
        content:
          application/json:
            schema:
              description: Filter on event data
              x-oneOf:
              - $ref: '#/components/schemas/GenericSearch'
              - type: array
                items:
                  type: string
                  enum:
                  - or
                  - not
                  - and
          application/x-yaml:
            schema:
              description: Filter on event data
              x-oneOf:
              - $ref: '#/components/schemas/GenericSearch'
              - type: array
                items:
                  type: string
                  enum:
                  - or
                  - not
                  - and
          application/edn:
            schema:
              description: Filter on event data
              x-oneOf:
              - $ref: '#/components/schemas/GenericSearch'
              - type: array
                items:
                  type: string
                  enum:
                  - or
                  - not
                  - and
          application/transit+json:
            schema:
              description: Filter on event data
              x-oneOf:
              - $ref: '#/components/schemas/GenericSearch'
              - type: array
                items:
                  type: string
                  enum:
                  - or
                  - not
                  - and
          application/transit+msgpack:
            schema:
              description: Filter on event data
              x-oneOf:
              - $ref: '#/components/schemas/GenericSearch'
              - type: array
                items:
                  type: string
                  enum:
                  - or
                  - not
                  - and
        description: Filter on event data
        required: true
      security:
      - iroh: []
      - AuthorizationHeader: []
      - oauth2:
        - telemetry
        - integration
        - private-intel
        - admin
        - cognitive
        - profile
        - inspect
        - asset
        - event
        - feedback
        - sse
        - registry
        - users
        - investigation
        - invite
        - casebook
        - orbital
        - enrich
        - oauth
        - vault
        - response
        - notification
        - global-intel:read
        - webhook
        - ao
  /iroh/iroh-event/event/incident/{incident-id}:
    servers:
    - url: https://visibility.amp.cisco.com/
    get:
      x-no-doc: false
      tags:
      - Event
      summary: Combines events from Private Intel and IROH using the IROH event format
      description: '[required scopes](/iroh/doc/iroh-auth/#scopes): `event:read`


        '
      parameters:
      - in: path
        name: incident-id
        description: ''
        required: true
        schema:
          type: string
      - in: query
        name: offset
        description: ''
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: limit
        description: ''
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: search_after
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            x-oneOf:
            - type: string
            - type: number
              format: double
            - type: string
      - in: query
        name: sort_by
        description: ''
        required: false
        x-oneOf:
        - type: string
        - type: number
          format: double
        - type: string
      - in: query
        name: sort_order
        description: ''
        required: false
        schema:
          type: string
          enum:
          - desc
          - asc
      - in: query
        name: fields
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - in: query
        name: include
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - response_actions
            - incident_changes
            - notes
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
            application/x-yaml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
            application/edn:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
            application/transit+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
            application/transit+msgpack:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
      security:
      - iroh: []
      - AuthorizationHeader: []
      - oauth2:
        - telemetry
        - integration
        - private-intel
        - admin
        - cognitive
        - profile
        - inspect
        - asset
        - event
        - feedback
        - sse
        - registry
        - users
        - investigation
        - invite
        - casebook
        - orbital
        - enrich
        - oauth
        - vault
        - response
        - notification
        - global-intel:read
        - webhook
        - ao
components:
  schemas:
    IncidentScores:
      example:
        asset: 10.0
      description: Used to indicate the severity or impact score of the threat represented by the incident.
      type: object
      additionalProperties:
        example: 10.0
        description: "Field is used to indicate the severity or impact of the threat represented by the incident.\nIt's an open-type dictionary object with score types and numeric value of the score.\n\nFor example, systems can have the following score types:\n\n- `asset` - assesses the potential damage or harm that the threat can cause to the affected asset(s). The scale ranges from 0 to 10, with 10 indicating the highest potential harm. \n\n- `global` - assesses the overall impact or significance of the threat to the organization or wider community. The scale ranges from 0 to 1000, with 1000 indicating the highest impact.\n\n- `ttp` - a measure of the threat actor's proficiency in utilizing TTPs. Typically, ranges from 0-100, with a higher score indicating a greater threat or concern."
        type: number
        format: double
    Response116834EventsFieldsChange:
      type: object
      properties:
        before: {}
        after: {}
      additionalProperties: false
    EventSign:
      type: object
      properties:
        value:
          type: string
        alg:
          type: string
          enum:
          - rsassa-pss+sha512
          - rsassa-pss+sha256
          - eddsa
          - rsassa-pkcs15+sha384
          - ecdsa+sha384
          - ecdsa+sha512
          - rsassa-pkcs15+sha512
          - ecdsa+sha256
          - rsassa-pss+sha384
          - rsassa-pkcs15+sha256
        kid:
          type: string
      additionalProperties: false
      required:
      - value
      - alg
      - kid
    ExternalReference:
      example:
        source_name: string
        description: string
        url: string
        hashes:
        - string
        external_id: string
      description: External references are used to describe pointers to information represented outside of CTIM. For example, a Malware object could use an external reference to indicate an ID for that malware in an external database or a report could use references to represent source material.
      type: object
      properties:
        source_name:
          example: string
          description: The source within which the external-reference is defined (system, registry, organization, etc.)
          type: string
        description:
          example: string
          description: Markdown string with at most 5000 characters.
          type: string
        url:
          example: string
          description: A URL reference to an external resource.
          type: string
        hashes:
          example:
          - string
          description: Specifies a dictionary of hashes for the contents of the url.
          type: array
          items:
            type: string
        external_id:
          example: string
          description: An identifier for the external reference content.
          type: string
      additionalProperties: false
      required:
      - source_name
    GenericSearch:
      type: object
      additionalProperties: {}
    EventDataAdditionalNote:
      type: object
      properties:
        schema_version:
          example: 1.3.30
          description: CTIM schema version for this entity.
          type: string
        revision:
          example: 10
          description: A monotonically increasing revision, incremented each time the object is changed.
          type: integer
          format: int64
        content:
          example: string
          description: Markdown string with at most 5000 characters.
          type: string
        note_class:
          example: keyword
          type: string
        type:
          example: note
          type: string
          enum:
          - note
        created:
          type: string
          format: date-time
        source:
          example: string
          description: Represents the source of the intelligence that led to the creation of the entity.
          type: string
        external_ids:
          example:
          - string
          description: "It is used to store a list of external identifiers that can be linked to the incident, providing a reliable and manageable way to correlate and group related events across multiple data sources. It is especially useful in larger organizations that rely on multiple security information and event management (SIEM) systems to detect security incidents. For instance, it can be used to track events across different network sensors, intrusion detection and prevention systems (IDPS), or log management platforms. \n The field can also be used to facilitate automation and orchestration workflows, where additional information can be shared among incident management systems. It can be used to cross-reference with other external tools such as threat intelligence feeds and vulnerability scanners."
          type: array
          items:
            type: string
        modified:
          type: string
          format: date-time
        external_references:
          example:
          - source_name: string
            description: string
            url: string
            hashes:
            - string
            external_id: string
          description: "Specifies a list of external references which refers to non-CTIM information.\n\nSimilar to `external_ids` field with major differences:\n\n- `external_ids` field is used to store a list of external identifiers that can be used to link entities across different data sources. These identifiers are typically standardized and well-known, such as CVE IDs, US-CERT advisories, or other industry-standard threat intelligence feeds. The `external_ids` field can be used to facilitate automation and orchestration workflows, where additional information can be shared among incident management systems. \n\n- `external_references` field, on the other hand, is used to provide a more general mechanism for linking entities to external sources of information. The `external_references` field can include references to blog posts, articles, external documents, threat intelligence reports, and other sources of information that may not have a standardized format or identifier."
          type: array
          items:
            $ref: '#/components/schemas/EventDataAdditionalNoteExternalReferences'
        author:
          example: string
          type: string
        source_uri:
          example: string
          description: URI of the source of the intelligence that led to the creation of the entity.
          type: string
        language:
          example: string
          description: 'The `language` field is used to specify the primary language of the affected system or the target of an attack. It can be used to provide additional context and information about the entity. The primary purpose of this field is to help analysts filter and prioritize entities based on their knowledge and expertise of different languages.


            For example, if an incident involves an attack on a system in a country where a specific language is predominant, the `language` field can be used to indicate that language, which can help analysts to quickly identify and respond to incidents that may be geographically or culturally relevant. This information can be used to prioritize incidents based on their potential impact. The `language` field can also be used to help with correlation of incidents across different systems and regions, as well as to help with data analysis and reporting.'
          type: string
        id:
          example: string
          description: Globally unique URI identifying this object.
          type: string
        tlp:
          example: green
          description: 'TLP stands for [Traffic Light Protocol](https://www.us-cert.gov/tlp), which indicates precisely how a resource is intended to be shared, replicated, copied, etc.


            It is used to indicate the sensitivity of the information contained within the message. This allows recipients to determine the appropriate handling and dissemination of the information based on their clearance level and need-to-know.


            For example, an entity containing information about a critical vulnerability in a widely-used software might be marked as `red`, indicating that it should only be shared with a small group of highly trusted individuals

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cisco-xdr/refs/heads/main/openapi/cisco-xdr-event-api-openapi.yml