> ## 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. # Overwrite event > Records a new version of the event identified by `idempotencyKey`, fully replacing `properties` (including `properties.value`). Frozen fields (`eventName`, `customerExternalId`, `occurredAt`) must match the existing event or the request is rejected with `ImmutableFieldChange`. If no event exists for the key, version 1 is created. Returns the recorded event. ## OpenAPI ````yaml /api-reference/openapi.yaml put /v1/events/{idempotencyKey} 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/{idempotencyKey}: put: tags: - Events summary: Overwrite event description: >- Records a new version of the event identified by `idempotencyKey`, fully replacing `properties` (including `properties.value`). Frozen fields (`eventName`, `customerExternalId`, `occurredAt`) must match the existing event or the request is rejected with `ImmutableFieldChange`. If no event exists for the key, version 1 is created. Returns the recorded event. parameters: - schema: type: string pattern: ^[a-zA-Z0-9_-]+$ example: 123e4567-e89b-12d3-a456-426614174000 in: path name: idempotencyKey required: true description: Unique key to ensure idempotency of the event. requestBody: content: application/json: schema: type: object properties: 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: - eventName - customerExternalId - properties - occurredAt additionalProperties: false required: true description: >- Full replacement payload for the event identified by `idempotencyKey`. Frozen fields (`eventName`, `customerExternalId`, `occurredAt`) must match the existing event; `properties` (including `properties.value`) is overwritten. responses: '200': description: Schema defining an event. content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the event. 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' createdAt: type: string format: date-time description: >- ISO 8601 timestamp in UTC indicating when the event was created. archivedAt: type: - 'null' - string format: date-time description: >- ISO 8601 timestamp in UTC indicating when the event was archived, or null if active. version: type: integer description: >- Version number. v1 is the original; subsequent versions are edits or archives. required: - id - idempotencyKey - eventName - customerExternalId - properties - occurredAt - createdAt - archivedAt - version 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 ````