API reference

A REST API over HTTPS with JSON bodies. The same API powers the console, the CLI and every SDK.

Authentication

Event endpoints take your ingest key in a Rivora-Ingest-Key header. It can only send events, so it is safe to ship in apps. Everything else uses an API token sent as a bearer token. Create tokens in Settings → API tokens and scope them to one environment.

Base URLhttps://api.rivora.dev/v1

Errors

Rivora uses conventional HTTP status codes and returns a JSON body with a machine-readable code and a human-readable message.

Status	Code	Meaning
`400`	`invalid_request`	The body is malformed or a required field is missing.
`401`	`unauthorized`	The key or token is missing, revoked or for another environment.
`404`	`not_found`	The resource does not exist in this workspace.
`422`	`schema_violation`	The event does not match its schema. Details list each field.
`429`	`rate_limited`	Too many requests. Retry after the `Retry-After` header.

Rate limits

Event endpoints accept up to 5,000 requests per second per workspace and are never rate limited on Enterprise. Management endpoints allow 100 requests per second per token.

Send an event

POST/v1/events

Send a single event. Events are validated against the schema for their name and acknowledged once stored.

Parameters

eventstringrequired

Event name, for example checkout.completed.

userIdstring

Your identifier for the user, if known. Leave it out for signed-out visitors and send deviceId instead.

propertiesobject

Event properties. Validated against the event's schema.

timestampISO 8601

When the event happened. Defaults to the time Rivora received it.

curl https://api.rivora.dev/v1/events \
  -H "Rivora-Ingest-Key: \
$RIVORA_INGEST_KEY" \
  -H "Content-Type: \
application/json" \
  -d '{
    "event": "checkout.completed",
    "userId": "usr_2481",
    "properties": {
      "orderId": "order_8812",
      "amount": 4900
    }
  }'

rivora.emit("checkout.completed", {
  userId: "usr_2481",
  orderId: "order_8812",
  amount: 4900,
});

{
  "id": "evt_01JB9X4Q2M",
  "status": "accepted",
  "schemaVersion": 22
}

Send a batch

POST/v1/events/batch

Send up to 1,000 events or 8 MB in one request. Each event is validated on its own; one bad event does not reject the batch.

Parameters

batcharrayrequired

Events in the same shape as /v1/events.

contextobject

Shared context merged into every event, such as app version.

curl \
  https://api.rivora.dev\
/v1/events/batch \
  -H "Rivora-Ingest-Key: \
$RIVORA_INGEST_KEY" \
  -d '{
    "batch": [
      {
        "event": "invoice.paid",
        "userId": "usr_2481"
      }
    ]
  }'

rivora.batch([
  {
    event: "invoice.paid",
    userId: "usr_2481",
  },
  {
    event: "trial.started",
    userId: "usr_9917",
  },
]);

{
  "accepted": 2,
  "rejected": []
}

Retrieve an event

GET/v1/events/{id}

Fetch one stored event with its delivery attempts across every destination.

Parameters

idstringrequired

The event ID returned when it was tracked.

curl \
  https://api.rivora.dev/v1/events/\
evt_01JB9X4Q2M \
  -H "Authorization: Bearer \
$RIVORA_API_TOKEN"

const event =
  await rivora.events.retrieve(
    "evt_01JB9X4Q2M"
  );

{
  "id": "evt_01JB9X4Q2M",
  "event": "checkout.completed",
  "deliveries": [
    {
      "destination": "warehouse",
      "status": "delivered",
      "ms": 12
    }
  ]
}

List pipelines

GET/v1/pipelines

List pipelines in the current environment, with their sources, destinations and health.

Parameters

environmentstring

production, staging or preview.

limitinteger

Between 1 and 100. Defaults to 20.

cursorstring

Cursor from the previous page.

curl \
  https://api.rivora.dev/v1/pipelines\
?limit=20 \
  -H "Authorization: Bearer \
$RIVORA_API_TOKEN"

const pages = rivora.pipelines.list();

for await (const p of pages) {
  console.log(p.name, p.health);
}

{
  "data": [
    {
      "id": "pl_checkout",
      "health": "healthy"
    }
  ],
  "nextCursor": null
}

Start a rewind

POST/v1/rewinds

Rewind stored events into one or more destinations. Set dryRun to preview the result first.

Parameters

fromISO 8601required

Start of the time range.

toISO 8601required

End of the time range.

destinationsstring[]required

Destination IDs to rewind into.

filterstring

Optional filter, for example event = "invoice.paid".

dryRunboolean

Count matching events without sending them.

curl \
  https://api.rivora.dev/v1/rewinds \
  -H "Authorization: Bearer \
$RIVORA_API_TOKEN" \
  -d '{
    "from": "2026-10-01",
    "to": "2026-10-07",
    "destinations": ["warehouse"]
  }'

const rewind =
  await rivora.rewinds.create({
    from: "2026-10-01",
    to: "2026-10-07",
    destinations: ["warehouse"],
    dryRun: true,
  });

{
  "id": "rpl_7Q2",
  "status": "dry_run",
  "matched": 184220
}

Cancel a rewind

DELETE/v1/rewinds/{id}

Stop a running rewind. Events already delivered stay delivered.

Parameters

idstringrequired

The rewind ID.

curl -X DELETE \
  https://api.rivora.dev/v1/rewinds/\
rpl_7Q2 \
  -H "Authorization: Bearer \
$RIVORA_API_TOKEN"

await rivora.rewinds.cancel(
  "rpl_7Q2"
);

{
  "id": "rpl_7Q2",
  "status": "cancelled"
}

List schemas

GET/v1/schemas

List event schemas and their current versions.

Parameters

namestring

Filter by event name prefix, for example checkout..

curl \
  https://api.rivora.dev/v1/schemas\
?name=checkout. \
  -H "Authorization: Bearer \
$RIVORA_API_TOKEN"

const schemas =
  await rivora.schemas.list({
    name: "checkout.",
  });

{
  "data": [
    {
      "name": "checkout.completed",
      "version": 22
    }
  ]
}