Guide développeur
Interroger APIBASE par codeDeveloper Guide
Querying APIBASE from code

Comment ça fonctionneHow it works

APIBASE expose les données par coordonnées, pas par SQL. Chaque valeur dans votre base possède une adresse : un ID de table, une ligne et un ID de colonne.

APIBASE exposes data through coordinates, not SQL. Every value in your base has an address: a Table ID, a Line, and a Column ID.

Votre proxy conserve le token. Votre frontend appelle votre proxy. APIBASE ne voit jamais le navigateur directement.

Your proxy holds the token. Your frontend calls your proxy. APIBASE never sees the browser.

# the flow
Browser → your proxy (holds token) → APIBASE
                                  ↳ checks ACL
                                  ↳ returns data

Tokens et ACLs Hive — le flux completTokens and Hive ACLs — the complete flow

Chaque utilisateur crée ses propres tokens dans son compte APIBASE. Le même compte peut posséder simultanément un token full et un token hive.

Every user creates their own tokens in their APIBASE account. The same account can hold both a full token and a hive token simultaneously.

# Worker's tokens page — creates their own hive token
id_token  label                  scope  status
19        Agent-research For HIVE  hive   Active

Une fois que le worker possède son token, il communique son ID de token (ici : 19) au propriétaire de la base. Le propriétaire ouvre ensuite Account → Hive ACLs → Add ACL et définit précisément les tables accessibles par ce token ainsi que les droits accordés :

Once the worker has their token, they communicate the token ID (here: 19) to the base owner. The owner then opens Account → Hive ACLs → Add ACL and sets exactly which tables that token can access and with which rights:

# Owner's Hive ACLs — one rule per token + table
id_token  label                    table          read  add  edit  delete
19        Agent-research For HIVE  memorys (T30)   ✓    ✓    —     —

Étape 1 — Découvrir votre schémaStep 1 — Discover your schema

Appelez l’endpoint schema pour obtenir les IDs T et C avant de construire vos requêtes.

Call the schema endpoint to get T and C ids before building your queries.

Token propriétaire (scope: full)Owner token (scope: full)

Token worker (scope: hive)Worker token (scope: hive)

GET /hive/schema/pierre/equipements

{
  "status":  "success",
  "table":   "equipements",
  "T":       31,
  "columns": {
    "1": "id_equipement",
    "2": "equipement",
    "3": "nom",
    "4": "categorie"
  },
  "hive_base": "pierre"
}

Étape 2 — Structure d’URLStep 2 — URL structure

Chaque requête de lecture suit ce modèle. Les segments sont positionnels — la valeur de filtre va seulement dans ?V=.

Every read request follows this pattern. Segments are positional — filter value in ?V= only.

# all rows
GET /hive/get/{base}/T31/L

# one row by primary key
GET /hive/get/{base}/T31/L42

# filter: category == "HVAC"
GET /hive/get/{base}/T31/L/C4/O1?V=HVAC

# filter: name contains "pump"
GET /hive/get/{base}/T31/L/C3/O28?V=pump

# named keys (format=assoc)
GET /hive/get/{base}/T31/L?format=assoc

# single cell value
GET /hive/get/{base}/T31/L42/C3

Étape 3 — OpérateursStep 3 — Operators

Passez le numéro d’opérateur dans le segment O{n} et la valeur à tester dans ?V=.

Pass the operator number in the O{n} segment and the test value in ?V=.

O	SymboleSymbol	Description	Exemple ?V=Example ?V=
1	==	Equal (loose, numeric-aware)	V=42
3	!=	Not equal	V=draft
6	<	Less than	V=100
7	>	Greater than	V=1000
28	LIKE	Contains (case-insensitive)	V=pump
32	BETWEEN	Inclusive range — _ separator	V=100_500
33	IN LIST	Value is one of — _ separator	V=new_reserved

Endpoints d’écritureWrite endpoints

POST, PUT et DELETE suivent le même système de coordonnées. Le token doit posséder le droit ACL correspondant.

POST, PUT, and DELETE follow the same coordinate system. The token must have the matching ACL right.

# POST — add a record
POST /hive/post/pierre/T31
Authorization: Bearer <token>

{ "record": { "nom": "Centrifugal pump", "categorie": "HVAC" } }

# PUT cell — update one value
PUT /hive/put/pierre/T31/L99/C4
{ "value": "Plumbing" }

Archives — le coffre à suffixesArchives — the Suffix Vault

Quand une table devient trop volumineuse, elle est rotée vers une archive en lecture seule. La table active reste rapide. L’historique reste interrogeable.

When a table fills up, it rotates into a read-only archive. The active table stays fast. The past stays queryable.

Chaque table APIBASE possède un compteur de cellules. Lorsqu’il atteint sa limite, vous déclenchez une rotation depuis le tableau de bord : APIBASE prend un snapshot global de cohérence — toutes les tables liées en même temps — et le fige comme segment d’archive en lecture seule. La table active repart ensuite allégée.

Each APIBASE table has a cell counter. When it reaches its limit, you trigger a rotation from the dashboard: APIBASE takes a global consistency snapshot — all related tables at once — and freezes it as a read-only archive chunk. The active table starts fresh.

Pour interroger une archive, ajoutez ?archive={suffix} à n’importe quelle requête de lecture. Tout le reste demeure identique — même T, même L, même C, mêmes opérateurs.

To query an archive, add ?archive={suffix} to any read request. Everything else stays identical — same T, same L, same C, same operators.

# active table — default, no parameter needed
GET /hive/get/{base}/T2/L95

# same record in archive chunk "aaa"
GET /hive/get/{base}/T2/L95?archive=aaa

# filter across an archive chunk
GET /hive/get/{base}/T2/L/C3/O1?V=active&archive=aab&format=assoc

Exemples completsComplete examples

Un proxy minimal en trois langages. Le token reste côté serveur. Le navigateur reste propre.

A minimal proxy in three languages. The token stays server-side. The browser stays clean.

Ces exemples utilisent un token hive — créé dans votre propre compte APIBASE, avec des droits accordés par le propriétaire de la base.

These examples use a hive token — created in your own APIBASE account, with rights granted by the base owner.

JavaScript (Node / fetch)

const API        = 'https://apibase.work';
const BASE       = 'pierre';            // basekey of the owner's base
const HIVE_TOKEN = process.env.HIVE_TOKEN; // your hive token (scope: hive)

// 1 — discover schema (only tables the owner granted you)
const schema = await fetch(
  `${API}/hive/schema/${BASE}/equipements`,
  { headers: { Authorization: `Bearer ${HIVE_TOKEN}` } }
).then(r => r.json());

const T = schema.T;  // 31 — store this in config

// 2 — query: category == "HVAC"
const result = await fetch(
  `${API}/hive/get/${BASE}/T${T}/L/C4/O1?V=HVAC&format=assoc`,
  { headers: { Authorization: `Bearer ${HIVE_TOKEN}` } }
).then(r => r.json());

PHP

$api       = 'https://apibase.work';
$base      = 'pierre';               // basekey of the owner's base
$hiveToken = getenv('HIVE_TOKEN');   // your hive token (scope: hive)

// 1 — schema once — store T + C ids in config
$schema = api_get("$api/hive/schema/$base/equipements", $hiveToken);
$T      = $schema['T'];  // 31

// 2 — filter: nom contains "pump"
$rows = api_get("$api/hive/get/$base/T{$T}/L/C3/O28?V=pump&format=assoc", $hiveToken)['data'];

Python

import os, requests

API        = "https://apibase.work"
BASE       = "pierre"                 # basekey of the owner's base
HIVE_TOKEN = os.environ["HIVE_TOKEN"]  # your hive token (scope: hive)
HDR        = {"Authorization": f"Bearer {HIVE_TOKEN}"}

# 1 — schema once
T = requests.get(f"{API}/hive/schema/{BASE}/equipements", headers=HDR).json()["T"]

# 2 — BETWEEN: id between 60001 and 60100
rows = requests.get(
  f"{API}/hive/get/{BASE}/T{T}/L/C1/O32?V=60001_60100&format=assoc",
  headers=HDR,
).json()["data"]

Checklist d’intégrationIntegration checklist

1. Créez votre tokenCreate your token Dans votre compte APIBASE, générez un token avec le scope hive. Donnez votre ID de token au propriétaire de la base — il vous accorde les droits table par table. Gardez le token côté serveur seulement.In your APIBASE account, generate a token with scope hive. Give your token ID to the base owner — they grant you rights table by table. Keep the token server-side only.
2. Appelez /schema une foisCall /schema once Récupérez les IDs T et C pour chaque table nécessaire. Stockez-les dans un fichier de config ou des constantes. Ils sont permanents.Retrieve T and C ids for each table you need. Store them in a config file or constants. They are permanent.
3. Construisez votre proxyBuild your proxy Un seul fichier dans le langage de votre choix. Il lit le token depuis une variable d’environnement, relaie les requêtes vers APIBASE et retourne le JSON au navigateur.One file in any language. Reads the token from an environment variable, relays requests to APIBASE, returns JSON to the browser.
4. Interrogez par coordonnéesQuery by coordinates Utilisez T{n}/L pour les tables complètes, T{n}/L{pk} pour une ligne, C{n}/O{op}?V= pour les filtres. Ajoutez ?format=assoc pour obtenir des clés nommées.Use T{n}/L for full tables, T{n}/L{pk} for one row, C{n}/O{op}?V= for filters. Add ?format=assoc for named keys.
5. Vérifiez la réponseCheck the response Chaque réponse inclut "status": "success" ou une erreur HTTP avec "message". Les lectures et écritures refusées sont explicites — jamais silencieuses.Every response includes "status": "success" or an HTTP error with "message". Denied reads and writes are explicit — never silent.