Events API

Events are the spark for conversions, Insights goals, and event-triggered Journeys. They are a core API — you do not create an inbound webhook first.

Endpoint: ingestEvents — POST /v1/projects/{projectId}/event_ingestion Scope: write Batch: up to 500 events per call

Payload

{
  "events": [{
    "externalId": "evt_123",
    "contactExternalId": "user_42",
    "name": "order_placed",
    "occurredAt": "2026-09-05T10:00:00Z",
    "properties": {
      "order_id": "ord_1842",
      "status": "paid",
      "total": "42.00",
      "items": [{ "name": "Pro plan", "amount": "$29" }]
    }
  }]
}

Unknown event names create a proposed definition. Journeys that listen for that exact name still fire.

curl -X POST "$AUDRYO_API_BASE/projects/$PROJECT_ID/event_ingestion" \
  -H "Authorization: Bearer $AUDRYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"externalId":"evt_123","contactExternalId":"user_42","name":"order_placed","occurredAt":"2026-09-05T10:00:00Z","properties":{"order_id":"ord_1842"}}]}'

After ingest

Audryo records the event, evaluates matching active Journeys, and may enroll the contact (reentry policy applying). Goal events also feed Insights incrementality.

CLI: audryo events ingest events.json (raw array or { "events": [] }).

Related

• Contacts & events
• Triggers and reentry
• Personalization
• Inbound webhooks — only when you cannot use this API

Event catalog as code

Keep a complete JSON catalog in the product repository. Deploy it with POST /v1/projects/:projectId/event_catalog using a workspace API token with the write scope. GET on the same endpoint requires read and returns the current catalog, or null before the first sync.

{
  "version": 1,
  "source": "JunoApi",
  "events": [
    {
      "name": "book_draft_idle",
      "description": "A book draft has been inactive.",
      "purpose": "Help the author finish their book.",
      "properties": {
        "book_id": {
          "type": "string",
          "example": "book-123",
          "required": true
        },
        "child_name": {
          "type": "string",
          "example": "Alex"
        }
      }
    }
  ]
}

Use synthetic examples. Supported types are string, integer, number, boolean, datetime (ISO 8601), object and array. Property names are flat identifiers matching the keys of the ingestion event payload; nested property paths are not yet supported. Examples are optional and must match their type when non-null.

Run the deploy helper shipped with Audryo:

AUDRYO_API_URL=https://api.audryo.com AUDRYO_PROJECT_ID=your-project-id AUDRYO_API_TOKEN=your-write-token node scripts/sync-event-catalog.mjs event-catalog.json

The URL includes no /v1 suffix. Increment the positive integer version whenever the contract changes. An identical retry is safe. Changed contents at the same version or a lower version return 409. Validation failures return 422 with details and do not partially apply. Versions are serialized under a project lock and kept as immutable snapshots. Each sync replaces the complete declared catalog; omitted events remain in the observed event definitions so existing journeys are not deleted. Catalog events are automatically confirmed for journey triggers.

Observed properties remain separate and never overwrite the declared contract. Ingestion is not rejected by the catalog: this initial implementation validates authored mail, not production event traffic. required documents the producer contract; it does not guarantee a value on any particular event.

For emails owned by a journey whose entries all use declared events, saving checks data.* in subject, preheader, body, destinations, visibility conditions and repeat sources against every triggering event. A typo such as data.book_idd fails with the event name and catalog version. Legacy projects, standalone transactional emails, mixed entry types and undeclared triggers remain compatible. Scoped editor context (message_context?messageId=...) suggests properties for the journey’s declared triggers; generic context shows the catalog’s properties. The preview retains the saved message’s journey context and performs the same validation.