Requêtes

Base URL

Les routes du produit sont servies sous :

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

La documentation ci-dessous décrit le runtime actuel des clients OrbitWake officiels. Elle ne transforme pas ces routes en API publique stable pour intégrations tierces.

Méthodes HTTP observées

Corps JSON

Les routes mutatives inspectées utilisent request.json() pour lire leur corps.

Pour les requêtes JSON, utilisez normalement :

Content-Type: application/json

Le comportement d’erreur sur JSON invalide n’est pas encore uniformisé. Certaines routes retournent explicitement 400 Invalid JSON., tandis que d’autres laissent leur gestionnaire d’erreur convertir l’échec en réponse spécifique au endpoint.

Paramètres de chemin

Les identifiants de ressource sont placés directement dans l’URL lorsqu’ils adressent une ressource précise.

/api/projects/:projectId
/api/memory/:memoryId
/api/ide/sessions/:sessionId
/api/connectors/approvals/:id

Plusieurs routes valident la forme de l’identifiant avant de continuer, par exemple un UUID pour une session IDE ou une approval Connector.

Query params

Les paramètres de recherche ou de filtre sont généralement transmis dans la query string.

Exemples confirmés :

GET /api/domains/search?domain=example.com
GET /api/memory?search=database&scope=project
GET /api/connectors/activity?limit=50

La validation dépend du endpoint. Pour Memory, un scope inconnu retombe actuellement sur all. Pour Domains, le provider valide ensuite le nom demandé.

Requête AI

POST /api/ai/generate et POST /api/ai/stream utilisent le même schéma d’entrée principal.

{
  "model": "orbitwake-auto",
  "mode": "general",
  "messages": [
    {
      "role": "user",
      "content": "Explique ce code."
    }
  ],
  "conversationId": null,
  "maxOutputTokens": 1200
}

model est optionnel et retombe sur orbitwake-auto. mode retombe sur general.

Rôles des messages AI

Les rôles clients autorisés aujourd’hui sont :

user
assistant

Un message avec le rôle system est refusé. Les instructions système sont gérées côté OrbitWake.

Le contenu d’un message doit être une chaîne non vide après trim.

Pièces jointes AI

Les fichiers AI ne sont pas envoyés en multipart/form-data dans les routes inspectées. Ils sont inclus dans le JSON sous forme base64.

{
  "role": "user",
  "content": "Analyse ce document.",
  "attachments": [
    {
      "name": "rapport.pdf",
      "mimeType": "application/pdf",
      "data": "<base64 brut>"
    }
  ]
}

Le champ data attend du base64 brut correspondant à la validation actuelle, pas une URL data:....

Limites des pièces jointes

Types acceptés : PDF, PNG, JPEG, WEBP et GIF.

Projects : création et modification

Créer un projet :

POST /api/projects

{
  "name": "Mon projet"
}

Renommer un projet :

PATCH /api/projects/:projectId

{
  "name": "Nouveau nom"
}

Archiver un projet se fait avec DELETE /api/projects/:projectId et ne nécessite pas de body dans l’implémentation actuelle.

Projects : fichiers

La sauvegarde d’un fichier de projet utilise PUT :

PUT /api/projects/:projectId/files

{
  "path": "src/app.ts",
  "content": "...",
  "contentType": "text/typescript"
}

La validation finale des champs est déléguée à la couche Projects privée beta.

Projects : checkpoints

Créer une version/checkpoint :

POST /api/projects/:projectId/versions

{
  "label": "Avant refactor"
}

Le body est optionnel pour cette route : un JSON absent ou invalide est actuellement converti en objet vide par le handler.

Restaurer une version :

POST /api/projects/:projectId/versions/:versionId/restore

La restauration ne lit pas de body dans l’implémentation actuelle.

Memory : création

Exemple :

POST /api/memory

{
  "scope": "project",
  "category": "decision",
  "title": "Base de données",
  "content": "Utiliser PostgreSQL.",
  "projectKey": "orbitwake",
  "pinned": true
}

content est obligatoire. scope retombe sur personal et category sur context lorsqu’ils ne sont pas fournis.

Un scope project nécessite un projectKey.

Memory : modification partielle

PATCH /api/memory/:memoryId ne modifie que les champs présents dans le body.

{
  "title": "Décision mise à jour",
  "pinned": false
}

Les champs title et content ne peuvent pas devenir vides lorsqu’ils sont explicitement fournis.

Connectors : exécuter une action

Le body de POST /api/connectors/execute utilise :

{
  "connectorId": "github",
  "actionName": "read_file",
  "input": {
    "owner": "example",
    "repo": "project",
    "path": "README.md"
  },
  "idempotencyKey": "optional-string",
  "approvalId": "optional-uuid"
}

connectorId et actionName sont obligatoires. input retombe sur un objet vide.

Idempotency

Dans la surface Connectors actuelle, l’idempotency est transmise dans le JSON avec :

"idempotencyKey": "..."

Il n’existe pas aujourd’hui de convention globale documentée utilisant un header HTTP Idempotency-Key pour toutes les routes OrbitWake.

Ne supposez donc pas qu’un POST est rejouable sans effet secondaire simplement parce qu’une autre API supporte ce header.

Connectors : approvals

Une décision d’approbation utilise :

POST /api/connectors/approvals/:id

{
  "decision": "approve"
}

La seule autre valeur acceptée est deny. L’identifiant d’approval doit être un UUID valide.

Requêtes IDE

Les requêtes Ask/Agent de l’extension utilisent leur Bearer token IDE et un body JSON.

Authorization: Bearer <ide-token>
Content-Type: application/json

Le pairing claim transmet notamment code, deviceName, editorName, editorVersion et machineId.

Le token IDE ne doit pas être réutilisé pour les endpoints web généraux.

GET publics

Une route publique peut n’exiger aucun cookie ou Bearer token.

Exemple :

GET /api/domains/search?domain=orbitwake.com

Cette route applique son propre rate limiting et expose les headers associés. Le caractère public est spécifique au endpoint, pas au préfixe /api.

Headers utiles

Aucun header client universel de version API, de clé API ou d’idempotency n’est actuellement défini comme contrat public.

Appels depuis le client web

Le produit web officiel appelle ses endpoints dans le contexte de la session navigateur. Le cookie HttpOnly est géré par le navigateur et n’est pas accessible au JavaScript applicatif comme une clé à copier.

Cette documentation n’encourage pas l’extraction manuelle du cookie pour fabriquer des appels externes.

Validation d’entrée

Les routes valident leurs données au plus près de leur domaine :

• AI valide modèles, modes, rôles, contexte et fichiers ;
• Memory valide scope, category, tailles et champs obligatoires ;
• Connectors valide action, UUID d’approval et types ;
• IDE valide pairing, Bearer token et sessions ;
• Domains applique validation provider et rate limit.

Il n’existe pas encore un schéma public OpenAPI unique à partir duquel générer automatiquement toutes ces validations côté client.

Retries

Un retry est généralement moins risqué sur un GET de lecture que sur un POST mutatif.

Pour une action Connector, utilisez l’idempotencyKey lorsqu’elle est pertinente au workflow. Pour les autres POST, ne supposez pas une déduplication globale.

Les actions comme création de projet, mémoire, checkpoint ou ordre hosting peuvent avoir des effets persistants : le client doit connaître le résultat précédent avant de rejouer aveuglément la requête.

Ce qui n’est pas uniformisé aujourd’hui

Limites actuelles

Ces conventions décrivent l’implémentation actuelle, pas une spécification externe immuable.

Tant qu’une API publique versionnée n’est pas disponible, les consommateurs externes ne doivent pas construire une dépendance critique sur des routes produit privées ou sur des détails internes de body non contractuels.

Étape suivante

La page Réponses détaillera les structures JSON de succès, les envelopes de ressources, les métadonnées AI, les réponses Connectors et les headers de cache observés.