> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://usehelloai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://usehelloai.ferndocs.com/_mcp/server.

# Ingesting Events

When an AI agent completes an action — booking an appointment, collecting a payment, updating a record — call `POST /events` to record it. Hello AI validates the event against your active policy rule packs and returns a signed receipt.

## Single event

#### Python

```python
import datetime
from usehelloai import HelloAI, SystemOfRecordRef

client = HelloAI(api_key="YOUR_API_KEY")

response = client.ingestion.ingest_event(
    agent_id="agent_01HXYZ",
    session_id="sess_call_38291",
    event_type="appointment.booked",
    occurred_at=datetime.datetime.now(datetime.timezone.utc),
    payload={
        "patient_id": "pt_9912",
        "procedure_code": "D0120",
        "appointment_datetime": "2025-06-15T10:00:00-05:00",
    },
    system_of_record=SystemOfRecordRef(
        type="ehr",
        adapter="athena",
        write_confirmed=True,
        record_reference="appt_athena_88821",
    ),
)

print(response.receipt_id)
```

#### TypeScript

```typescript
const response = await client.ingestion.ingestEvent({
  agent_id: "agent_01HXYZ",
  session_id: "sess_call_38291",
  event_type: "appointment.booked",
  occurred_at: new Date().toISOString(),
  payload: {
    patient_id: "pt_9912",
    procedure_code: "D0120",
  },
  system_of_record: {
    type: "ehr",
    adapter: "athena",
    write_confirmed: true,
    record_reference: "appt_athena_88821",
  },
});

console.log(response.receipt_id);
```

## Batch ingestion

For high-throughput scenarios, use `POST /events/batch` to submit up to 100 events in a single request.

```python
response = client.ingestion.ingest_batch(events=[...])
for result in response.results:
    print(result.receipt_id, result.status)
```

## Policy evaluation

Every event is evaluated against your active rule packs synchronously. The response includes a `policy_evaluation_state` — `pending` (async) or `complete` (inline) — and a compliance verdict on the resulting receipt.