API REST

Chaque objet que vous déclarez obtient automatiquement un ensemble complet de points de terminaison REST. Chaque action devient un POST. Chaque flow devient un POST vers /flows/.... Il n'y a aucune couche API distincte à écrire ou à déployer.

URL de base : https://<your-host>/api/v1. La spécification OpenAPI est disponible en direct sur /api/v1/openapi.json.

Authentification

ObjectOS utilise Better Auth. Toutes les routes sous /api/v1 requièrent une session authentifiée, sauf si elles sont explicitement marquées comme publiques (voir Formulaires publics). Les méthodes d'authentification sont configurées dans apps/<app>/auth.config.ts — typiquement un cookie de session ou un jeton bearer issu de /api/v1/auth/sign-in.

Les permissions sont vérifiées par route, par enregistrement. Les routes annotées ci-dessous avec une clé de permission (par ex. ai:chat) appellent requirePermission(...) ; l'accès au niveau de l'enregistrement est appliqué par RBAC + sécurité au niveau des lignes + sécurité au niveau des champs au sein du moteur de données.

Discovery

Restreindre la surface d'API

Les endpoints générés automatiquement sont gouvernés par objet, de sorte que vous pouvez retirer un objet de l'API ou le rendre en lecture seule sans écrire aucun code de route :

• apiEnabled (booléen, par défaut true) — définissez false pour retirer entièrement l'objet de la surface REST. Les requêtes vers ses routes renvoient 404.
• apiMethods (liste blanche optionnelle) — lorsqu'elle est définie, seules les opérations listées sont accessibles ; toute autre opération est rejetée au niveau de la couche REST. Valeurs autorisées : get, list, create, update, delete, upsert, bulk, aggregate, history, search, restore, purge, import, export.

// Un objet de référence en lecture seule, jamais inscriptible via l'API :
defineObject({
  name: 'exchange_rate',
  apiMethods: ['get', 'list'],
  // ...fields
})

// Un objet interne que l'API n'expose jamais :
defineObject({
  name: 'sync_cursor',
  apiEnabled: false,
  // ...fields
})

Les deux sont désormais appliqués au niveau de la couche REST (ADR-0049) — les versions antérieures analysaient ces propriétés mais ne les appliquaient pas.

Données — /api/v1/data/*

CRUD + requêtes avancées pour chaque objet que vous déclarez. :object est le name de l'objet (snake_case).

Exemple rapide

GET /api/v1/data/support_ticket?where={"status":{"$eq":"open"}}&orderBy=-created_at&limit=20
Authorization: Bearer <token>

{
  "items": [ { "id": "...", "subject": "...", "status": "open" } ],
  "total": 137,
  "nextCursor": "eyJpZCI6IjAxSDA..."
}

IA — /api/v1/ai/*

Les points de terminaison sur lesquels reposent l'AI Builder et vos agents.

La séparation entre ai:read et ai:approve est la primitive de sécurité qui rend l'AI Builder sûr pour les utilisateurs finaux.

Actions — /api/v1/actions/*

Chaque *.action.ts que vous déclarez devient un point de terminaison.

Chaque action est également exposée à l'IA sous forme d'outil action_<name> — voir Actions.

Flows — /api/v1/flows/*

Métadonnées — /api/v1/meta/*

Introspection en lecture seule des métadonnées du runtime en cours d'exécution. Utile pour l'outillage et la Console.

Partage et approbations

Rapports et recherche

Formulaires publics

Les seules routes qui sont non authentifiées, activées de manière optionnelle via FormView.sharing.allowAnonymous.

Utilitaires

Enveloppe d'erreur

Chaque réponse non-2xx suit la même forme :

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Missing ai:approve on conversation 01H…",
    "details": { "permission": "ai:approve", "subject": "01H…" }
  }
}

Codes courants : UNAUTHENTICATED, PERMISSION_DENIED, VALIDATION_ERROR, NOT_FOUND, CONCURRENT_UPDATE, RATE_LIMITED, INTERNAL.

Versionnage

/api/v1 est l'API stable. Les changements incompatibles vont vers /api/v2 et les deux sont servies en parallèle pendant une version mineure. La version actuelle et l'horizon de dépréciation se trouvent dans GET /api/v1.

Voir aussi

• ObjectQL — le langage de requête utilisé par /data/*
• Types de champs — les formes que peuvent prendre les données
• Build → Actions — déclarer des points de terminaison personnalisés
• Sécurité — ce que chaque route vérifie avant de s'exécuter