Documentation/API/Vue d’ensemble

OrbitWake API

Vue d’ensemble

OrbitWake expose aujourd’hui plusieurs routes HTTP utilisées par le produit web, l’extension VS Code, les intégrations et certaines surfaces publiques. Il ne s’agit pas encore d’une API développeur publique versionnée avec clé API, SDK officiel ou contrat OpenAPI stable.

Statut actuel

Les routes sont servies sous le domaine principal OrbitWake :

https://orbitwake.com/api/...

La plupart des endpoints authentifiés sont conçus pour les clients OrbitWake officiels et reposent sur la session web du compte.

Pas encore une API publique stableNe considérez pas les routes internes du produit comme un contrat externe garanti. Les chemins, schémas et comportements peuvent évoluer tant qu’une API développeur versionnée n’est pas publiée.

Quatre surfaces API distinctes

Surface	Authentification	Usage
API produit web	Cookie de session OrbitWake.	AI, conversations, mémoire, projets, connecteurs, média et autres fonctions du workspace.
API IDE	Bearer token IDE dédié.	Pairing, Ask, Agent et sessions VS Code.
Routes publiques	Aucune session requise selon le endpoint.	Recherche de domaine, catalogue hosting, configuration publique de paiement, health.
Routes internes / webhooks	Secrets spécifiques.	Administration privée et callbacks fournisseurs.

API produit : session web

La majorité des routes produit authentifiées appellent getCurrentUser().

Cette fonction lit le cookie HttpOnly :

orbitwake_session

Le token de session est hashé côté serveur et la session doit être non expirée. La durée créée par l’authentification actuelle est de 30 jours.

Ces endpoints ne lisent pas aujourd’hui une clé API développeur standard dans Authorization: Bearer ....

Pas de clé API développeur publique aujourd’hui

Le repo actuel ne contient pas de flux public de création de clés API utilisateur, de schéma OpenAPI/Swagger ni de SDK API versionné.

Le Bearer token observé dans certaines routes ne doit pas être généralisé :

l’API IDE utilise un token de session IDE dédié ;
une route admin interne utilise un token serveur privé ;
les webhooks fournisseurs utilisent leurs propres secrets.

Aucun de ces secrets ne constitue une clé API publique destinée aux développeurs externes.

Endpoints AI du produit

Les principales routes AI actuelles sont :

Méthode	Route	Rôle
POST	`/api/ai/generate`	Réponse AI JSON non streamée.
POST	`/api/ai/stream`	Réponse AI en Server-Sent Events.
GET	`/api/ai/models`	Liste des modèles disponibles.
GET	`/api/ai/providers`	Résumé runtime/provider pour comptes autorisés.
GET	`/api/ai/conversations`	Liste récente des conversations.
GET / DELETE	`/api/ai/conversations/:id`	Lire ou archiver une conversation.

Ces routes exigent une session web valide et l’éligibilité OrbitWake AI du compte.

Entrée AI actuelle

/api/ai/generate et /api/ai/stream acceptent notamment :

model — par défaut orbitwake-auto ;
mode — general, research, build ou analyze ;
messages — rôles user et assistant ;
conversationId optionnel ;
maxOutputTokens borné par la policy serveur.

Les messages system fournis par le client sont refusés : OrbitWake gère les instructions système côté serveur.

Pièces jointes AI

Les messages utilisateur peuvent actuellement contenir jusqu’à trois pièces jointes par message.

Types supportés :

application/pdf
image/png
image/jpeg
image/webp
image/gif

Chaque fichier est limité à 8 MB et l’ensemble des pièces jointes présentes dans le contexte est limité à 12 MB.

Streaming SSE

POST /api/ai/stream retourne :

Content-Type: text/event-stream; charset=utf-8

Le flux peut émettre quatre familles d’événements :

Événement	Rôle
`activity`	Étapes d’exécution visibles.
`delta`	Fragment de texte streamé.
`done`	Métadonnées finales, conversation, modèle et usage.
`error`	Erreur survenue après ouverture du flux.

Projects API

La surface Projects privée beta utilise aussi la session web OrbitWake.

Exemples :

GET    /api/projects
POST   /api/projects
GET    /api/projects/:projectId
PATCH  /api/projects/:projectId
DELETE /api/projects/:projectId

Le DELETE actuel archive le projet plutôt que de promettre une suppression physique immédiate.

Memory API

La mémoire utilisateur possède ses propres routes authentifiées :

GET  /api/memory
POST /api/memory
GET  /api/memory/settings
PATCH /api/memory/settings

Les scopes de mémoire actuellement reconnus sont personal, workspace et project.

Les catégories actuelles sont preference, decision, fact, instruction et context.

Connectors API

Les routes Connectors sont authentifiées avec la session web et incluent notamment :

GET  /api/connectors/tools
GET  /api/connectors/activity
POST /api/connectors/execute
POST /api/connectors/approvals/:id

L’exécution peut retourner 202 lorsqu’une approbation est nécessaire. Les actions GitHub réelles suivent la politique read/write/sensitive documentée dans la section Connectors.

API IDE

L’extension VS Code n’utilise pas le cookie navigateur pour Ask et Agent. Elle utilise un token IDE dédié.

Routes principales :

POST /api/ide/pairing
POST /api/ide/pairing/claim
POST /api/ide/generate
POST /api/ide/patch
GET  /api/ide/sessions
DELETE /api/ide/sessions/:sessionId

Le pairing est créé depuis une session web authentifiée ; le claim transforme le code à usage unique en session IDE. Ask et Agent utilisent ensuite :

Authorization: Bearer <ide-token>

Routes publiques par design

Certaines routes peuvent être appelées sans session web.

Route	Comportement
`GET /api/domains/search?domain=...`	Recherche publique avec rate limit ; ne renvoie pas le prix wholesale fournisseur.
`GET /api/hosting/catalog`	Catalogue hosting public avec cache court.
`GET /api/payments/config`	Méthodes de paiement exposées publiquement.
`GET /api/health`	État opérationnel agrégé, sans cache.

Le fait qu’une route soit publique ne crée pas automatiquement une garantie de compatibilité externe à long terme.

Rate limiting

Le rate limiting n’est pas uniformisé sur toutes les routes.

La recherche de domaine expose actuellement :

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After   # sur 429

La future page Limites ne doit pas inventer un quota global unique tant qu’un système commun n’existe pas.

Format des réponses

La majorité des endpoints non streamés retournent du JSON avec NextResponse.json().

Les erreurs utilisent généralement une forme simple :

{
  "error": "Message lisible"
}

Certains endpoints retournent aussi des structures plus riches, par exemple l’exécution Connectors avec résultat, approval, requestId et activity.

Codes HTTP observés

Code	Usage actuel
200	Succès courant.
201	Création de ressource, par exemple project ou memory.
202	Action Connector en attente d’approbation.
204	Webhook traité sans corps de réponse.
400	Entrée invalide ou validation refusée.
401	Authentification absente ou invalide.
403	Compte non autorisé ou approval invalide selon la route.
404	Ressource ou action non trouvée.
413	Contexte ou pièces jointes trop volumineux.
429	Rate limit, par exemple recherche de domaine.
500 / 503	Erreur serveur, provider indisponible ou budget/runtime non disponible.

Cache et confidentialité

Les routes privées utilisent fréquemment Cache-Control: private, no-store ou no-store.

Certains endpoints publics ont une stratégie spécifique : le catalogue hosting permet un cache public court, tandis que health et domaines utilisent no-store.

Il ne faut donc pas appliquer une stratégie de cache unique à toutes les réponses OrbitWake.

Routes internes et webhooks

Le repo contient aussi des routes qui ne doivent pas être traitées comme API client publique.

Exemples :

/api/internal/beta/invites utilise un token admin serveur privé ;
/api/webhooks/brevo vérifie un secret webhook spécifique ;
les callbacks OAuth GitHub servent le flux Connector ;
les callbacks de paiement servent le flux du provider.

Ne réutilisez pas les secrets internesUn token admin, webhook ou provider n’est jamais un substitut à une future clé API développeur.

Versioning

Les routes actuelles vivent directement sous /api/ et ne sont pas préfixées par une version publique comme /v1.

Il n’existe pas encore de promesse de compatibilité sémantique pour les consommateurs externes.

Une API publique mature devrait introduire explicitement son modèle de versioning avant d’être présentée comme contrat stable.

Ce qu’il ne faut pas faire aujourd’hui

ne pas extraire le cookie orbitwake_session pour l’utiliser comme clé API dans une intégration externe ;
ne pas réutiliser un token IDE comme token API général ;
ne pas dépendre d’une route interne/admin comme contrat produit ;
ne pas supposer que tous les endpoints ont les mêmes quotas ou headers ;
ne pas exposer les secrets admin, webhook ou provider au client.

Limites actuelles

OrbitWake possède une API HTTP fonctionnelle pour ses produits officiels, mais pas encore une plateforme API publique versionnée.

Il n’y a pas aujourd’hui de :

clé API utilisateur publique ;
OAuth public pour apps tierces ;
OpenAPI/Swagger officiel ;
SDK officiel ;
version publique v1 ;
quota externe unifié documenté.

Étapes suivantes

Les prochaines pages API peuvent documenter Authentification, Requêtes, Réponses, Streaming, Erreurs et Limites à partir des comportements vérifiés du runtime actuel, tout en conservant la frontière entre API produit et future API publique développeur.