API guide

Before you start

The Rellova API lets your own systems list your automations, start them with data, and check how each run went. It is part of the Business and Scale plans (see pricing). Webhooks and HTTP request steps work on every plan.

• Make a key: a workspace owner or admin, with two-factor sign-in on, opens Workspace → API keys and makes one. Copy it straight away: it’s shown once.
• Pick the least access: Read keys list automations and runs. Read and run keys can also start automations.
• One key per system, named after it, so you can revoke one without breaking the others.

Base address: https://rellova.vercel.app/api/v1. Every request and response is JSON over HTTPS.

Authentication

Send the key in the Authorization header on every request. The key decides the workspace, so it never appears in the address.

curl https://rellova.vercel.app/api/v1/automations \
  -H "Authorization: Bearer $RELLOVA_API_KEY"

• Keys look like rlv_ followed by 43 letters, numbers, - and _.
• A key in the address (for example ?api_key=…) is refused with 400, because addresses end up in logs. If that happens, revoke the key and make a new one.
• A wrong, revoked or expired key all get the same 401.
• If the workspace moves to a plan without the API, requests get 403 until it moves back. Keys aren’t deleted.

List automations

GET /api/v1/automations lists the automations you can start: manual, scheduled, webhook and polling ones. Form automations run when their form is submitted, so they aren’t listed.

curl https://rellova.vercel.app/api/v1/automations -H "Authorization: Bearer $RELLOVA_API_KEY"

{
  "data": [
    {
      "id": "6f1c0d6e-1b7a-4c1e-9b8e-2f4d7a9c3e10",
      "name": "New order: check stock and invoice",
      "trigger": "webhook",
      "status": "active",
      "publishedVersion": 3,
      "nextRunAt": null,
      "lastRun": { "status": "succeeded", "startedAt": "2026-11-12T03:15:09.000Z" }
    }
  ]
}

Start an automation

POST /api/v1/automations/{id}/runs starts a run of the published version. Needs a Read and run key. The automation must be published and turned on.

curl -X POST https://rellova.vercel.app/api/v1/automations/6f1c0d6e-1b7a-4c1e-9b8e-2f4d7a9c3e10/runs \
  -H "Authorization: Bearer $RELLOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1001" \
  -d '{"order_id": "A-1001", "customer_email": "sam@example.com", "total": "149.90"}'

The body is a JSON object of up to 64 KB. Its top-level fields become values the automation uses as {{order_id}}, {{total}} and so on, exactly as with a webhook. Up to 50 fields. A name like orderId or Customer Email is tidied to {{order_id}} and {{customer_email}}, and a field inside an object or list is reached with dots: {{customer.email}}, {{items.0.sku}}.

HTTP/1.1 202 Accepted
Location: /api/v1/runs/0b9a7c52-3d1e-4f6a-8c2b-5e7d9f1a3c64

{
  "data": {
    "id": "0b9a7c52-3d1e-4f6a-8c2b-5e7d9f1a3c64",
    "automationId": "6f1c0d6e-1b7a-4c1e-9b8e-2f4d7a9c3e10",
    "status": "queued"
  },
  "replayed": false
}

Check a run

GET /api/v1/runs/{id} returns a run’s status and each step’s result. GET /api/v1/automations/{id}/runs?limit=20 lists recent runs, newest first (up to 100).

{
  "data": {
    "id": "0b9a7c52-3d1e-4f6a-8c2b-5e7d9f1a3c64",
    "automationId": "6f1c0d6e-1b7a-4c1e-9b8e-2f4d7a9c3e10",
    "status": "succeeded",
    "trigger": "webhook",
    "version": 3,
    "attempts": 1,
    "error": null,
    "createdAt": "2026-11-12T03:15:09.000Z",
    "finishedAt": "2026-11-12T03:15:11.000Z",
    "steps": [
      { "id": "stock", "type": "http.request", "status": "succeeded", "error": null,
        "output": { "delivered": true, "status": 200, "reply": { "in_stock": true } } },
      { "id": "gst", "type": "core.calculate", "status": "succeeded", "error": null,
        "output": { "value": "14.99", "a": "149.90", "b": "10" } }
    ]
  }
}

Runs usually finish within seconds. Check every few seconds, then less often.

Errors

Errors use application/problem+json with a plain-English detail. Every response has an X-Request-Id; include it if you contact support.

{
  "type": "about:blank",
  "title": "Read-only key",
  "status": 403,
  "detail": "This key can only read. Make a \"Read and run\" key to start automations.",
  "requestId": "3e0b5f8c-6d2a-4b71-a9c4-1f7e2d8b5a90"
}

Limits

• 120 requests a minute per key, and 300 a minute per IP address.
• After 20 requests with a wrong key in a minute, that IP address is refused for the rest of the minute.
• Runs started through the API count towards your plan’s monthly runs.
• Up to 10 working keys per workspace.

Keeping keys safe

• Keep keys on your server, in its secret settings or a secrets manager. Never put a key in a website, mobile app, code repository, spreadsheet or email.
• Use a Read key unless the system needs to start automations, and choose an expiry. Make the replacement before the old key expires.
• The API keys page shows when each key was last used. Revoke keys nothing uses any more.
• If a key may have leaked, revoke it: it stops working at once. Making and revoking keys, and every run started through the API, is in the workspace’s audit log.
• Rellova stores only a fingerprint (SHA-256 hash) of each key, so nobody, including Rellova staff, can read a key back.

Webhooks or the API?

Both start automations with your data. Use whichever suits the system sending it:

• Webhook (every plan): each webhook automation has its own secret address. Good for tools that can only “POST to a URL”, like form tools, Zapier, Make or n8n. See Triggers.
• API (Business and Scale): one key for many automations, safe retries with Idempotency-Key, and run results you can read back.

Rellova calling your API

An automation’s HTTP request step calls your API, on every plan. Give it a name under “Save the reply as” (say stock) and later steps can use the reply’s fields: {{stock.in_stock}}, {{stock.items.0.sku}}. A Calculate step does sums, percentages and dates on those values, and If / else can branch on them.

Rellova calls public https addresses only, with a 10-second timeout and no redirects, and sends an Idempotency-Key header that stays the same if the call is retried. Replies are read up to 16 KB.

Checking it’s really Rellova: turn on “Sign each request” on a custom API connection and Rellova adds an X-Rellova-Signature header: t=<unix seconds>,s=<hex>, where s is the HMAC-SHA256 of <t>.<raw body> using the connection’s signing key. Check it against the raw body, before parsing, and refuse old timestamps:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function fromRellova(header: string, rawBody: string, signingKey: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', signingKey).update(`${t}.${rawBody}`).digest('hex');
  const given = String(parts.s ?? '');
  return given.length === expected.length &&
    timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}