API
Référence de l’API REST d’Orbit : URL de base, authentification, scopes, clés développeur, endpoints du Brain, limites et erreurs.
L’API REST d’Orbit branche Brain et Studio sur votre code : contexte déterministe, Context Pack, profil portable, Alignment Check, graphe utilisateur, écriture Memory de compatibilité, propositions de changement, Skills portables, journal d’activité des agents, génération Studio et lecture d’Artifacts durables. Elle partage les mêmes credentials/scopes que le serveur MCP et réutilise les mêmes capabilities de domaine.
| URL de base | https://orbit.easyconnector.app/api/v1 |
| Authentification | Authorization: Bearer … : clé orb_… ou jeton d’accès OAuth Orbit |
| Scopes proposés | brain:read, brain:write, studio:read, studio:generate, artifacts:read, activity:read, activity:write (et spaces:manage, en cours de déploiement) ; l’ancien projects:read reste reconnu pour les clés qui le portent déjà |
| Format | JSON |
| Référence | cette page |
Pour une première connexion guidée, suivez MCP ou API : premier test. Cette page conserve la référence détaillée des appels.
Authentification et scopes
Deux credentials sont acceptés :
- une clé développeur
orb_…(ci-dessous), pour vos serveurs, scripts et CI ; - un jeton d’accès OAuth émis par Orbit (voir MCP, section OAuth), avec les scopes accordés au consentement.
| Scope | Ce qu’il permet |
|---|---|
brain:read | Lister/lire les espaces (Space), construire Context Packs, profil et Alignment Checks, chercher, lire le graphe utilisateur, les propositions et les Skills. |
brain:write | Ajouter des Memories de compatibilité, créer/éditer/relier les Nodes d’organisation, déposer ou refuser des propositions. |
projects:read | Ancien scope (« Anciens projets Studio ») : lire les fiches de projets historiques via GET /projects. Il n’est plus proposé à une nouvelle clé. |
studio:read | Lire l’état d’une génération Studio. |
studio:generate | Lancer une génération ou une révision Studio payante via le ledger Orbit. |
artifacts:read | Lire un Artifact Studio durable autorisé. |
activity:read | Lire le journal d’activité des agents. |
activity:write | Consigner une entrée dans le journal d’activité des agents. |
spaces:manage | Créer, modifier et partager des espaces. En cours de déploiement : voir API Spaces. |
Aucun scope n’en implique un autre : brain:write n’accorde pas brain:read. Un credential sans le scope requis reçoit 403 insufficient_scope.
Clés développeur
Les clés se gèrent dans Orbit, page API (https://orbit.easyconnector.app/developers/api), dans le groupe Connexion de la barre latérale. Elle réunit l’URL de base, la carte Clés API, un test rapide, les appels récents et les erreurs.
Créer une clé. Choisissez Créer une clé API dans la carte Clés API : le formulaire s’ouvre en ligne, sous l’en-tête de la carte (il n’y a plus de fenêtre modale). Renseignez :
- Nom de la clé : 1 à 64 caractères, qui indique où la clé sera installée (« Production », « Claude Code », « CI »…).
- Accès : les scopes à cocher. Par défaut
brain:readseul ; accordez seulement ce dont l’intégration a besoin. - Espaces du Brain autorisés : tous les espaces que vous voyez sont cochés d’avance ; décochez ceux que la clé ne doit pas atteindre (32 au plus). Un compteur indique « n / total espaces sélectionnés ».
- Expiration : 30 jours, 90 jours (recommandé, présélectionné), 1 an ou jamais.
Choisissez Créer la clé : la carte « Votre clé est prête » remplace le formulaire et montre le secret, avec un bouton Copier la clé. Copiez-le avant de choisir Terminé : Orbit ne pourra pas l’afficher une seconde fois. La liste affiche ensuite chaque clé avec son nom, son préfixe, ses accès, son dernier usage et son statut (Active, Expirée, Révoquée).
- Qui peut les gérer : seul le rôle Propriétaire du compte (permission
developers.manage) peut lister, créer et révoquer des clés. Les autres membres voient la page sans les clés ni la création. - Scopes : cochés à la création ; les accès Studio et Artifact sont séparés, et
studio:generatedoit être accordé explicitement pour toute génération payante. - Espaces : la clé n’ouvre que les espaces cochés à la création : un espace créé ensuite n’y est pas ajouté, il demande une nouvelle clé. Une liste vide n’ouvre aucun espace. Les clés créées avant cette restriction restent valables pour tout le compte et sont marquées « Ancien accès à tout le compte » : remplacez-les par une nouvelle clé pour les restreindre.
- Format :
orb_suivi de 64 caractères hexadécimaux. Le secret complet n’est affiché qu’une seule fois, à la création ; Orbit n’en conserve qu’une empreinte et affiche ensuite un préfixe. - Révocation : immédiate, depuis la même page (Révoquer, avec une fenêtre de confirmation, car elle arrête toutes les intégrations qui utilisent la clé). Une clé révoquée ou expirée est refusée dès l’appel suivant.
- Membre : une clé agit pour le membre qui l’a créée, relu à chaque appel. Si ce membre a été révoqué ou a quitté le compte, la clé cesse de fonctionner aussitôt :
401 invalid_api_key, comme une clé révoquée. Le403 member_inactivereste le garde-fou des autres credentials dont le membre n’est plus actif. - Portée : une clé n’ouvre que les projets du compte qui l’a émise, et seulement ses espaces autorisés que son créateur peut voir (un espace privé d’un autre membre reste fermé). Elle est aussi acceptée par le serveur MCP, qui applique la même restriction par espace.
- Suivi : les appels faits avec une clé apparaissent dans la carte Appels récents de la même page.
Traitez une clé comme un mot de passe : variable d’environnement ou gestionnaire de secrets, jamais dans un dépôt ni dans du code exécuté par un navigateur. Pour connecter Claude, ChatGPT, Claude Code ou Cursor, préférez OAuth, sans clé : voir MCP.
Endpoints
| Méthode et chemin | Scope | Réponse |
|---|---|---|
GET /spaces | brain:read | les Spaces du compte et sa capacité |
GET /spaces/{id} | brain:read | un Space, ses vues legacy et son graphe utilisateur lorsqu’il est disponible |
GET /spaces/{id}/context | brain:read | contexte déterministe legacy borné |
POST /context | brain:read | Context Pack Memory/Segment par intention |
POST /alignment | brain:read | Alignment Check evidence-first + Context Pack |
GET /search | brain:read | recherche Memory legacy |
GET /quota | brain:read | quota mensuel de lectures |
GET /profile | brain:read | profil portable compact (un petit Context Pack) |
POST /spaces/{id}/memories | brain:write | Memory ajoutée (compatibilité) |
GET /spaces/{id}/nodes | brain:read | Nodes + Edges du graphe utilisateur |
POST /spaces/{id}/nodes | brain:write | crée un Node |
PATCH /nodes/{id} | brain:write | modifie un Node |
DELETE /nodes/{id} | brain:write | supprime uniquement le Node et ses liens |
POST /nodes/{id}/resources | brain:write | attache/détache Memory, Source, Fact ou Segment |
POST /node-edges | brain:write | crée/met à jour une Edge du même Space |
DELETE /node-edges/{id} | brain:write | supprime une Edge |
GET /proposals | brain:read | propositions d’un Space |
POST /proposals | brain:write | dépose une proposition en attente, sans rien appliquer |
POST /proposals/{id}/review | brain:write | refuse une proposition ; l’approbation se fait dans Orbit |
GET /skills | brain:read | Skills approuvées d’un espace, ou une Skill versionnée (bundle ou SKILL.md) |
GET /skills/{slug}/export | brain:read | une Skill approuvée en archive zip |
GET /skills/{slug}/diff | brain:read | fichiers ajoutés, retirés ou modifiés entre deux versions |
POST /skills/import | brain:write | dépose une Skill (SKILL.md) comme proposition en attente, sans rien publier |
POST /activity | activity:write | consigne une entrée dans le journal d’activité |
GET /activity | activity:read | lit le journal, de la plus récente à la plus ancienne |
GET /usage | brain:read | appels des applications OAuth sur 30 jours (clé du Propriétaire seulement) |
GET /projects | projects:read | projets Studio historiques du compte (ancien scope, compatibilité) |
POST /studio/generations | studio:generate | lance/rejoue une génération Studio ; Idempotency-Key obligatoire |
GET /studio/generations/{id} | studio:read | état/résultat d’une génération |
GET /artifacts/{id} | artifacts:read | Artifact durable et lineage |
POST /spaces | spaces:manage | crée un espace ; Idempotency-Key obligatoire. En cours de déploiement |
PATCH /spaces/{id} | spaces:manage | renomme, décrit ou change la visibilité d’un espace. En cours de déploiement |
GET /spaces/{id}/grants | spaces:manage | qui atteint un espace. En cours de déploiement |
PUT /spaces/{id}/grants | spaces:manage | donne l’accès à un espace. En cours de déploiement |
DELETE /spaces/{id}/grants | spaces:manage | retire cet accès. En cours de déploiement |
Les lectures de contenu GET /spaces/{id}, GET …/context, POST /context, GET /profile, POST /alignment et GET /search comptent dans le quota de lectures ; lister les espaces ou les projets, lire le quota, les propositions, les Skills ou le journal d’activité, et écrire n’en consomment pas. GET /spaces/{id} lit des corps de Memories et est paginé par limit (1 à 200, défaut 100) et offset. Un espace d’un autre compte, un espace privé d’un autre membre ou un espace hors de la liste autorisée du credential répond exactement comme un identifiant inconnu : 404 not_found. Les dates sont en ISO 8601 (UTC) ; les identifiants sont des chaînes opaques.
Les chemins legacy de Memory/contexte déterministe gardent encore les cinq rôles IDENTITY, GUIDELINES, KNOWLEDGE, ITEMS, PEOPLE pour compatibilité. Ne les utilisez pas pour modéliser une nouvelle intégration. Le graphe libre vit dans nodes/Edges, et le Context Pack récupère aussi des Segments sans pilier ni Memory artificielle. Voir Brain : espaces, Nodes et mémoires.
GET /spaces
curl https://orbit.easyconnector.app/api/v1/spaces \
-H "Authorization: Bearer $ORBIT_API_KEY"
{
"object": "list",
"data": [
{ "object": "space", "id": "…", "name": "Ma marque", "template": "brand", "templateLabel": "Marque", "memories": 12, "cu": 38 }
],
"capacity": { "usedCu": 38, "capacityCu": 120 }
}
template vaut brand, app, work, personal ou blank sur cette interface de compatibilité. Ces valeurs ne désignent pas des types de Space obligatoires et ne doivent pas structurer de nouvelles intégrations.
GET /spaces/{id}
Vue paginée : object: "space", id, name, champs de compatibilité template / templateLabel, websiteUrl, canEdit, pillars[] (role, label, icon, note, memories[], cu, quality), graph (nodes, edges), visibility, description, cu, quality et capacity. Passer limit (1 à 200, défaut 100) et offset (0 à 1 000 000, défaut 0) ; suivre page.nextOffset jusqu’à null (page.total annonce le nombre total de Memories). Le serveur peut écourter la page pour rester sous sa limite de caractères : ne pas supposer que limit éléments seront renvoyés. Les valeurs cu, quality et les tableaux de piliers de cette projection sont calculés à partir des Memories de la page, pas un total garanti de l’espace. Cette lecture consomme une unité du quota mensuel en cas de succès.
GET /spaces/{id}/context
curl "https://orbit.easyconnector.app/api/v1/spaces/$SPACE_ID/context?pillars=IDENTITY,GUIDELINES&maxChars=8000" \
-H "Authorization: Bearer $ORBIT_API_KEY"
| Paramètre | Rôle |
|---|---|
pillars | rôles séparés par des virgules (défaut : les cinq) |
maxChars | entier de 1 000 à 100 000, défaut 12 000 |
Réponse : object: "context", space, pillars[], context (le texte à injecter), maxChars, truncated, omittedMemories. Le texte ne dépasse jamais maxChars : les corps longs sont raccourcis équitablement, et si même les titres ne tiennent pas, les dernières mémoires sont omises avec une note.
POST /context
Construit un Context Pack pour une intention, sur un ou plusieurs Spaces autorisés.
curl -X POST "https://orbit.easyconnector.app/api/v1/context" \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task":"Prépare le lancement Orion","spaceIds":["space_…"],"asOf":"2030-02-01T00:00:00.000Z","maxChars":8000,"maxCu":40}'
Corps JSON :
| Champ | Rôle |
|---|---|
task | requis, chaîne de 1 à 8 000 caractères |
spaceIds | facultatif, liste de 32 Spaces au plus ; omis = tous les Spaces que ce credential peut lire |
asOf | facultatif, date/heure ISO pour une coupe historique |
maxChars | facultatif, 1 000 à 100 000 |
maxCu | facultatif, entier ≥ 1 ; budget de sélection, pas une facturation |
Le corps de POST /context est limité à 64 Kio. Réponse : object: "context_pack", identifiant/version du pack, requête normalisée, Spaces, fragments, contradictions, budget, état des retrievers et diagnostics.
Chaque fragment porte kind: "memory" | "segment" et peut porter memoryId ou segmentId, puis factIds, Evidence (sourceId, snapshotId, evidenceId, locator et rôle), confidence, validAt pour une coupe historique et whyIncluded.
Le retrieval produit des candidats Memory/Segment, fusionne leurs rangs par RRF pondérée, ajoute l’expansion bornée du graphe canonique et reranke un ensemble borné lorsque le provider est disponible. Un retriever optionnel indisponible ne provoque pas un fallback silencieux : retrieval et degraded rendent cet état visible.
POST /alignment
Vérifie le contexte pertinent avant une action ou un draft sans inventer une preuve d’alignement.
Corps : task requis ; action, draft, spaceIds, asOf et maxChars facultatifs.
La réponse object: "alignment_check" expose :
no_relevant_context / no_evidence_foundlorsqu’aucune preuve pertinente n’a été retrouvée ;review_required / review_context_before_proceedinglorsqu’un contexte pertinent doit être concilié ;- les signaux (
kernel_contradiction,constraint_candidate,relevant_context) ; - le Context Pack exact utilisé.
no_evidence_found ne signifie jamais « action autorisée » ou « alignée ».
Graphe utilisateur
GET /spaces/{id}/nodes rend {object:"brain_graph", spaceId, nodes, edges}.
Un Node est une collection/vue utilisateur et peut référencer plusieurs Memories, Sources, Facts et Segments. Les routes d’écriture vérifient que Node, Edge et ressource restent dans le même Space du compte. Supprimer un Node ne supprime jamais la connaissance qu’il organisait.
GET /search
curl "https://orbit.easyconnector.app/api/v1/search?q=livraison&limit=5" \
-H "Authorization: Bearer $ORBIT_API_KEY"
| Paramètre | Rôle |
|---|---|
q | requis, 200 caractères au plus |
spaceId | seulement cet espace |
pillar | seulement ce rôle de pilier |
limit | entier de 1 à 50, défaut 10 |
Réponse : object: "list", query, data[] d’objets search_hit (spaceId, spaceName, memoryId, pillar, pillarLabel, title, snippet, source, score, updatedAt), meilleurs d’abord.
POST /spaces/{id}/memories
curl -X POST "https://orbit.easyconnector.app/api/v1/spaces/$SPACE_ID/memories" \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: commande-1234-note" \
-d '{"pillar":"KNOWLEDGE","title":"Livraison","body":"48 h en France métropolitaine."}'
- Corps JSON :
pillar,title(1 à 120 caractères),body(20 000 caractères au plus),kind(facultatif, 1 à 40 caractères, défautnote),parentId(facultatif, une mémoire du même espace). Aucun autre champ n’est accepté. - En-tête
Idempotency-Keyobligatoire (1 à 200 caractères ASCII visibles). Même clé et même contenu :200avec la même mémoire et l’en-têteIdempotent-Replayed: true. Même clé et autre contenu :409 idempotency_conflict, rien n’est écrit. - Réponse
201:object: "memory",id,spaceId,pillar,parentId,kind,title,body,source: "API",createdAt,updatedAt. - La mémoire compte dans la capacité du compte. Un Brain plein répond
402 capacity_fullet rien n’est écrit.
Propositions et Skills
GET /profile rend { object: "portable_profile", pack } : un petit Context Pack (3 000 caractères, 20 CU de sélection au plus) centré sur l’identité, les préférences, les directives approuvées et les interdits. Paramètre spaceId répétable (32 au plus) ; omis, tous les espaces que ce credential peut lire. Compte pour une lecture.
POST /proposals (corps JSON de 32 Kio au plus) dépose une proposition en attente : spaceId, operation (create_memory, correct_memory, remove_memory, publish_skill, archive_skill), title (160 caractères), body (20 000), description (1 024, facultatif), targetId (la Memory à corriger ou retirer), pillar et skillSlug facultatifs, idempotencyKey (8 à 160 caractères) obligatoire dans le corps. Réponse 201 : { object: "brain_proposal", proposal, applied: false, requiresExplicitReview: true }. Une proposition ne modifie rien tant qu’elle n’est pas approuvée.
GET /proposals?spaceId=…&status=PENDING|APPLIED|REJECTED|ALL liste les propositions d’un espace (PENDING par défaut). Un membre sans droit d’écriture ne voit que les siennes.
POST /proposals/{id}/review (corps { "decision": "approve" | "reject", "confirmed": true }) : seul un refus est possible par l’API. Une approbation répond 403 approvalRequiresOrbit : le membre approuve dans Orbit, page Propositions à valider (/brain/review). Sans confirmed: true, 400 explicit_confirmation_required.
GET /skills?spaceId=… liste les Skills approuvées et actives d’un espace ; avec slug (et version facultative), rend une Skill versionnée (object: "brain_skill"). format=bundle (défaut) rend son en-tête, un manifeste (chemins, tailles, empreintes sha256) et tous ses fichiers ; format=skill_md rend le seul SKILL.md (toute autre valeur : 400 format_invalid). GET /skills/{slug}/export?spaceId=…&version=… rend une version en archive zip (<slug>/SKILL.md, et references/, scripts/ si la Skill en porte), en texte, sans rien d’exécutable : Orbit n’exécute jamais un script. GET /skills/{slug}/diff?spaceId=…&from=…&to=… liste les fichiers ajoutés, retirés ou modifiés entre deux versions (to : la dernière par défaut).
POST /skills/import (corps { spaceId, markdown, files?, idempotencyKey }, idempotencyKey de 8 à 160 caractères) est l’équivalent REST de brain_import_skill : il contrôle le SKILL.md (64 Kio au plus, contrôlé contre les secrets) et dépose une proposition publish_skill en attente ; réponse 201 (200 en rejeu) { object: "brain_proposal", proposal, manifest, applied: false, requiresExplicitReview: true }. Rien n’est publié, installé ni exécuté : l’approbation se fait dans Orbit. L’import de fichiers d’accompagnement est en cours de déploiement : tant qu’il n’est pas ouvert, un import avec files répond 403 bundles_disabled. Un fichier ou un SKILL.md trop gros répond 413 (skill_md_too_large, file_too_large, bundle_too_large).
GET /usage rend, pour les 30 derniers jours, le nombre d’appels de chaque application OAuth du compte (réussis, refusés, par opération). Il exige une clé orb_… créée par le Propriétaire : un jeton OAuth ou une autre clé reçoit 403 not_allowed. Aucun prompt, argument ni contenu n’est enregistré.
Journal d’activité
Le journal d’activité des agents est un registre en ajout seul, pas une mémoire : une entrée n’est jamais modifiée et n’entre jamais dans un Context Pack. Entrées gardées 180 jours. Mêmes règles que les tools MCP brain_log_activity et brain_list_activity ; aucun des deux appels n’est compté dans les lectures incluses. Les entrées se lisent aussi dans Orbit, page Brain → Activité des agents.
POST /activity (scope activity:write, corps JSON de 16 Kio au plus) :
curl -X POST https://orbit.easyconnector.app/api/v1/activity \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent":"claude-code","kind":"DEPLOY","summary":"Déploie le site vitrine en production.","spaceId":"space_…","repo":"acme/site","branch":"main","links":["https://github.com/acme/site/actions/runs/123"],"status":"DONE"}'
| Champ | Rôle |
|---|---|
agent | requis, 1 à 64 caractères (claude-code, claude-desktop, codex…) |
kind | requis : SESSION, TASK, PR, DEPLOY ou NOTE |
summary | requis, 1 à 4 000 caractères, factuel |
spaceId | facultatif, mais obligatoire pour un credential limité à certains espaces (sinon 400 space_required) |
host, repo, branch | facultatifs, 64 / 200 / 200 caractères au plus |
links | facultatif, 10 URL http(s) au plus, sans identifiants |
status | DONE (défaut), IN_PROGRESS, BLOCKED ou FAILED |
occurredAt | facultatif, date/heure ISO ; défaut maintenant, pas plus ancienne que 180 jours, pas dans le futur |
Réponse 201 : { object: "activity", activity } (id, spaceId, agent, host, repo, branch, kind, summary, links, status, occurredAt, createdAt, principal). Un secret dans un champ ou un lien est refusé : 422 secret_refused, rien n’est écrit. Le journal a son propre plafond, 30 entrées par minute et 1 000 par jour et par credential : au-delà, 429 rate_limited avec Retry-After. Le membre derrière le credential doit pouvoir écrire dans le Brain (sinon 403 forbidden).
GET /activity?spaceId=&agent=&repo=&kind=&since=&until=&limit=&cursor= (scope activity:read) rend { object: "list", data: [ { object: "activity", … } ], nextCursor }, de la plus récente à la plus ancienne. limit : 1 à 100, défaut 20 ; passez nextCursor en cursor pour la page suivante (null sur la dernière). Un credential limité à certains espaces ne voit que les entrées de ces espaces. Un cursor invalide ou since après until répond 400 invalid_request.
API Spaces
En cours de déploiement. L’API Spaces n’est pas encore ouverte par défaut. Tant qu’elle ne l’est pas, ses routes répondent 404 not_found comme un chemin qui n’existe pas, et le scope spaces:manage n’est pas annoncé. Les tools MCP équivalents suivent la même règle.
Quand elle est ouverte, elle permet de créer des espaces et de changer qui les atteint, avec le scope spaces:manage (jamais accordé par défaut). Les corps JSON ne portent que les champs listés (tout autre champ est refusé en 400 invalid_request).
POST /spaces(16 Kio au plus) :{ name, template?, description?, visibility? }.name: 1 à 60 caractères ;template:brand,app,work,personaloublank(défaut) ;description: 500 caractères au plus ;visibility:WORKSPACE(tous les membres du compte) ouPRIVATE(son créateur et les membres avec qui il est partagé). L’en-têteIdempotency-Keyest obligatoire : même clé et même corps rendent le premier espace (200,Idempotent-Replayed: true) ; même clé et autre corps,409 idempotency_conflict. Réponse201:{ object: "space", id, name, description, template, visibility, ownerId, createdAt, updatedAt, credentialAccess }. Un credential limité à certains espaces reçoit le nouvel espace dans sa liste (credentialAccess: "added").PATCH /spaces/{id}(16 Kio au plus) : au moins un dename,description(nulll’efface),visibility. Renommer ou décrire exige l’accès en écriture à l’espace ; changer la visibilité, être le membre qui l’a créé. Un espace lié à un projet partagé ne peut pas devenirPRIVATE(409 bound_to_studio). Idempotent : la même modification répondchanged: false.GET /spaces/{id}/grants:{ object: "space_grants", space, everyMember, members, apiKeys, oauthClients }. Aucun secret n’est rendu.PUT /spaces/{id}/grants(4 Kio au plus) :{ principalType, principalId, memberId?, canWrite? }.principalTypevautmember(membre d’un espacePRIVATE;canWritepour l’écriture),api_key(l’id de la clé : l’espace rejoint sa liste) ouoauth_client(leclient_idd’une application connectée : l’espace rejoint la liste de chacune de ses autorisations dans le compte, ou de celles du seulmemberId). Réponse{ object: "space_grant", spaceId, principal, changed, access, … }; la même requête répondchanged: false.DELETE /spaces/{id}/grants: mêmes champs en corps JSON ou en paramètres de requête, sanscanWrite. Réponse{ object: "space_grant_revoked", … }, effective à l’appel suivant du credential concerné. Un credential ouvert à tout le compte devient une liste explicite de tous les autres espaces (converted).
Lister, donner ou retirer un accès est réservé au Propriétaire du compte, relu en base à chaque appel ; un espace PRIVATE n’est géré que par son créateur. Un accès donné ne dépasse jamais celui de l’appelant (403 grant_exceeds_caller). Les erreurs ont la même forme que les autres ({ error: { code, message } }) ; leurs codes sont dans le tableau des erreurs.
Studio headless
POST /studio/generations accepte { projectId, spec, mentions? } et exige l’en-tête Idempotency-Key. projectId est l’identifiant d’un projet, ou null pour créer sans projet (une création propre au membre, comme dans le composer de /studio). mentions est le contexte que la génération peut lire : huit références { type, id } au plus, type parmi space, memory, node, source, url, project, character et reference. Pour les générations compatibles, les citations de contexte explicites sont prioritaires ; en leur absence et avec un projet, un extrait d’au plus trois espaces partagés avec le compte, explicitement liés et encore autorisés, peut être lu. Les espaces privés sont exclus de cette sélection automatique. Sans projet ni citation de contexte, aucun contexte du Brain n’est ajouté ; chaque mention est autorisée de nouveau au moment de la génération, et une référence inconnue, d’un autre compte ou interdite refuse toute la demande. Une url citée n’est pas téléchargée. Voir Citer son contexte. Le serveur applique les mêmes règles de coûts, crédits, références et providers que le composer de Studio, et enregistre lui-même la trace des droits (qui, quand, quelles entrées, quelle version des conditions) : aucun champ d’attestation n’est à envoyer.
Une génération synchrone peut répondre 201; un job asynchrone peut répondre 202. Une replay idempotente répond 200 avec Idempotent-Replayed: true.
GET /studio/generations/{id} rend l’état courant et peut finaliser un job vidéo asynchrone lorsque le provider a terminé.
GET /artifacts/{id} rend l’Artifact durable autorisé. Un Artifact de projet est partagé au niveau du compte ; un Artifact créé sans projet reste limité au membre qui l’a créé.
GET /projects
Liste les projets Studio enregistrés du compte, du plus ancien au plus récent, chacun avec les identifiants des espaces du même compte auquel il est lié (spaceIds, vide s’il n’en lit aucun). Pas de paramètre ni de pagination.
{
"object": "list",
"data": [
{
"id": "…",
"object": "project",
"name": "Ma marque",
"websiteUrl": "https://example.com",
"spaceIds": ["…"],
"createdAt": "2026-09-01T10:00:00.000Z",
"updatedAt": "2026-09-15T08:30:00.000Z"
}
]
}
websiteUrl peut valoir null.
Quota de lectures incluses
Votre abonnement inclut un nombre de lectures de contenu par mois (UTC), proportionnel à la capacité du Brain : 3 000 lectures par tranche de 120 CU (4 500 à 180 CU). Ce quota est partagé entre l’API et le serveur MCP : GET /spaces/{id}, GET /spaces/{id}/context, POST /context, GET /profile, POST /alignment, GET /search et les tools brain_get_profile, brain_get_context, brain_get_context_pack, brain_check_alignment, brain_search comptent chacun pour une lecture. Rien n’est facturé à l’usage : il n’y a ni dépassement payant ni facture surprise.
Les réponses des endpoints de lecture de contenu portent l’état du quota, et GET /quota le rend sans rien consommer :
| En-tête | Valeur |
|---|---|
X-Orbit-Quota-Limit | lectures incluses ce mois-ci |
X-Orbit-Quota-Remaining | lectures restantes |
Une lecture qui échoue (espace inconnu, paramètre invalide) est rendue : seule une lecture qui a renvoyé un résultat est comptée. Le quota se renouvelle au début de chaque mois UTC.
GET /quota
Où en est le compte, sans compter pour une lecture (scope brain:read) : appelez-le avant une longue série de lectures. Mêmes chiffres que l’outil MCP brain_quota et que la carte « Lectures incluses » de la page Développeurs.
curl https://orbit.easyconnector.app/api/v1/quota \
-H "Authorization: Bearer $ORBIT_API_KEY"
{
"object": "quota",
"limit": 3000,
"used": 412,
"remaining": 2588,
"resetsAt": "2026-11-01T00:00:00.000Z",
"activated": true,
"storage": {
"usedBytes": 12400000000,
"includedBytes": 50000000000,
"addonBlocks": 0,
"addonBytes": 0,
"quotaBytes": 50000000000,
"brainBytes": 9100000000,
"studioBytes": 3500000000,
"state": "ok",
"graceEndsAt": null
}
}
limit est la limite du mois (0 tant qu’Orbit n’est pas activé, sauf quota fixé par contrat), resetsAt le début du mois UTC suivant, activated vaut true quand le compte a une capacité.
storage donne le stockage du compte (voir Stockage), en octets (1 Go = 10⁹ octets) : usedBytes (fichiers originaux comptés, chacun une fois), includedBytes (inclus avec l’offre), addonBlocks et addonBytes (blocs de +100 Go ajoutés), quotaBytes (le total permis), brainBytes et studioBytes (par surface ; un fichier présent dans les deux compte une fois dans chacune, la somme peut donc dépasser usedBytes), state (ok, warning à 80 %, grace au-delà du quota pendant 14 jours, waiting ensuite : un nouveau fichier du Brain attend, un envoi Studio est refusé) et graceEndsAt (date ISO de fin de la grâce, null sous le quota). Au-delà du quota, rien n’est supprimé ni bloqué en lecture.
- Quota épuisé :
402 quota_exceeded. Le message donne la date du renouvellement ; pour l’augmenter, ajoutez des pas de +60 CU à votre abonnement depuis la page de facturation. - Orbit pas encore activé sur le compte (aucune lecture incluse) :
402 activation_required. Le Propriétaire active Orbit depuis/brain, à l’envoi de la première source.
Un compte aux conditions négociées (custom) peut avoir un quota fixé par contrat.
Limites de débit
120 requêtes par minute et par credential. Chaque réponse authentifiée porte l’en-tête X-RateLimit-Remaining. Au-delà, l’API répond 429 avec l’en-tête Retry-After (en secondes). L’écriture dans le journal d’activité a en plus son propre plafond : 30 entrées par minute et 1 000 par jour et par credential.
Chaque route applique son propre plafond au corps JSON. 128 Kio n’est pas une limite universelle.
| Opération | Corps maximal |
|---|---|
POST /context, POST /alignment | 64 Kio chacun |
POST /spaces/{id}/nodes, PATCH /nodes/{id}, POST /proposals | 32 Kio chacun |
POST /node-edges, POST /activity | 16 Kio chacun |
POST /spaces, PATCH /spaces/{id} (en cours de déploiement) | 16 Kio chacun |
PUT et DELETE /spaces/{id}/grants (en cours de déploiement) | 4 Kio chacun |
POST /skills/import | 96 Kio (2 Mio si l’import de fichiers est ouvert) |
POST /nodes/{id}/resources, POST /proposals/{id}/review | 8 Kio chacun |
POST /spaces/{id}/memories, POST /studio/generations | 128 Kio chacun |
Si le corps dépasse son plafond, la route répond 413 payload_too_large (413 invalid_request pour les routes de propositions). Les validations métier (longueurs de champs, identifiants, schémas, etc.) sont indépendantes de ces limites en octets.
Erreurs
Les erreurs de l’API REST ont toutes la même forme ; le code est stable et en minuscules, le message est destiné aux humains, rédigé en anglais, et peut changer.
{ "error": { "code": "idempotency_key_required", "message": "The Idempotency-Key header is required." } }
| HTTP | code | Cas |
|---|---|---|
400 | invalid_json, invalid_request, invalid_params, idempotency_key_required, idempotency_key_invalid, pillar_invalid, title_invalid, body_invalid, kind_invalid, parent_invalid, max_chars_invalid, query_invalid, limit_invalid, task_invalid, space_ids_invalid, as_of_invalid, max_cu_invalid, space_required, version_invalid, format_invalid, explicit_confirmation_required, invalid | paramètre, en-tête ou corps invalide |
400 | name_invalid, description_invalid, template_invalid, visibility_invalid, principal_invalid, can_write_invalid | corps invalide pour l’API Spaces (en cours de déploiement) |
401 | invalid_api_key | en-tête Authorization absent, clé ou jeton mal formé, inconnu, expiré ou révoqué |
402 | quota_exceeded | les lectures incluses du mois sont épuisées ; voir X-Orbit-Quota-* |
402 | activation_required | Orbit n’est pas encore activé sur le compte : aucune lecture incluse, et rien n’a été écrit pour une écriture |
402 | capacity_full | la capacité du Brain du compte est pleine ; rien n’a été écrit |
403 | insufficient_scope | le credential n’a pas le scope requis ; voir l’en-tête WWW-Authenticate |
403 | member_inactive | le membre derrière un credential autre qu’une clé (jeton OAuth) n’est plus actif dans le compte |
403 | forbidden, notAllowed | ce membre ne peut pas écrire dans le Brain |
403 | approvalRequiresOrbit | une proposition ne s’approuve que dans Orbit (/brain/review) |
403 | not_allowed | GET /usage appelé sans clé du Propriétaire |
403 | bundles_disabled | POST /skills/import avec des fichiers d’accompagnement, tant que leur import n’est pas ouvert |
403 | not_space_owner, grant_exceeds_caller | API Spaces : seul le créateur gère la visibilité et l’accès d’un espace PRIVATE ; un accès ne dépasse jamais celui de l’appelant |
404 | not_found, notFound, no_space | espace inconnu, d’un autre compte, privé ou hors de la liste du credential ; proposition ou Skill introuvable ; route de l’API Spaces non ouverte ; ou aucun espace lisible pour construire un Context Pack |
404 | principal_not_found | API Spaces : membre, clé ou application inconnus pour ce compte |
409 | idempotency_conflict, idempotencyConflict | cette clé d’idempotence a déjà servi pour un contenu différent |
409 | alreadyReviewed, inProgress, writeFailed | la proposition a déjà été traitée, est en cours de traitement ou n’a pas pu être appliquée |
409 | spaces_limit, bound_to_studio, principal_is_owner, space_not_private, principal_lacks_access | API Spaces : 25 espaces par compte au plus, espace lié à un projet partagé, accès du créateur, membre sur un espace non privé, membre qui ne voit pas l’espace |
413 | payload_too_large, skill_md_too_large, file_too_large, bundle_too_large | corps ou Skill trop volumineux |
422 | secret_refused | une entrée du journal d’activité semble contenir un secret ; rien n’est écrit |
429 | rate_limited | limite de débit dépassée ; voir Retry-After |
Un refus de scope suit la RFC 6750 :
WWW-Authenticate: Bearer realm="Orbit API", error="insufficient_scope", scope="brain:write", resource_metadata="https://orbit.easyconnector.app/.well-known/oauth-protected-resource"
Réagissez au code, jamais au texte du message.
CORS
Les réponses portent Access-Control-Allow-Origin: *, autorisent les en-têtes authorization, content-type et idempotency-key, exposent WWW-Authenticate, Idempotent-Replayed, X-RateLimit-* et X-Orbit-Quota-*, et envoient Cache-Control: no-store. Le pré-vol OPTIONS répond 204 (cache 24 h). L’ouverture CORS ne rend pas l’usage d’une clé côté navigateur sûr : appelez l’API depuis un serveur.
Versioning
Le préfixe /v1 est la version majeure en service. /v1 n’évolue que par ajouts (nouveaux champs, nouveaux endpoints) ; un changement incompatible passera par une nouvelle version majeure. Votre client doit donc ignorer les champs qu’il ne connaît pas.
Disponibilité
Sont exposés par défaut tous les endpoints ci-dessus, sauf ceux marqués « en cours de déploiement » : l’API Spaces (spaces:manage) et l’import de fichiers d’accompagnement d’une Skill, qui ne sont pas encore ouverts par défaut. La pagination générale et l’archivage ou la suppression protégés de la connaissance (au-delà de la proposition de retrait d’une Memory) ne sont pas exposés par l’API.
Pour connecter un client ou un agent compatible, voyez MCP.