API-Dokumentation

In 5 Minuten starten

1. Erstellen Sie ein Token unter Einstellungen › Sicherheit › API-Tokens. Geben Sie ihm einen Namen und wählen Sie seine Berechtigungen (zum Beispiel rows:read und rows:write). Das Token wird nur einmal angezeigt: Kopieren Sie es.

2. Prüfen Sie, ob es funktioniert.

export RANGEE_TOKEN="pat…"

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

Die Antwort liefert Ihre Identität, den Namen des Tokens, seine Berechtigungen, seinen Bereich und das Kontingent des Monats.

3. Finden Sie Ihre Tabellen. Die Antwort von GET /v1/bases/app… listet die Tabellen der Base mit ihren IDs auf.

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. Lesen Sie Ihre Zeilen, für den Anfang nach Feldnamen geschlüsselt.

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

5. Legen Sie eine Zeile an.

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()

Zugriff und Tokens

Jeder Aufruf trägt ein persönliches Token im Header:

Authorization: Bearer pat….…

Ein Token hat einen Namen, Berechtigungen, einen Bereich und, wenn Sie möchten, ein Ablaufdatum.

Es erbt die Rolle seines Erstellers in jeder Base. Das Token einer Person mit Lesezugriff schreibt nie, auch nicht mit der Berechtigung rows:write.

Es wird sofort gesperrt, wenn Sie es widerrufen oder wenn sein Ersteller aus dem Workspace entfernt oder deaktiviert wird.

Berechtigungen

Bereich

Ein Token umfasst entweder alle Bases des Workspace, auf die sein Ersteller Zugriff hat, oder eine gewählte Liste von Bases. Ein Token reicht nie über zwei Workspaces.

Eine Ressource außerhalb des Bereichs des Tokens antwortet mit 404, genau wie eine Ressource, die nicht existiert.

Identität

GET /v1/me

Liefert die Person, den Namen des Tokens, seine Berechtigungen, seinen Bereich und das Aufrufkontingent des Monats.

Begriffe und IDs

IDs sind undurchsichtig. Bauen Sie sie nicht selbst und zerlegen Sie sie nicht: Nur die vollständige ID hat eine Bedeutung.

Konventionen

• Format. JSON in UTF-8. Datum und Uhrzeit in ISO 8601 UTC (2026-11-03T09:30:00.000Z), Daten ohne Uhrzeit als YYYY-MM-DD.
• Ressource oder Liste. Eine einzelne Ressource wird unverändert zurückgegeben. Eine Liste hat die Form { "data": [...], "nextCursor": "…" | null }.
• Paginierung. Mit undurchsichtigem Cursor: limit (1 bis 1.000, standardmäßig 100) und cursor. Ein Cursor bleibt 24 Stunden gültig. Wenn nextCursor null ist, haben Sie alles gelesen.
• Stapel. Ein Schreibvorgang umfasst 1 bis 100 Zeilen. Ein Stapel ist atomar: Alles geht durch oder nichts.
• Bezeichnung. Eine Tabelle, ein Feld oder eine Ansicht wird über ihre ID angesprochen. Feldnamen werden nur als Schlüssel von values beim Schreiben akzeptiert.
• Leseschlüssel. Die Werte sind nach Feld-ID geschlüsselt. Fügen Sie fieldKey=name zu jedem Lesen von Zeilen hinzu, um sie nach Namen geschlüsselt zu erhalten.
• Risikolos wiederholen. Jede Anfrage POST, PATCH, PUT oder DELETE akzeptiert einen Header Idempotency-Key (1 bis 255 Zeichen). Derselbe Aufruf, innerhalb von 24 Stunden wiederholt, liefert dieselbe Antwort, ohne erneut zu schreiben. Derselbe Schlüssel mit anderem Body antwortet mit 409 IDEMPOTENCY_CONFLICT.
• Support. Jede Antwort trägt einen Header Request-Id. Nennen Sie ihn dem Support: Er genügt, um den Aufruf wiederzufinden.

Paginieren

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);
}

Zeilen

{
  "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
  }
}

Leere Werte. Ein leerer Wert erscheint nicht in values. Um einen Wert zu leeren, schreiben Sie null.

Schreibregeln

PATCH oder PUT. PATCH ändert nur die gesendeten Felder. PUT ersetzt die Zeile: Im Body fehlende Felder werden geleert.

Berechnete Felder. Sie lehnen das Schreiben ab (422 READ_ONLY_FIELD): Formel, Lookup, Rollup, Zähler, Autonummer, Datum und Autor der Erstellung und Änderung, Schaltfläche.

Umwandlung mit "coerce": true. Im Body angegeben, wandelt die Option Texte in Zahlen, Daten und Kontrollkästchen um und legt unbekannte Auswahloptionen an. Ohne sie antwortet ein Wert mit falschem Typ mit 422 INVALID_VALUE.

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

Upsert.

• matchOn nennt 1 bis 3 Felder vom Typ Text, E-Mail, Zahl, Autonummer, URL oder Telefon.
• Jede gesendete Zeile, die auf genau eine bestehende Zeile passt, ändert diese. Findet sie keine, wird sie angelegt. Findet sie mehrere, antwortet der Aufruf mit 409 UPSERT_AMBIGUOUS.
• Die Antwort unterscheidet angelegte Zeilen (created) von geänderten Zeilen (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" } }
    ]
  }'

Löschen. Eine gelöschte Zeile kommt für 30 Tage in den Papierkorb der Base. Sie lässt sich in der Anwendung wiederherstellen.

Planlimit. Ein Anlegen über die in Ihrem Plan erlaubte Zeilenzahl hinaus antwortet mit 422 ROW_LIMIT und der Zahl der verbleibenden Zeilen.

Zeilen suchen

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

Der Body übernimmt die Form der Filter der Ansichten in der Anwendung:

filter, search, viewId und formula werden mit „und“ kombiniert.

{
  "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
}

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

Jeder Feldtyp akzeptiert nur einen Teil dieser Operatoren. Ein nicht akzeptierter Operator antwortet mit 422 INVALID_FILTER und nennt das betroffene Feld. Eine zu aufwendige Formel wird vor der Ausführung abgelehnt (422 QUERY_TOO_EXPENSIVE).

Werte nach Feldtyp

Automatisierungen

Eine Automatisierung lässt sich auf zwei Arten über die API auslösen.

Auslöser „API-Aufruf“.

• Die Automatisierung deklariert ihre Variablen im Editor. Jede Variable hat einen Namen (Buchstaben, Ziffern und _), eine Bezeichnung, einen Typ, die Angabe, ob sie Pflicht ist, einen Standardwert und eine Beschreibung.
• Mögliche Typen: text, number, boolean, date, dateTime, email, rowId, rowIds, json.
• Die Schritte lesen die Variablen unter trigger.inputs.<name>.
• Eine Variable vom Typ rowId nennt ihre Tabelle. Der Server prüft, ob die Zeile existiert, und lädt sie unter trigger.inputs.<name>.fields.

Auslöser „Schaltfläche“. Er wird mit einer rowId ausgelöst, wie ein Klick in der Anwendung.

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
  }'

Senden Sie für einen Auslöser „Schaltfläche“ { "rowId": "row…" } statt inputs.

Regeln

Prüfung vor der Ausführung. Eine fehlende Pflichtvariable, eine unbekannte Variable oder ein Wert mit falschem Typ antwortet mit 422 INVALID_INPUTS und der Liste der Fehler. Dieser Aufruf zählt weder als Ausführung noch zum Kontingent des Plans.

Warten mit wait.

• Ohne wait: Antwort 202, die Ausführung wird eingereiht (queued).
• Mit wait (0 bis 30 Sekunden): Der Server wartet bis zu dieser Frist auf das Ende der Ausführung. Er antwortet mit 200 und dem Ergebnis, wenn sie beendet ist, sonst mit 202.

Ergebnis. Der Schritt „Werte zurückgeben“ berechnet Name-Wert-Paare aus den Daten der Ausführung. Sie werden in output zurückgegeben. Ohne diesen Schritt ist output gleich {}.

Status einer Ausführung:

Nur aktive Automatisierungen. Nur veröffentlichte und aktive Automatisierungen laufen; die anderen antworten mit 422 AUTOMATION_DISABLED.

Nachvollziehbarkeit. Die Ausführung trägt den Namen des Tokens als Herkunft. Er erscheint im Verlauf der Ausführungen und in dem der geschriebenen Zeilen.

Dienste ohne Header. Der Auslöser „Webhook empfangen“ bleibt für Dienste verfügbar, die keinen Header Authorization senden können. Seine geheime URL akzeptiert dieselben deklarierten Variablen.

Webhooks

Rangee schickt Ihnen die Änderungen einer Base, ohne dass Sie die Daten erneut lesen müssen: Jede Zustellung enthält die betroffenen Zeilen.

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

Filter. tableIds beschränkt den Webhook auf bestimmte Tabellen. fieldIds beschränkt row.updated auf Änderungen dieser Felder.

Body einer Zustellung:

{
  "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 enthält nur die geänderten Felder. Mit includeValues: false werden nur die IDs gesendet.

Signatur prüfen

Jede Zustellung trägt den Header:

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

v1 ist der HMAC-SHA256 in Hexadezimal der Zeichenkette "<zeitstempel>.<roher body>", berechnet mit dem Secret des Webhooks. Das Secret wird nur einmal angezeigt, beim Anlegen des Webhooks.

Lehnen Sie jede Zustellung ab, deren Zeitstempel älter als 5 Minuten ist, damit sie nicht wiederholt werden kann.

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", ""))

Berechnen Sie die Signatur auf dem empfangenen rohen Body, bevor Sie das JSON auswerten.

Zustellung

• Mindestens einmal, in der Reihenfolge des Journals für dieselbe Zeile. Entfernen Sie Duplikate anhand der Ereignis-id.
• Eine Antwort 2xx in weniger als 10 Sekunden gilt als Empfang. Antworten Sie schnell und verarbeiten Sie danach.
• Andernfalls versucht Rangee es 24 Stunden lang mit wachsenden Abständen erneut. Nach 24 Stunden Fehlschlägen wird der Webhook deaktiviert und die Admins des Workspace werden benachrichtigt.
• Ein Webhook läuft nicht ab: Er besteht, bis er gelöscht wird.
• Nur HTTPS-Adressen, keine privaten oder lokalen Adressen.
• Höchstens 20 Webhooks pro Base.

Schema

Beschreibung eines Felds. Ein Feld wird durch { id, name, type, description, readOnly, options } beschrieben. Der Inhalt von options hängt vom Typ ab und hat beim Lesen und Schreiben dieselbe Form.

Typnamen. Sie folgen denen der Anwendung, mit „row“ statt „record“: multipleRowLinks, rowId. Die Auslöser folgen derselben Regel: rowCreated, rowUpdated, rowMatches, rowEntersView.

Typ ändern. Ein PATCH mit einem neuen type ändert den Typ des Felds und wandelt die Werte so um wie die Anwendung.

Ein Feld löschen.

• Dafür ist die Rolle Admin oder User nötig. Das Feld kommt in den Papierkorb.
• Ein Feld, das von einer Formel, einer Automatisierung oder einem Interface verwendet wird, antwortet mit 409 FIELD_IN_USE und der Liste seiner Verwendungen.
• Fügen Sie ?force=true hinzu, um es trotzdem zu löschen.

Anhänge und Kommentare

Einen Anhang hinzufügen geht in zwei Schritten:

1. Laden Sie die Datei hoch. Sie erhalten { id, filename, size, type }.
2. Setzen Sie { "id": "att…" } innerhalb der folgenden Stunde in einen Anhangswert. Eine in dieser Zeit nicht verwendete Datei wird gelöscht.

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

Kommentare. Ein Kommentar erwähnt ein Mitglied mit @[usr…]. Nur sein Autor kann ihn bearbeiten oder löschen.

Fehler

Alle Fehler haben dieselbe Form:

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

Nichts wird stillschweigend ignoriert. Ein ungültiger Wert, ein unbekanntes Feld, ein beschriebenes berechnetes Feld oder eine fehlende Variable antworten mit 422 und dem genauen Pfad des Fehlers in details.path.

Was zu tun ist, je nach Code:

Limits

Jede Antwort nennt Ihre verbleibende Rate in den Headern RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset.

Ihre Nutzung verfolgen

Einstellungen › Sicherheit › API-Tokens listet Ihre Tokens und ihre letzte Nutzung auf. GET /v1/me liefert das monatliche Aufrufkontingent der Organisation.

Hilfe

Schreiben Sie dem Support und nennen Sie die Request-Id des betreffenden Aufrufs. Sie genügt, um die Anfrage, ihre Antwort und ihren Kontext wiederzufinden.