Sign in
Cloud Events

Ingest a cloud event

Stores one normalized event idempotently on (user, source, dedupeKey) and enqueues async routing to matching API-target background tasks. Returns 202 for a fresh event and 200 with deduped=true for a replay.

post/v1/events

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /v1/events
  • Auth: HTTP bearer

Request body

dedupeKeystring required

Required idempotency anchor, unique per (user, source).

eventTypestring nullable

Provider-specific event type.

occurredAtstring nullable

RFC3339 provider event time.

payloadobject

Full normalized provider object. Sealed at rest; returned only by the event detail endpoint.

source'gmail' | 'google_calendar' | 'google_drive' | 'slack' | 'webhook' | 'mcp' | 'github' | 'linear' | 'stripe' | 'internal' required

Event source.

sourceAccountIdstring nullable

Connected-account key the event belongs to.

sourceEventIdstring nullable

Provider-side event id.

subjectstring nullable

Short title used in UI and routing prompts.

textstring nullable

Human-readable gist used in routing prompts.

Example request

{
  "dedupeKey": "gmail:msg:msg_123",
  "eventType": "email.received",
  "occurredAt": "2026-06-06T14:00:00Z",
  "source": "internal",
  "sourceAccountId": "acct_google_primary",
  "sourceEventId": "evt_123",
  "subject": "Invoice #4821 dispute",
  "text": "Acme disputed invoice #4821 for $18,000."
}

Response

Duplicate dedupeKey: existing event returned, routing not re-run.

dedupedboolean required

Whether this post matched an existing (user, source, dedupeKey) event.

eventIdstring required

Cloud event id.

matchedTaskCountinteger

Tasks the router matched (populated once routed).

routingStatus'pending' | 'routed' | 'skipped' | 'failed' required

Routing status at response time.

Example response

{
  "eventId": "0c0afab1-7f6f-4f0b-9d8e-1e58e8b0f111",
  "routingStatus": "pending"
}

Changes

No operation changes recorded.