Réponses

Convention générale

Les handlers non streamés utilisent généralement NextResponse.json(). Les succès peuvent renvoyer { user }, { project }, { memory }, { response } ou un objet métier direct.

Format d’erreur courant

{
  "error": "Message lisible"
}

Connectors peut aussi retourner une erreur métier à l’intérieur de son objet result.

AI — génération JSON

POST /api/ai/generate renvoie :

{
  "conversation": { "...": "..." },
  "response": {
    "id": "provider-request-id",
    "text": "Réponse générée",
    "provider": "openai",
    "providerModel": "...",
    "model": "...",
    "modelLabel": "...",
    "routingTier": "...",
    "routingReason": "...",
    "sources": [],
    "usage": { "...": "..." },
    "latencyMs": 1234,
    "estimatedCredits": 0.42
  }
}

conversation peut être null si aucune conversation persistée n’est retournée.

Métadonnées AI

AI — événement final du streaming

L’événement SSE done renvoie les métadonnées finales et la conversation. Le texte complet n’est pas répété dans done : il arrive via les événements delta.

Projects

GET /api/projects
{ "projects": [...] }

POST /api/projects
{ "project": { "...": "..." } }

DELETE /api/projects/:projectId
{ "archived": true }

La création d’un projet retourne 201 Created.

Fichiers et checkpoints

{ "file": { "...": "..." } }

{ "version": { "...": "..." } }

{ "restored": true }

La création d’un checkpoint retourne 201 Created.

Memory

GET /api/memory
{
  "memories": [...],
  "settings": { "...": "..." }
}

POST/PATCH
{ "memory": { "...": "..." } }

DELETE
{ "deleted": true }

La création d’une mémoire retourne 201 Created.

Connectors

POST /api/connectors/execute retourne :

{
  "result": {
    "success": true
  },
  "approval": null,
  "requestId": "uuid",
  "activity": [...]
}

Quand une approbation est requise, le status peut être 202 et approval contient la demande créée.

Erreurs métier Connectors

{
  "result": {
    "success": false,
    "error": {
      "code": "ACTION_NOT_FOUND",
      "message": "...",
      "retryable": false
    }
  },
  "approval": null,
  "requestId": "uuid",
  "activity": [...]
}

Le status dépend du code métier : approval requise, action absente, approval invalide ou erreur de validation.

IDE

Liste des sessions :

{
  "sessions": [
    {
      "id": "uuid",
      "deviceName": "...",
      "editorName": "VS Code",
      "editorVersion": "...",
      "lastSeenAt": "...",
      "createdAt": "..."
    }
  ]
}

IDE — Ask

{
  "response": {
    "text": "...",
    "model": "...",
    "modelLabel": "...",
    "provider": "...",
    "latencyMs": 1200,
    "estimatedCredits": 0.2
  }
}

Cette shape est plus compacte que celle de /api/ai/generate.

IDE — Agent

{
  "proposal": {
    "summary": "...",
    "changes": [
      {
        "path": "src/file.ts",
        "content": "...",
        "reason": "..."
      }
    ]
  },
  "response": {
    "model": "...",
    "modelLabel": "...",
    "provider": "...",
    "latencyMs": 1200,
    "estimatedCredits": 0.5
  }
}

Auth

Les routes qui retournent l’utilisateur utilisent généralement :

{
  "user": {
    "id": "...",
    "email": "...",
    "name": "...",
    "workspaceName": "...",
    "defaultModel": "...",
    "onboardingComplete": true
  }
}

Sign-out, reset password et certaines actions email retournent { "ok": true }.

Session absente

GET /api/auth/session retourne actuellement 401 avec :

{ "user": null }

C’est une exception au format d’erreur { error }.

Domains

{
  "domain": "example.com",
  "available": true,
  "premium": false,
  "priceUsd": 12.34,
  "currency": "USD",
  "environment": "production"
}

Hosting catalog

{
  "provider": "...",
  "environment": "...",
  "configured": true,
  "region": "...",
  "product": "...",
  "plans": [...],
  "checkoutEnabled": false,
  "source": "...",
  "updatedAt": "..."
}

En erreur provider, le endpoint peut retourner 503, une liste de plans vide et un champ error.

Health

{
  "status": "operational",
  "checkedAt": "2026-...",
  "components": {
    "website": {
      "state": "operational",
      "latencyMs": 0
    }
  }
}

Si un composant est dégradé, le status global devient degraded et le HTTP status passe à 503.

Headers de cache

Rate limit headers

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

Ces headers sont vérifiés sur la recherche de domaine, pas comme convention globale de toute l’API.

Status codes

Ce qui n’est pas standardisé

Il n’existe pas encore d’envelope universelle { data, error, meta }, ni de requestId global. Le champ requestId est confirmé dans Connectors, mais pas garanti ailleurs.

Conseils côté client

• lire le status HTTP avant la structure métier ;
• pour Connectors, lire aussi result.success ;
• pour SSE, traiter les événements individuellement ;
• respecter les headers de cache du endpoint ;
• ne pas figer une intégration externe sur une shape non versionnée.

Limites actuelles

Ces structures correspondent au runtime actuel. Une future API publique devra probablement standardiser envelopes, erreurs, request IDs, pagination et métadonnées.

Étape suivante

La page Streaming détaillera les événements SSE activity, delta, done et error.