Ingestion API

Anything that can make an HTTP request can send events to Origamy — no SDK required. This is the same API the Web SDK speaks.

Base URL

Deployment	Base URL
Origamy Cloud	https://events.origamy.io
Self-hosted (BYOD) data plane	your gateway’s host

Authentication

Authenticate with your source’s write key using HTTP Basic auth — the write key is the username, the password is empty (note the trailing colon):

Authorization: Basic base64("YOUR_WRITE_KEY:")

With curl, -u "YOUR_WRITE_KEY:" does this for you.

A writeKey query parameter is also accepted (?writeKey=...) — it exists for navigator.sendBeacon, which cannot set headers. Prefer the header everywhere else.

POST /v1/batch

Deliver up to 500 events in one request.

curl https://events.origamy.io/v1/batch \
  -u "YOUR_WRITE_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      {
        "type": "identify",
        "userId": "user_123",
        "anonymousId": "anon-1",
        "traits": { "email": "ada@example.com" },
        "messageId": "m-001",
        "timestamp": "2026-07-02T12:00:00Z"
      },
      {
        "type": "track",
        "userId": "user_123",
        "anonymousId": "anon-1",
        "event": "Order Completed",
        "properties": { "amount": 99.99, "currency": "USD" },
        "messageId": "m-002",
        "timestamp": "2026-07-02T12:00:01Z"
      }
    ],
    "sentAt": "2026-07-02T12:00:02Z"
  }'

Request body

Field	Required	Description
batch	yes	Array of event objects — see the Event spec.
sentAt	no	ISO-8601 client send time, used to correct client clock skew.

Success response — 200:

{ "success": true }

Invalid events within a batch are skipped and logged, not rejected wholesale; the request only fails outright if every event fails.

Request bodies may be gzip-compressed — set Content-Encoding: gzip.

Single-event endpoints

Each event type also has its own endpoint accepting one event object (same shape as a batch entry, type inferred from the path):

POST /v1/track
POST /v1/identify
POST /v1/page
POST /v1/group
POST /v1/alias

curl https://events.origamy.io/v1/track \
  -u "YOUR_WRITE_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "anonymousId": "anon-1",
    "event": "Signed Up",
    "properties": { "plan": "pro" },
    "timestamp": "2026-07-02T12:00:00Z"
  }'

GET /v1/config

Returns the source’s device-mode destination configuration. Used by the Web SDK to decide which plugins to load; authenticate via the writeKey query parameter:

curl "https://events.origamy.io/v1/config?writeKey=YOUR_WRITE_KEY"

Limits

Limit	Value
Max request body	1 MB
Max events per batch	500
Max single event size	32 KB
Rate limit	per write key; current status in X-RateLimit-* response headers

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and — when you are being throttled — X-RateLimit-Reset and Retry-After.

Response codes

Code	Meaning
200	Accepted.
400	Malformed JSON or the batch failed validation (e.g. more than 500 events).
401	Missing or invalid write key.
413	Request body over 1 MB (or a single event over 32 KB).
429	Rate limit exceeded — back off for Retry-After seconds.
500	Every event in the batch failed to be accepted; retry with backoff.

Error responses are JSON with an explanatory message.

Delivery semantics

Events are published into Origamy’s processing pipeline with the event’s messageId as the deduplication key — retrying a failed request with the same messageIds will not double-count events. Always generate a unique messageId per event and reuse it on retries.