> ## Documentation Index
> Fetch the complete documentation index at: https://devlookout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest normalized events

> For the complete documentation index, see https://devlookout.com/llms.txt. Accepts a JSON event array or an object containing an events array.



## OpenAPI

````yaml /openapi.yaml post /api/v1/events
openapi: 3.1.0
info:
  title: Lookout HTTP API
  version: 1.0.0
  description: >-
    Versioned interface for querying Lookout security state, ingesting evidence,
    managing Alerts, and promoting Incidents. The deployed Lookout instance is
    authoritative and raw evidence remains local unless export is explicitly
    enabled.
servers:
  - url: https://lookout.example.com
    description: Replace with the private URL of your Lookout deployment
security:
  - bearerAuth: []
tags:
  - name: System
  - name: Security graph
  - name: Rules
  - name: Events
  - name: Collectors
  - name: Alerts
  - name: Incidents
paths:
  /api/v1/events:
    post:
      tags:
        - Events
      summary: Ingest normalized events
      description: >-
        For the complete documentation index, see
        https://devlookout.com/llms.txt. Accepts a JSON event array or an object
        containing an events array.
      operationId: ingestEvents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/NormalizedEvent'
                - type: object
                  required:
                    - events
                  properties:
                    events:
                      type: array
                      items:
                        $ref: '#/components/schemas/NormalizedEvent'
      responses:
        '202':
          description: Events accepted and evaluated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestionResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/TooLarge'
components:
  schemas:
    NormalizedEvent:
      type: object
      required:
        - schemaVersion
        - id
        - category
        - class
        - activity
        - outcome
        - time
        - ingestedAt
        - source
        - entityKeys
        - attributes
      properties:
        schemaVersion:
          type: integer
          const: 1
        id:
          type: string
        category:
          $ref: '#/components/schemas/EventCategory'
        class:
          type: string
        activity:
          type: string
        outcome:
          type: string
          enum:
            - success
            - failure
            - unknown
        time:
          type: string
          format: date-time
        ingestedAt:
          type: string
          format: date-time
        severity:
          type: number
          minimum: 0
          maximum: 10
        source:
          $ref: '#/components/schemas/EventSource'
        entityKeys:
          type: array
          maxItems: 256
          items:
            type: string
        actor:
          type:
            - object
            - 'null'
          additionalProperties: true
        sourceEndpoint:
          type:
            - object
            - 'null'
          additionalProperties: true
        destinationEndpoint:
          type:
            - object
            - 'null'
          additionalProperties: true
        service:
          type:
            - object
            - 'null'
          additionalProperties: true
        correlation:
          type: object
          additionalProperties: true
        attributes:
          type: object
          additionalProperties: true
        rawReference:
          type:
            - string
            - object
            - 'null'
    IngestionResult:
      type: object
      properties:
        accepted:
          type: array
          items:
            $ref: '#/components/schemas/NormalizedEvent'
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
        incidents:
          type: array
          items:
            $ref: '#/components/schemas/Incident'
    EventCategory:
      type: string
      enum:
        - identity
        - network
        - system
        - application
        - discovery
        - configuration
        - data
        - health
        - finding
    EventSource:
      type: object
      additionalProperties: false
      required:
        - adapter
        - instance
        - recordId
      properties:
        adapter:
          type: string
        instance:
          type: string
        recordId:
          type: string
    Alert:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - open
            - in_review
            - dismissed
      additionalProperties: true
    Incident:
      type: object
      required:
        - id
      properties:
        id:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        issues:
          type: array
          items:
            type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The principal lacks the required permission
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooLarge:
      description: Request body exceeds the operation limit
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: A 256-bit token generated by the Lookout CLI.

````