API documentation

Start in 5 minutes

1. Create a token in Settings › Security › API tokens. Give it a name and choose its scopes (for example rows:read and rows:write). The token is shown only once: copy it.

2. Check that it works.

export RANGEE_TOKEN="pat…"

curl https://api.rangee.io/v1/me \
  -H "Authorization: Bearer $RANGEE_TOKEN"

The response gives your identity, the token's name, its scopes, its perimeter and the month's quota.

3. Find your tables. The response of GET /v1/bases/app… lists the base's tables, with their IDs.

curl https://api.rangee.io/v1/bases \
  -H "Authorization: Bearer $RANGEE_TOKEN"

curl https://api.rangee.io/v1/bases/app… \
  -H "Authorization: Bearer $RANGEE_TOKEN"

4. Read your rows, keyed by field name to start with.

curl "https://api.rangee.io/v1/tables/tbl…/rows?limit=10&fieldKey=name" \
  -H "Authorization: Bearer $RANGEE_TOKEN"

5. Create a row.

curl https://api.rangee.io/v1/tables/tbl…/rows \
  -H "Authorization: Bearer $RANGEE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2e7a-creation-atelier-martin" \
  -d '{
    "rows": [
      { "values": { "Nom": "Atelier Martin", "Statut": "Signé", "Montant": 1250 } }
    ]
  }'

In JavaScript:

const res = await fetch("https://api.rangee.io/v1/tables/tbl…/rows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RANGEE_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    rows: [{ values: { Nom: "Atelier Martin", Statut: "Signé", Montant: 1250 } }],
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code} : ${body.error.message}`);

In Python:

import os, uuid, requests

res = requests.post(
    "https://api.rangee.io/v1/tables/tbl…/rows",
    headers={
        "Authorization": f"Bearer {os.environ['RANGEE_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"rows": [{"values": {"Nom": "Atelier Martin", "Statut": "Signé", "Montant": 1250}}]},
)
res.raise_for_status()

Access and tokens

Every call carries a personal token in the header:

Authorization: Bearer pat….…

A token has a name, scopes, a perimeter and, if you wish, an expiry date.

It inherits its creator's role in each base. The token of a read-only person never writes, even with the rows:write scope.

It is cut off immediately if you revoke it, or if its creator is removed from the workspace or deactivated.

Scopes

Perimeter

A token covers either all the workspace bases its creator can access, or a chosen list of bases. A token never crosses two workspaces.

A resource outside the token's perimeter answers 404, exactly like a resource that does not exist.

Identity

GET /v1/me

Returns the person, the token's name, its scopes, its perimeter and the month's call quota.

Vocabulary and IDs

IDs are opaque. Do not build them and do not parse them: only the full ID has a meaning.

Conventions

• Format. JSON in UTF-8. Dates and times in ISO 8601 UTC (2026-11-03T09:30:00.000Z), dates without time as YYYY-MM-DD.
• Resource or list. A single resource is returned as is. A list has the shape { "data": [...], "nextCursor": "…" | null }.
• Pagination. By opaque cursor: limit (1 to 1,000, 100 by default) and cursor. A cursor stays valid for 24 hours. When nextCursor is null, you have read everything.
• Batches. A write carries 1 to 100 rows. A batch is atomic: everything goes through, or nothing.
• Referring to things. A table, a field or a view is referred to by its ID. Field names are only accepted as keys of values, when writing.
• Read keys. Values are keyed by field ID. Add fieldKey=name to any row read to receive them keyed by name.
• Replay safely. Any POST, PATCH, PUT or DELETE request accepts an Idempotency-Key header (1 to 255 characters). The same call replayed within 24 hours returns the same response without writing anything again. The same key with a different body answers 409 IDEMPOTENCY_CONFLICT.
• Support. Every response carries a Request-Id header. Quote it to support: it is enough to find the call.

Paginate

async function* allRows(tableId) {
  let cursor = null;
  do {
    const url = new URL(`https://api.rangee.io/v1/tables/${tableId}/rows`);
    url.searchParams.set("limit", "1000");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.RANGEE_TOKEN}` } });
    const page = await res.json();
    yield* page.data;
    cursor = page.nextCursor;
  } while (cursor);
}

Rows

{
  "id": "row01JC9…",
  "createdAt": "2026-10-12T08:14:03.000Z",
  "updatedAt": "2026-11-02T17:40:11.000Z",
  "values": {
    "fld01Nom…": "Atelier Martin",
    "fld01Statut…": { "id": "sel…", "name": "Signé" },
    "fld01Montant…": 1250
  }
}

Empty values. An empty value does not appear in values. To empty a value, write null.

Writing rules

PATCH or PUT. PATCH only touches the fields sent. PUT replaces the row: fields missing from the body are emptied.

Computed fields. They refuse writes (422 READ_ONLY_FIELD): formula, lookup, rollup, count, autonumber, created and modified dates and authors, button.

Conversion with "coerce": true. Added to the body, the option converts text into numbers, dates and checkboxes, and creates unknown select options. Without it, a value of the wrong type answers 422 INVALID_VALUE.

{ "coerce": true, "rows": [{ "values": { "fld01Montant…": "1 250,50", "fld01Signé…": "oui" } }] }

Upsert.

• matchOn lists 1 to 3 fields, of type text, email, number, autonumber, URL or phone.
• Each row sent that matches exactly one existing row updates it. If it finds none, it is created. If it finds several, the call answers 409 UPSERT_AMBIGUOUS.
• The response tells created rows (created) from updated rows (updated).

curl https://api.rangee.io/v1/tables/tbl…/rows/upsert \
  -H "Authorization: Bearer $RANGEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "matchOn": ["fld01Email…"],
    "rows": [
      { "values": { "fld01Email…": "camille@atelier-martin.fr", "fld01Nom…": "Camille Durand" } }
    ]
  }'

Deletion. A deleted row goes to the base's trash for 30 days. It can be restored from the app.

Plan limit. A create beyond the number of rows your plan allows answers 422 ROW_LIMIT, with the number of rows left.

Search rows

POST /v1/tables/{tableId}/rows/query

The body takes the shape of the app's view filters:

filter, search, viewId and formula combine with “and”.

{
  "viewId": "viw…",
  "filter": {
    "and": [
      { "field": "fld01Statut…", "operator": "isAnyOf", "value": ["En cours", "À valider"] },
      { "or": [
        { "field": "fld01Montant…", "operator": ">=", "value": 10000 },
        { "field": "fld01Prioritaire…", "operator": "is", "value": true }
      ] }
    ]
  },
  "sort": [{ "field": "fld01Echeance…", "direction": "asc" }],
  "limit": 50
}

Operators: isEmpty, isNotEmpty, is, isNot, contains, doesNotContain, isAnyOf, isNoneOf, hasAnyOf, hasAllOf, linksTo, =, !=, <, <=, >, >=.

Each field type accepts only some of these operators. An operator that is not accepted answers 422 INVALID_FILTER, naming the field at fault. A formula that is too costly is refused before it runs (422 QUERY_TOO_EXPENSIVE).

Values by field type

Automations

An automation can be triggered through the API in two ways.

“API call” trigger.

• The automation declares its variables in the editor. Each variable has a name (letters, digits and _), a label, a type, whether it is required, a default value and a description.
• Possible types: text, number, boolean, date, dateTime, email, rowId, rowIds, json.
• Steps read the variables under trigger.inputs.<name>.
• A variable of type rowId names its table. The server checks that the row exists and loads it under trigger.inputs.<name>.fields.

“Button” trigger. It runs with a rowId, like a click in the app.

curl https://api.rangee.io/v1/automations/aut…/runs \
  -H "Authorization: Bearer $RANGEE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: relance-devis-2026-11-03" \
  -d '{
    "inputs": { "client": "row…", "montant": 1250, "relance": true },
    "wait": 10
  }'

For a “Button” trigger, send { "rowId": "row…" } instead of inputs.

Rules

Checked before running. A missing required variable, an unknown variable or a value of the wrong type answers 422 INVALID_INPUTS with the list of errors. Such a call counts neither as a run nor against the plan's quota.

Waiting with wait.

• Without wait: response 202, the run is queued (queued).
• With wait (0 to 30 seconds): the server waits for the run to finish, up to that delay. It answers 200 with the result if it finished, 202 otherwise.

Result. The “Return values” step computes name and value pairs from the run's data. They are returned in output. Without this step, output is {}.

Run states:

Active automations only. Only published, active automations run; the others answer 422 AUTOMATION_DISABLED.

Traceability. The run carries the token's name as its origin. It shows in the run history and in the history of the rows written.

Services without headers. The “Webhook received” trigger stays available for services that cannot send an Authorization header. Its secret URL accepts the same declared variables.

Webhooks

Rangee sends you a base's changes, without you having to read the data again: each delivery holds the rows concerned.

Events: row.created, row.updated, row.deleted, field.created, field.updated, field.deleted, table.created, table.updated, table.deleted.

Filters. tableIds limits the webhook to some tables. fieldIds limits row.updated to changes in those fields.

Body of a delivery:

{
  "id": "evt…",
  "type": "row.updated",
  "createdAt": "2026-11-03T09:30:00.000Z",
  "baseId": "app…",
  "tableId": "tbl…",
  "data": {
    "row": { "id": "row…", "createdAt": "…", "updatedAt": "…", "values": { "fld01Statut…": { "id": "sel…", "name": "Signé" } } },
    "previous": { "values": { "fld01Statut…": { "id": "sel…", "name": "Devis" } } }
  }
}

previous only holds the fields that changed. With includeValues: false, only IDs are sent.

Check the signature

Each delivery carries the header:

Rangee-Signature: t=<horodatage>,v1=<signature>

v1 is the HMAC-SHA256, in hexadecimal, of the string "<timestamp>.<raw body>", computed with the webhook's secret. The secret is shown only once, when the webhook is created.

Refuse any delivery whose timestamp is more than 5 minutes old, so it cannot be replayed.

Node.js:

import crypto from "node:crypto";

export function verifyRangeeSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python:

import hmac, hashlib, time

def verify_rangee_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = parts.get("t", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Compute the signature on the raw body received, before any JSON parsing.

Delivery

• At least once, in log order for a given row. Deduplicate by event id.
• A 2xx response within 10 seconds counts as received. Answer fast, and process afterwards.
• Otherwise, Rangee retries for 24 hours, waiting longer each time. After 24 hours of failures, the webhook is disabled and the workspace's Admins are told.
• A webhook does not expire: it lives until it is deleted.
• HTTPS URLs only, no private or local addresses.
• 20 webhooks per base at most.

Schema

Describing a field. A field is described by { id, name, type, description, readOnly, options }. The content of options depends on the type, and keeps the same shape for reading and writing.

Type names. They follow the app's, with “row” instead of “record”: multipleRowLinks, rowId. Triggers follow the same rule: rowCreated, rowUpdated, rowMatches, rowEntersView.

Changing the type. A PATCH with a new type changes the field's type and converts the values the way the app does.

Deleting a field.

• It takes the Admin or User role. The field goes to the trash.
• A field used by a formula, an automation or an interface answers 409 FIELD_IN_USE with the list of its uses.
• Add ?force=true to delete it anyway.

Attachments and comments

Adding an attachment takes two steps:

1. Upload the file. You receive { id, filename, size, type }.
2. Put { "id": "att…" } in an attachments value within the hour that follows. A file not used within that time is deleted.

curl https://api.rangee.io/v1/bases/app…/attachments \
  -H "Authorization: Bearer $RANGEE_TOKEN" \
  -F "file=@devis-atelier-martin.pdf"

Comments. A comment mentions a member with @[usr…]. Only its author can edit or delete it.

Errors

Every error has the same shape:

{
  "error": {
    "code": "INVALID_VALUE",
    "message": "« Montant » attend un nombre",
    "details": { "path": "rows[2].values.fld01Montant…" }
  }
}

Nothing is ignored silently. An invalid value, an unknown field, a computed field written or a missing variable answers 422, with the exact path of the error in details.path.

What to do, by code:

Limits

Every response gives your remaining rate in the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers.

Track your usage

Settings › Security › API tokens lists your tokens and when they were last used. GET /v1/me gives the organisation's call quota for the month.

Need help

Write to support quoting the call's Request-Id. It is enough to find the request, its response and its context.