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

# Ingest a single audit event



## OpenAPI

````yaml /openapi/audit.v1.yaml post /v1/events
openapi: 3.1.0
info:
  title: Fact0 Audit API
  version: 1.0.0
  description: >
    Compliance-grade universal fact layer with tamper-evident audit log API.
    Events form a per-tenant SHA-256 hash chain.


    **Authentication:** `Authorization: Bearer f0_live_*` or `alk_live_*` API
    keys (write or read scope).


    **Async ingest (default):** POST ingest endpoints return `202 Accepted` with
    a `receipt_id`.

    Poll `GET /v1/receipts/{id}` until `status` is `committed` or `failed`.

    Force synchronous ingest with header `X-Fact0-Sync: true`  or query
    `?sync=true`.
servers:
  - url: https://api.fact0.io
    description: Fact0 Cloud
security:
  - apiKey: []
tags:
  - name: Ingest
  - name: Query
  - name: Verify
  - name: Export
  - name: Chain
  - name: Stream
  - name: Share
paths:
  /v1/events:
    post:
      tags:
        - Ingest
      summary: Ingest a single audit event
      operationId: logEvent
      parameters:
        - $ref: '#/components/parameters/SyncHeader'
        - $ref: '#/components/parameters/SyncQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditEventInput'
      responses:
        '201':
          description: Event committed (sync mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEvent'
        '202':
          description: Event queued (async default)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncReceipt'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
      security:
        - apiKey: []
components:
  parameters:
    SyncHeader:
      name: X-Fact0-Sync
      in: header
      description: Set to `true` for synchronous ingest
      schema:
        type: string
        enum:
          - 'true'
    SyncQuery:
      name: sync
      in: query
      description: Set to `true` for synchronous ingest
      schema:
        type: string
        enum:
          - 'true'
  schemas:
    AuditEventInput:
      type: object
      required:
        - actor
        - action
        - resource
        - outcome
      properties:
        id:
          type: string
        timestamp:
          type: string
          format: date-time
        actor:
          $ref: '#/components/schemas/Actor'
        action:
          type: string
          description: Dot-notation action name (e.g. document.delete)
        resource:
          $ref: '#/components/schemas/Resource'
        outcome:
          type: string
          enum:
            - success
            - failure
            - error
        metadata:
          type: object
          additionalProperties: true
    AuditEvent:
      allOf:
        - $ref: '#/components/schemas/AuditEventInput'
        - type: object
          properties:
            tenant_id:
              type: string
            prev_hash:
              type: string
            hash:
              type: string
            sequence_number:
              type: integer
              format: int64
            created_at:
              type: string
              format: date-time
    AsyncReceipt:
      allOf:
        - $ref: '#/components/schemas/BatchResult'
        - type: object
          properties:
            receipt_id:
              type: string
            status:
              type: string
              enum:
                - queued
                - committed
                - failed
            error_message:
              type: string
            created_at:
              type: string
              format: date-time
            committed_at:
              type: string
              format: date-time
    Actor:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - human
            - agent
            - system
        email:
          type: string
    Resource:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
    BatchResult:
      type: object
      properties:
        accepted:
          type: integer
        rejected:
          type: integer
        ids:
          type: array
          items:
            type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BatchError'
    ErrorResponse:
      type: object
      properties:
        error:
          oneOf:
            - type: string
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
    BatchError:
      type: object
      properties:
        index:
          type: integer
        code:
          type: string
        message:
          type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Key lacks required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Duplicate event ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: API key prefixed with `alk_live_`. Write scope required for ingest.

````