Documentation de l'API

Démarrer en 5 minutes

1. Créez un jeton dans Réglages › Sécurité › Jetons API. Donnez-lui un nom et choisissez ses portées (par exemple rows:read et rows:write). Le jeton n'est montré qu'une fois : copiez-le.

2. Vérifiez qu'il fonctionne.

export RANGEE_TOKEN="pat…"

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

La réponse donne votre identité, le nom du jeton, ses portées, son périmètre et le quota du mois.

3. Trouvez vos tables. La réponse de GET /v1/bases/app… liste les tables de la base, avec leurs identifiants.

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. Lisez vos lignes, clées par nom de champ pour commencer.

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

5. Créez une ligne.

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

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

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

Accès et jetons

Chaque appel porte un jeton personnel dans l'en-tête :

Authorization: Bearer pat….…

Un jeton a un nom, des portées, un périmètre et, si vous le souhaitez, une date d'expiration.

Il hérite du rôle de son créateur dans chaque base. Le jeton d'une personne en lecture seule n'écrit jamais, même avec la portée rows:write.

Il est coupé immédiatement si vous le révoquez, ou si son créateur est retiré du workspace ou désactivé.

Portées

Périmètre

Un jeton couvre soit toutes les bases du workspace auxquelles son créateur a accès, soit une liste de bases choisie. Un jeton ne traverse jamais deux workspaces.

Une ressource hors du périmètre du jeton répond 404, exactement comme une ressource qui n'existe pas.

Identité

GET /v1/me

Renvoie la personne, le nom du jeton, ses portées, son périmètre et le quota d'appels du mois.

Vocabulaire et identifiants

Les identifiants sont opaques. Ne les construisez pas et ne les analysez pas : seul l'identifiant complet a un sens.

Conventions

• Format. JSON en UTF-8. Dates et heures en ISO 8601 UTC (2026-11-03T09:30:00.000Z), dates sans heure en YYYY-MM-DD.
• Ressource ou liste. Une ressource unique est renvoyée telle quelle. Une liste a la forme { "data": [...], "nextCursor": "…" | null }.
• Pagination. Par curseur opaque : limit (de 1 à 1 000, 100 par défaut) et cursor. Un curseur reste valable 24 heures. Quand nextCursor vaut null, vous avez tout lu.
• Lots. Une écriture porte de 1 à 100 lignes. Un lot est atomique : tout passe, ou rien.
• Désignation. Une table, un champ ou une vue se désigne par son identifiant. Les noms de champs ne sont acceptés que comme clés de values, en écriture.
• Clés de lecture. Les valeurs sont clées par identifiant de champ. Ajoutez fieldKey=name à n'importe quelle lecture de lignes pour les recevoir clées par nom.
• Rejouer sans risque. Toute requête POST, PATCH, PUT ou DELETE accepte un en-tête Idempotency-Key (1 à 255 caractères). Le même appel rejoué dans les 24 heures renvoie la même réponse sans rien réécrire. La même clé avec un corps différent répond 409 IDEMPOTENCY_CONFLICT.
• Support. Chaque réponse porte un en-tête Request-Id. Citez-le au support : il suffit pour retrouver l'appel.

Paginer

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

Lignes

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

Valeurs vides. Une valeur vide n'apparaît pas dans values. Pour vider une valeur, écrivez null.

Règles d'écriture

PATCH ou PUT. PATCH ne touche que les champs envoyés. PUT remplace la ligne : les champs absents du corps sont vidés.

Champs calculés. Ils refusent l'écriture (422 READ_ONLY_FIELD) : formule, lookup, rollup, compteur, numéro automatique, dates et auteurs de création et de modification, bouton.

Conversion avec "coerce": true. Ajoutée au corps, l'option convertit les textes en nombres, dates et cases cochées, et crée les options de sélection inconnues. Sans elle, une valeur au mauvais type répond 422 INVALID_VALUE.

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

Upsert.

• matchOn liste de 1 à 3 champs, de type texte, e-mail, nombre, numéro automatique, URL ou téléphone.
• Chaque ligne envoyée qui correspond à exactement une ligne existante la modifie. Si elle n'en trouve aucune, elle est créée. Si elle en trouve plusieurs, l'appel répond 409 UPSERT_AMBIGUOUS.
• La réponse distingue les lignes créées (created) des lignes modifiées (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" } }
    ]
  }'

Suppression. Une ligne supprimée va à la corbeille de la base pendant 30 jours. Elle se restaure depuis l'application.

Limite du plan. Une création au-delà du nombre de lignes autorisé par votre plan répond 422 ROW_LIMIT, avec le nombre de lignes restant.

Chercher des lignes

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

Le corps reprend la forme des filtres des vues de l'application :

filter, search, viewId et formula se combinent par « et ».

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

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

Chaque type de champ n'accepte qu'une partie de ces opérateurs. Un opérateur non accepté répond 422 INVALID_FILTER en nommant le champ en cause. Une formule trop coûteuse est refusée avant d'être exécutée (422 QUERY_TOO_EXPENSIVE).

Valeurs par type de champ

Automatisations

Une automatisation se déclenche par l'API de deux façons.

Déclencheur « Appel API ».

• L'automatisation déclare ses variables dans l'éditeur. Chaque variable a un nom (lettres, chiffres et _), un libellé, un type, un caractère obligatoire ou non, une valeur par défaut et une description.
• Types possibles : text, number, boolean, date, dateTime, email, rowId, rowIds, json.
• Les étapes lisent les variables sous trigger.inputs.<nom>.
• Une variable de type rowId précise sa table. Le serveur vérifie que la ligne existe et la charge sous trigger.inputs.<nom>.fields.

Déclencheur « Bouton ». Il se déclenche avec un rowId, comme un clic dans l'application.

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

Pour un déclencheur « Bouton », envoyez { "rowId": "row…" } à la place de inputs.

Règles

Vérification avant exécution. Une variable obligatoire absente, une variable inconnue ou une valeur au mauvais type répond 422 INVALID_INPUTS avec la liste des erreurs. Cet appel ne compte ni comme exécution, ni dans le quota du plan.

Attente avec wait.

• Sans wait : réponse 202, l'exécution est mise en file (queued).
• Avec wait (0 à 30 secondes) : le serveur attend la fin de l'exécution jusqu'à ce délai. Il répond 200 avec le résultat si elle a fini, sinon 202.

Résultat. L'étape « Renvoyer des valeurs » calcule des paires nom et valeur sur les données de l'exécution. Elles sont renvoyées dans output. Sans cette étape, output vaut {}.

États d'une exécution :

Automatisations actives seulement. Seules les automatisations publiées et actives se déclenchent ; les autres répondent 422 AUTOMATION_DISABLED.

Traçabilité. L'exécution porte le nom du jeton comme origine. Il apparaît dans l'historique des exécutions et dans celui des lignes écrites.

Services sans en-tête. Le déclencheur « Webhook reçu » reste disponible pour les services qui ne savent pas envoyer d'en-tête Authorization. Son URL secrète accepte les mêmes variables déclarées.

Webhooks

Rangee vous envoie les changements d'une base, sans que vous ayez à relire les données : chaque livraison contient les lignes concernées.

Événements : row.created, row.updated, row.deleted, field.created, field.updated, field.deleted, table.created, table.updated, table.deleted.

Filtres. tableIds limite le webhook à certaines tables. fieldIds limite row.updated aux changements de ces champs.

Corps d'une livraison :

{
  "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 ne contient que les champs changés. Avec includeValues: false, seuls les identifiants sont envoyés.

Vérifier la signature

Chaque livraison porte l'en-tête :

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

v1 est le HMAC-SHA256, en hexadécimal, de la chaîne "<horodatage>.<corps brut>", calculé avec le secret du webhook. Le secret n'est montré qu'une fois, à la création du webhook.

Refusez toute livraison dont l'horodatage a plus de 5 minutes, pour éviter qu'elle soit rejouée.

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

Calculez la signature sur le corps brut reçu, avant tout analyse du JSON.

Livraison

• Au moins une fois, dans l'ordre du journal pour une même ligne. Dédoublonnez par id d'événement.
• Une réponse 2xx en moins de 10 secondes vaut réception. Répondez vite, et traitez ensuite.
• Sinon, Rangee réessaie pendant 24 heures, avec une attente croissante. Après 24 heures d'échecs, le webhook est désactivé et les Admins du workspace sont prévenus.
• Un webhook n'expire pas : il vit jusqu'à sa suppression.
• Adresse en HTTPS uniquement, hors adresses privées et locales.
• 20 webhooks par base au plus.

Schéma

Description d'un champ. Un champ se décrit par { id, name, type, description, readOnly, options }. Le contenu de options dépend du type, et garde la même forme en lecture et en écriture.

Noms de types. Ils reprennent ceux de l'application, avec « row » à la place de « record » : multipleRowLinks, rowId. Les déclencheurs suivent la même règle : rowCreated, rowUpdated, rowMatches, rowEntersView.

Changer de type. Un PATCH avec un nouveau type change le type du champ et convertit les valeurs comme le fait l'application.

Supprimer un champ.

• Il faut le rôle Admin ou User. Le champ va à la corbeille.
• Un champ utilisé par une formule, une automatisation ou une interface répond 409 FIELD_IN_USE avec la liste de ses usages.
• Ajoutez ?force=true pour le supprimer quand même.

Pièces jointes et commentaires

Ajouter une pièce jointe se fait en deux temps :

1. Téléversez le fichier. Vous recevez { id, filename, size, type }.
2. Placez { "id": "att…" } dans une valeur de pièces jointes dans l'heure qui suit. Un fichier non utilisé dans ce délai est supprimé.

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

Commentaires. Un commentaire mentionne un membre avec @[usr…]. Seul son auteur peut le modifier ou le supprimer.

Erreurs

Toutes les erreurs ont la même forme :

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

Rien n'est ignoré en silence. Une valeur invalide, un champ inconnu, un champ calculé écrit ou une variable manquante répondent 422, avec le chemin exact de l'erreur dans details.path.

Que faire selon le code :

Limites

Chaque réponse indique votre débit restant dans les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset.

Suivre votre usage

Réglages › Sécurité › Jetons API liste vos jetons et leur dernier usage. GET /v1/me donne le quota d'appels du mois de l'organisation.

Besoin d'aide

Écrivez au support en citant le Request-Id de l'appel concerné. Il suffit pour retrouver la requête, sa réponse et son contexte.