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

# Submit a signed collector envelope

> For the complete documentation index, see https://devlookout.com/llms.txt. Accepts an Ed25519-signed, registered collector envelope. Exact retries of the most recently accepted envelope are idempotent.



## OpenAPI

````yaml /openapi.yaml post /api/v1/collector/submissions
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/collector/submissions:
    post:
      tags:
        - Collectors
      summary: Submit a signed collector envelope
      description: >-
        For the complete documentation index, see
        https://devlookout.com/llms.txt. Accepts an Ed25519-signed, registered
        collector envelope. Exact retries of the most recently accepted envelope
        are idempotent.
      operationId: submitCollectorEnvelope
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectorEnvelope'
      responses:
        '202':
          description: Collector payload accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectorSubmissionResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/TooLarge'
components:
  schemas:
    CollectorEnvelope:
      type: object
      additionalProperties: false
      required:
        - algorithm
        - payload
        - signature
      properties:
        algorithm:
          type: string
          const: Ed25519
        payload:
          type: object
          additionalProperties: false
          required:
            - schemaVersion
            - collectorId
            - sequence
            - collectedAt
            - facts
            - events
          properties:
            schemaVersion:
              type: integer
              const: 1
            collectorId:
              type: string
            sequence:
              type: integer
              minimum: 1
            collectedAt:
              type: string
              format: date-time
            facts:
              type: array
              maxItems: 5000
              items:
                $ref: '#/components/schemas/GenericObject'
            events:
              type: array
              maxItems: 5000
              items:
                $ref: '#/components/schemas/NormalizedEvent'
        signature:
          type: string
          format: byte
    CollectorSubmissionResult:
      type: object
      required:
        - collectorId
        - sequence
      properties:
        collectorId:
          type: string
        sequence:
          type: integer
        graph:
          type: object
          properties:
            entities:
              type: integer
            relationships:
              type: integer
        acceptedEvents:
          type: integer
    GenericObject:
      type: object
      additionalProperties: true
    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'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        issues:
          type: array
          items:
            type: string
    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
  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.

````