API publique v1

L'API publique v1 est le contrat stable que Superfasttt offre aux applications tierces (CRM, ERP, outils métier) : un préfixe versionné, /api/public/v1/, une authentification par clé d'API scopée, des réponses dont la forme ne change pas sans une nouvelle version.

Principes

• Une clé = un espace client. L'espace client d'une requête est toujours celui de la clé, jamais un paramètre, un en-tête ou un champ du corps. Une application qui travaille avec plusieurs instances détient une clé par instance et route elle-même chaque appel vers la bonne instance.
• Serveur à serveur. Seules les clés sk-... sont acceptées, dans l'en-tête Authorization: Bearer sk-.... Un jeton de session utilisateur est refusé (401).
• Versionnée. Rien n'est renommé ni retiré dans /api/public/v1/ : on y ajoute des routes et des champs optionnels. Une rupture passe par une v2 publiée à côté, avec le préavis décrit dans Versioning.

GET /api/public/v1/whoami

Scope requis : public:whoami.

Rend l'espace client (l'instance) auquel appartient la clé, ainsi que l'identité publique de la clé. C'est la sonde à appeler au démarrage de votre intégration, ou après un changement de configuration, pour vérifier que l'URL et la clé désignent bien l'instance attendue.

curl -s https://<votre-instance>/api/public/v1/whoami \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "api_version": "v1",
  "tenant": { "id": "acme", "name": "Acme", "slug": "acme", "domain": null },
  "key": {
    "id": "3f1e0f0c-8d5c-4d8e-9b8e-2a1c3b4d5e6f",
    "prefix": "sk-1a2b",
    "name": "CRM",
    "scopes": ["public:whoami"],
    "expires_at": null
  },
  "environment": "production"
}

• Le secret de la clé n'est jamais renvoyé.
• L'appel ne compte pas comme une utilisation de la clé : son compteur d'utilisation, sa date de dernière utilisation et son quota journalier restent inchangés. La limite par minute s'applique, et l'appel est tracé dans le journal de la clé.
• Comparez tenant.id à l'identifiant attendu pour cette instance : une différence signale une URL ou une clé inversée.

POST /api/public/v1/documents/parse

Scope requis : documents:parse.

Lit un document et rend son texte, sans rien stocker sur l'instance (ni document, ni index). Le fichier est lu par la même chaîne que l'import de documents de l'instance : le lecteur intégré, ou un service d'OCR si l'instance en a configuré un et que sa politique de données l'autorise.

curl -s https://<votre-instance>/api/public/v1/documents/parse \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@bail.pdf"

{
  "api_version": "v1",
  "filename": "bail.pdf",
  "parsing_mode": "mistral:ocr",
  "format": "markdown",
  "content": "# Bail commercial\n\n| Surface | Loyer |\n\n## Annexe",
  "characters": 49,
  "page_count": 2,
  "pages": ["# Bail commercial\n\n| Surface | Loyer |", "## Annexe"]
}

• format vaut markdown quand un OCR a lu le document (titres et tableaux conservés), text pour le lecteur intégré.
• pages donne le texte de chaque page quand le document est lu page par page (PDF, OCR) ; sinon pages et page_count valent null.
• Envoyez un seul fichier, dans le champ file, avec un en-tête Content-Length (les envois « chunked » sont refusés).
• Types acceptés : pdf, docx, xlsx, txt, md, mdx, html, csv ; 50 Mo et 500 pages au plus ; le texte rendu est limité à 5 millions de caractères.
• L'appel compte comme une utilisation de la clé ; le coût d'un OCR externe est imputé au budget IA de l'instance. La réponse n'est jamais mise en cache (Cache-Control: no-store).

Les refus communs à toute l'API publique (clé, scope, option, IP, limites, état de l'espace client) sont décrits dans Erreurs.

POST /api/public/v1/agents/{agent_id}/ask

Scope requis : agents:ask.

Pose une question à un agent de l'instance et rend sa réponse, avec les sources sur lesquelles elle s'appuie. L'agent tourne exactement comme dans les applications de l'instance (mêmes droits, mêmes outils, même modèle, même budget) ; la réponse n'est pas diffusée en continu.

curl -s https://<votre-instance>/api/public/v1/agents/<agent_id>/ask \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"question": "Quel est le loyer annuel du bail de la rue de Rivoli ?"}'

{
  "api_version": "v1",
  "agent_id": "8b1f…",
  "conversation_id": "c42e…",
  "answer": "Le loyer annuel est de 120 000 € HT.",
  "sources": [
    {
      "origin": "knowledge_base",
      "source_id": "d71a…#3",
      "document_id": "d71a…",
      "title": "Bail Rivoli.pdf",
      "excerpt": "Loyer annuel : 120 000 € HT",
      "score": 0.82,
      "url": null
    }
  ],
  "iteration_budget_reached": false
}

• L'agent doit être visible par le compte qui a créé la clé (son propriétaire, un partage, un agent public de l'espace) ; sinon il n'existe pas pour la clé (404 agent_not_found).
• sources réunit les passages de documents cités (origin: knowledge_base) et les pages web consultées par les outils de l'agent (origin: tool, avec url).
• Conversation : la réponse porte un conversation_id ; renvoyez-le avec la question suivante pour rester dans le même fil. Seule la clé qui a ouvert une conversation peut la poursuivre : toute autre conversation, y compris celles du compte qui a créé la clé, répond 404 conversation_not_found.
• Mémoire personnelle : l'appel ne lit ni n'alimente la mémoire du compte qui a créé la clé.
• iteration_budget_reached vaut true quand l'agent a épuisé son nombre d'étapes : la réponse peut être incomplète.
• L'appel compte comme une utilisation de la clé ; il consomme le budget IA de l'instance et suit la limite par minute des appels IA. La réponse n'est jamais mise en cache (Cache-Control: no-store).

POST /api/public/v1/knowledge-bases/{kb_id}/documents

Scope requis : knowledge_bases:ingest.

Ajoute un document (en markdown) à une base de connaissances de l'instance, où ses agents et ses recherches le trouvent, ou le remplace s'il y est déjà.

curl -s https://<votre-instance>/api/public/v1/knowledge-bases/<kb_id>/documents \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "bail-42",
    "source_feed": "crm-baux",
    "title": "Bail Rivoli",
    "content_markdown": "# Bail Rivoli\n\nLoyer annuel : 120 000 € HT",
    "metadata": { "ville": "Paris" }
  }'

{
  "api_version": "v1",
  "knowledge_base_id": "5e0c…",
  "id": "a41b…",
  "external_id": "bail-42",
  "source_feed": "crm-baux",
  "action": "created"
}

• Idempotent. Un document est identifié dans la base par source_feed et external_id, que vous choisissez. Le renvoyer le remplace (updated) ; le renvoyer à l'identique — même texte, même titre, mêmes metadata — ne fait rien (unchanged, rien n'est réindexé). id reste le même.
• source_feed nomme votre flux (minuscules, chiffres, _, ., -) : choisissez-le une fois et gardez-le, il ne dépend pas de la clé (une clé renouvelée retrouve ses documents).
• La base doit être modifiable par le compte qui a créé la clé (il en est propriétaire, ou elle lui est partagée en édition). Si la clé est restreinte à certaines ressources, la base doit en faire partie. Sinon elle n'existe pas pour la clé (404).
• Pour un fichier, lisez-le d'abord avec POST /api/public/v1/documents/parse (ci-dessus) et envoyez son content.
• metadata : des champs simples (texte, nombre, booléen), 50 au plus, enregistrés avec chaque passage du document.
• Le texte est indexé pendant l'appel ; l'appel compte comme une utilisation de la clé et son indexation est comptée dans le budget RAG de l'instance.

POST /api/public/v1/knowledge-bases/{kb_id}/search

Scope requis : knowledge_bases:search.

Rend les passages d'une base de connaissances les plus proches d'une question, le plus pertinent d'abord, chacun avec ce qui le cite : le document, sa page et sa section quand on les connaît. Ce sont les passages qu'un agent de l'instance citerait : document_id est le même que dans les sources de POST /api/public/v1/agents/{agent_id}/ask. Les réglages de recherche de la base s'appliquent (mode, nombre de passages, reclassement, seuil).

curl -s https://<votre-instance>/api/public/v1/knowledge-bases/<kb_id>/search \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Quel est le loyer annuel ?", "limit": 5 }'

{
  "api_version": "v1",
  "knowledge_base_id": "5e0c…",
  "hits": [
    {
      "document_id": "bail-rivoli.pdf",
      "chunk_index": 3,
      "title": "Bail Rivoli",
      "excerpt": "Le loyer annuel est fixé à 120 000 € HT…",
      "page": 4,
      "section": "Conditions financières",
      "score": 0.82
    }
  ]
}

La base doit être lisible par le compte qui a créé la clé et, si la clé est restreinte à certaines ressources, en faire partie ; sinon elle n'existe pas pour la clé (404).

Erreurs

Tout refus d'authentification ou d'autorisation porte un code stable :

{ "detail": { "error": "insufficient_scope", "message": "...", "required_scope": "public:whoami" } }

Les erreurs 404/405 de routage, 422 de validation et 500 suivent le format général.