DéveloppeursAPI

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 basehttps://orbit.easyconnector.app/api/v1
AuthentificationAuthorization: Bearer … : clé orb_… ou jeton d’accès OAuth Orbit
Scopes proposésbrain: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à
FormatJSON
Référencecette 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.
ScopeCe qu’il permet
brain:readLister/lire les espaces (Space), construire Context Packs, profil et Alignment Checks, chercher, lire le graphe utilisateur, les propositions et les Skills.
brain:writeAjouter des Memories de compatibilité, créer/éditer/relier les Nodes d’organisation, déposer ou refuser des propositions.
projects:readAncien scope (« Anciens projets Studio ») : lire les fiches de projets historiques via GET /projects. Il n’est plus proposé à une nouvelle clé.
studio:readLire l’état d’une génération Studio.
studio:generateLancer une génération ou une révision Studio payante via le ledger Orbit.
artifacts:readLire un Artifact Studio durable autorisé.
activity:readLire le journal d’activité des agents.
activity:writeConsigner une entrée dans le journal d’activité des agents.
spaces:manageCré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 :

  1. Nom de la clé : 1 à 64 caractères, qui indique où la clé sera installée (« Production », « Claude Code », « CI »…).
  2. Accès : les scopes à cocher. Par défaut brain:read seul ; accordez seulement ce dont l’intégration a besoin.
  3. 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 ».
  4. 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:generate doit ê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. Le 403 member_inactive reste 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 cheminScopeRéponse
GET /spacesbrain:readles Spaces du compte et sa capacité
GET /spaces/{id}brain:readun Space, ses vues legacy et son graphe utilisateur lorsqu’il est disponible
GET /spaces/{id}/contextbrain:readcontexte déterministe legacy borné
POST /contextbrain:readContext Pack Memory/Segment par intention
POST /alignmentbrain:readAlignment Check evidence-first + Context Pack
GET /searchbrain:readrecherche Memory legacy
GET /quotabrain:readquota mensuel de lectures
GET /profilebrain:readprofil portable compact (un petit Context Pack)
POST /spaces/{id}/memoriesbrain:writeMemory ajoutée (compatibilité)
GET /spaces/{id}/nodesbrain:readNodes + Edges du graphe utilisateur
POST /spaces/{id}/nodesbrain:writecrée un Node
PATCH /nodes/{id}brain:writemodifie un Node
DELETE /nodes/{id}brain:writesupprime uniquement le Node et ses liens
POST /nodes/{id}/resourcesbrain:writeattache/détache Memory, Source, Fact ou Segment
POST /node-edgesbrain:writecrée/met à jour une Edge du même Space
DELETE /node-edges/{id}brain:writesupprime une Edge
GET /proposalsbrain:readpropositions d’un Space
POST /proposalsbrain:writedépose une proposition en attente, sans rien appliquer
POST /proposals/{id}/reviewbrain:writerefuse une proposition ; l’approbation se fait dans Orbit
GET /skillsbrain:readSkills approuvées d’un espace, ou une Skill versionnée (bundle ou SKILL.md)
GET /skills/{slug}/exportbrain:readune Skill approuvée en archive zip
GET /skills/{slug}/diffbrain:readfichiers ajoutés, retirés ou modifiés entre deux versions
POST /skills/importbrain:writedépose une Skill (SKILL.md) comme proposition en attente, sans rien publier
POST /activityactivity:writeconsigne une entrée dans le journal d’activité
GET /activityactivity:readlit le journal, de la plus récente à la plus ancienne
GET /usagebrain:readappels des applications OAuth sur 30 jours (clé du Propriétaire seulement)
GET /projectsprojects:readprojets Studio historiques du compte (ancien scope, compatibilité)
POST /studio/generationsstudio:generatelance/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:readArtifact durable et lineage
POST /spacesspaces:managecrée un espace ; Idempotency-Key obligatoire. En cours de déploiement
PATCH /spaces/{id}spaces:managerenomme, décrit ou change la visibilité d’un espace. En cours de déploiement
GET /spaces/{id}/grantsspaces:managequi atteint un espace. En cours de déploiement
PUT /spaces/{id}/grantsspaces:managedonne l’accès à un espace. En cours de déploiement
DELETE /spaces/{id}/grantsspaces:manageretire 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ètreRôle
pillarsrôles séparés par des virgules (défaut : les cinq)
maxCharsentier 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 :

ChampRôle
taskrequis, chaîne de 1 à 8 000 caractères
spaceIdsfacultatif, liste de 32 Spaces au plus ; omis = tous les Spaces que ce credential peut lire
asOffacultatif, date/heure ISO pour une coupe historique
maxCharsfacultatif, 1 000 à 100 000
maxCufacultatif, 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_found lorsqu’aucune preuve pertinente n’a été retrouvée ;
  • review_required / review_context_before_proceeding lorsqu’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.

curl "https://orbit.easyconnector.app/api/v1/search?q=livraison&limit=5" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
ParamètreRôle
qrequis, 200 caractères au plus
spaceIdseulement cet espace
pillarseulement ce rôle de pilier
limitentier 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éfaut note), parentId (facultatif, une mémoire du même espace). Aucun autre champ n’est accepté.
  • En-tête Idempotency-Key obligatoire (1 à 200 caractères ASCII visibles). Même clé et même contenu : 200 avec la même mémoire et l’en-tête Idempotent-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_full et 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"}'
ChampRôle
agentrequis, 1 à 64 caractères (claude-code, claude-desktop, codex…)
kindrequis : SESSION, TASK, PR, DEPLOY ou NOTE
summaryrequis, 1 à 4 000 caractères, factuel
spaceIdfacultatif, mais obligatoire pour un credential limité à certains espaces (sinon 400 space_required)
host, repo, branchfacultatifs, 64 / 200 / 200 caractères au plus
linksfacultatif, 10 URL http(s) au plus, sans identifiants
statusDONE (défaut), IN_PROGRESS, BLOCKED ou FAILED
occurredAtfacultatif, 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, personal ou blank (défaut) ; description : 500 caractères au plus ; visibility : WORKSPACE (tous les membres du compte) ou PRIVATE (son créateur et les membres avec qui il est partagé). L’en-tête Idempotency-Key est 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éponse 201 : { 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 de name, description (null l’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 devenir PRIVATE (409 bound_to_studio). Idempotent : la même modification répond changed: 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? }. principalType vaut member (membre d’un espace PRIVATE ; canWrite pour l’écriture), api_key (l’id de la clé : l’espace rejoint sa liste) ou oauth_client (le client_id d’une application connectée : l’espace rejoint la liste de chacune de ses autorisations dans le compte, ou de celles du seul memberId). Réponse { object: "space_grant", spaceId, principal, changed, access, … } ; la même requête répond changed: false.
  • DELETE /spaces/{id}/grants : mêmes champs en corps JSON ou en paramètres de requête, sans canWrite. 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êteValeur
X-Orbit-Quota-Limitlectures incluses ce mois-ci
X-Orbit-Quota-Remaininglectures 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érationCorps maximal
POST /context, POST /alignment64 Kio chacun
POST /spaces/{id}/nodes, PATCH /nodes/{id}, POST /proposals32 Kio chacun
POST /node-edges, POST /activity16 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/import96 Kio (2 Mio si l’import de fichiers est ouvert)
POST /nodes/{id}/resources, POST /proposals/{id}/review8 Kio chacun
POST /spaces/{id}/memories, POST /studio/generations128 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." } }
HTTPcodeCas
400invalid_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, invalidparamètre, en-tête ou corps invalide
400name_invalid, description_invalid, template_invalid, visibility_invalid, principal_invalid, can_write_invalidcorps invalide pour l’API Spaces (en cours de déploiement)
401invalid_api_keyen-tête Authorization absent, clé ou jeton mal formé, inconnu, expiré ou révoqué
402quota_exceededles lectures incluses du mois sont épuisées ; voir X-Orbit-Quota-*
402activation_requiredOrbit n’est pas encore activé sur le compte : aucune lecture incluse, et rien n’a été écrit pour une écriture
402capacity_fullla capacité du Brain du compte est pleine ; rien n’a été écrit
403insufficient_scopele credential n’a pas le scope requis ; voir l’en-tête WWW-Authenticate
403member_inactivele membre derrière un credential autre qu’une clé (jeton OAuth) n’est plus actif dans le compte
403forbidden, notAllowedce membre ne peut pas écrire dans le Brain
403approvalRequiresOrbitune proposition ne s’approuve que dans Orbit (/brain/review)
403not_allowedGET /usage appelé sans clé du Propriétaire
403bundles_disabledPOST /skills/import avec des fichiers d’accompagnement, tant que leur import n’est pas ouvert
403not_space_owner, grant_exceeds_callerAPI 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
404not_found, notFound, no_spaceespace 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
404principal_not_foundAPI Spaces : membre, clé ou application inconnus pour ce compte
409idempotency_conflict, idempotencyConflictcette clé d’idempotence a déjà servi pour un contenu différent
409alreadyReviewed, inProgress, writeFailedla proposition a déjà été traitée, est en cours de traitement ou n’a pas pu être appliquée
409spaces_limit, bound_to_studio, principal_is_owner, space_not_private, principal_lacks_accessAPI 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
413payload_too_large, skill_md_too_large, file_too_large, bundle_too_largecorps ou Skill trop volumineux
422secret_refusedune entrée du journal d’activité semble contenir un secret ; rien n’est écrit
429rate_limitedlimite 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.