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

# Ingest events

> Ingests a batch of events. Each event is identified by its `idempotencyKey`: if no event exists for the key, version 1 is created; re-sending the key with unchanged `properties` (including `properties.value`) is a no-op; re-sending with changed `properties` records a new version that supersedes the previous one. Frozen fields (`eventName`, `customerExternalId`, `occurredAt`) must match the existing event or the request is rejected with `ImmutableFieldChange`. Validation and frozen-field checks apply across the whole batch — if any event is rejected, none are recorded.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/events/ingest
openapi: 3.1.0
info:
  title: API Reference
  version: '1.0'
  description: Aira API Reference
  x-logo:
    url: https://static.useaira.com/images/airalogo.svg
    backgroundColor: '#FFFFFF'
    altText: Aira Logo
servers:
  - url: https://api.useaira.com
    description: API base URL
security:
  - ApiKey: []
paths:
  /v1/events/ingest:
    post:
      tags:
        - Events
      summary: Ingest events
      description: >-
        Ingests a batch of events. Each event is identified by its
        `idempotencyKey`: if no event exists for the key, version 1 is created;
        re-sending the key with unchanged `properties` (including
        `properties.value`) is a no-op; re-sending with changed `properties`
        records a new version that supersedes the previous one. Frozen fields
        (`eventName`, `customerExternalId`, `occurredAt`) must match the
        existing event or the request is rejected with `ImmutableFieldChange`.
        Validation and frozen-field checks apply across the whole batch — if any
        event is rejected, none are recorded.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  description: >-
                    An array of events to be ingested. Each event represents an
                    usage of a resource from a customer at a specific point in
                    time.
                  type: array
                  items:
                    type: object
                    description: Schema defining an event.
                    properties:
                      idempotencyKey:
                        type: string
                        pattern: ^[a-zA-Z0-9_-]+$
                        description: Unique key to ensure idempotency of the event.
                        example: 123e4567-e89b-12d3-a456-426614174000
                      eventName:
                        type: string
                        pattern: ^[a-zA-Z0-9_-]+$
                        description: Identifier of the event.
                        example: api_request
                      customerExternalId:
                        type: string
                        pattern: ^[a-zA-Z0-9_-]+$
                        description: >-
                          External identifier of the customer involved in the
                          event.
                        example: cust_1234567890abcdef
                      properties:
                        type: object
                        description: >-
                          A dictionary of additional properties associated with
                          the event.
                        propertyNames:
                          pattern: ^[a-zA-Z](?:[a-zA-Z0-9]*|(?:_[a-zA-Z0-9]+))*$
                        required:
                          - value
                        properties:
                          value:
                            type: number
                            minimum: 0
                            multipleOf: 1
                            description: Numeric value associated with the event.
                            example: 3600
                        additionalProperties:
                          if:
                            type: number
                          then:
                            type: number
                            minimum: 0
                            multipleOf: 1
                          else:
                            anyOf:
                              - type: boolean
                              - type: string
                        example:
                          value: 3600
                          endpoint: /api/v1/users
                          method: GET
                          status_code: 200
                      occurredAt:
                        type: string
                        format: date-time
                        description: >-
                          ISO 8601 timestamp in UTC indicating when the event
                          occurred.
                        example: '2024-01-01T12:00:00Z'
                    required:
                      - idempotencyKey
                      - eventName
                      - customerExternalId
                      - properties
                      - occurredAt
                    additionalProperties: false
                  minItems: 1
                  maxItems: 10000
              required:
                - events
              additionalProperties: false
        required: true
        description: An object containing an array of events to be ingested.
      responses:
        '204':
          description: The request was successfully processed.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
        '400':
          description: >-
            Invalid request due to incorrect data or all events could not be
            processed successfully, so none have been recorded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable error message explaining why the ingestion
                      failed.
                  code:
                    type: string
                    description: Error code identifying the type of failure.
                  details:
                    type: array
                    description: List of failed events and their specific errors.
                    items:
                      type: object
                      properties:
                        idempotencyKey:
                          type: string
                          description: The idempotency key of the failed event.
                        errors:
                          type: array
                          items:
                            type: object
                            properties:
                              code:
                                type: string
                                enum:
                                  - future_occurred_at
                                  - duplicated_idempotency_key
                                  - failed_on_previous_event_creation
                                  - immutable_field_change
                              message:
                                type: string
                            required:
                              - code
                              - message
                      additionalProperties: true
                required:
                  - message
                  - code
                additionalProperties: false
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      description: API Key Authentication.
      name: X-API-KEY
      in: header

````