Docs / Référence API

Référence API

Tous les points d'accès API utilisent le format JSON. L'authentification utilise une clé API Bearer aqn_. Voir Authentification pour plus de détails.

URL de base : https://your-instance/api/

Authentification

Incluez votre clé API dans toutes les requêtes :

Authorization: Bearer aqn_your_api_key

Les clés API sont créées et gérées depuis la page Clés API (/keys/). Les clés à accès complet voient toutes les collections ; les clés limitées ne voient que les collections autorisées.

Collections

Lister les collections

GET /api/collections/

Renvoie les collections visibles par l'utilisateur authentifié (possédées + publiques souscrites).

Réponse : 200 OK

[
  {
    "uuid": "a1b2c3...",
    "name": "Project Docs",
    "slug": "project-docs",
    "description": "Technical documentation",
    "document_count": 15,
    "total_chunks": 342,
    "is_public": false,
    "is_subscribed": false,
    "created_at": "2026-03-01T10:00:00Z"
  }
]

Obtenir une collection

GET /api/collections/{uuid}/

Réponse : 200 OK — Objet Collection

Documents

Lister les documents

GET /api/documents/

Renvoie les documents de toutes les collections visibles.

Paramètres de requête :

Paramètre Type Description
tag string Filtrer par tag (insensible à la casse)
collection string Filtrer par identifiant de collection

Réponse : 200 OK

[
  {
    "uuid": "d4e5f6...",
    "title": "Annual Report 2025",
    "source_type": "pdf",
    "status": "indexed",
    "tags": ["finance", "annual"],
    "chunks_count": 24,
    "original_filename": "report-2025.pdf",
    "file_size": 102400,
    "collection_name": "Project Docs",
    "collection_slug": "project-docs",
    "created_at": "2026-03-01T10:00:00Z"
  }
]

Obtenir le détail d'un document

GET /api/documents/{uuid}/

Réponse : 200 OK — Inclut content_text, error_message et le tableau chunks.

{
  "uuid": "d4e5f6...",
  "title": "Annual Report 2025",
  "source_type": "pdf",
  "status": "indexed",
  "tags": ["finance", "annual"],
  "chunks_count": 24,
  "original_filename": "report-2025.pdf",
  "file_size": 102400,
  "content_text": "Full extracted text...",
  "error_message": "",
  "collection_name": "Project Docs",
  "collection_slug": "project-docs",
  "created_at": "2026-03-01T10:00:00Z",
  "chunks": [
    {
      "id": "uuid",
      "content": "Chunk text content...",
      "chunk_index": 0,
      "embedding_model": "text-embedding-3-small"
    }
  ]
}
POST /api/search/

Corps de la requête :

{
  "query": "payment terms",
  "collection": "project-docs",
  "limit": 5
}
Champ Type Requis Par défaut
query string Oui —
collection slug Non Toutes les collections visibles
limit int Non 5 (max: 50)

Réponse : 200 OK

{
  "query": "payment terms",
  "count": 3,
  "results": [
    {
      "content": "Matching chunk text...",
      "title": "Contract Document",
      "document_id": "uuid",
      "collection_name": "Legal",
      "tags": ["contract"],
      "score": 0.89
    }
  ]
}

Abonnements aux collections

S'abonner à une collection publique

POST /api/collections/{slug}/subscribe/

Réponse : 200 OK

{
  "status": "subscribed",
  "collection": "project-docs"
}

Erreurs :

  • 404 — Collection introuvable ou non publique

Se désabonner d'une collection

DELETE /api/collections/{slug}/subscribe/

Réponse : 200 OK

{
  "status": "unsubscribed",
  "collection": "project-docs"
}

Erreurs :

  • 404 — Abonnement introuvable

Gestion des clés API (KaaS)

Les clés API KaaS permettent aux développeurs externes de rechercher dans vos collections. Elles sont gérées via la page Clés API de l'interface web ou via l'API REST.

Lister / Créer des clés API

GET /api/keys/
POST /api/keys/

Corps de la requête de création :

{
  "name": "Acme Corp Key"
}

Réponse de création : 201 Created

{
  "uuid": "key-uuid",
  "name": "Acme Corp Key",
  "prefix": "aqn_abc123...",
  "key": "aqn_full_key_here",
  "is_active": true,
  "created_at": "2026-03-01T10:00:00Z"
}

Le champ key n'est renvoyé qu'au moment de la création.

Rotation de la clé API

POST /api/keys/{uuid}/rotate/

Révoque la clé API existante et en crée une nouvelle avec le même nom et les mêmes autorisations d'accès aux collections. L'ancienne clé est immédiatement désactivée.

Réponse : 201 Created

{
  "uuid": "new-key-uuid",
  "name": "Acme Corp Key",
  "prefix": "aqn_abc123...",
  "key": "aqn_new_full_key_here",
  "is_active": true,
  "is_full_access": false,
  "created_at": "2026-03-13T10:00:00Z"
}

Le champ key n'est renvoyé qu'au moment de la rotation. Conservez-le en lieu sûr — il ne pourra pas être récupéré ultérieurement.

Erreurs :

  • 404 — Clé API introuvable ou n'appartenant pas à l'utilisateur authentifié

Accorder / Révoquer l'accès à une collection

POST /api/keys/{uuid}/collections/
DELETE /api/keys/{uuid}/collections/{collection-slug}/

Corps de la requête d'autorisation :

{
  "collection": "collection-slug"
}

Statistiques d'utilisation

GET /api/keys/usage/?days=30
GET /api/keys/{uuid}/usage/

Point d'accès MCP

Le serveur MCP est accessible à /mcp via le transport Streamable HTTP.

Authentification : Authorization: Bearer aqn_<key>

Outils disponibles :

Outil Description
search_documents Recherche hybride texte + vecteur avec filtre de collection et limite de résultats optionnels
list_collections Lister toutes les collections avec le nombre de documents et les descriptions
get_document_info Obtenir les détails complets d'un document et ses fragments par UUID
search_by_tag Trouver tous les documents avec un tag spécifique

Gestion des erreurs

Codes de statut HTTP

Code Signification
200 Succès
201 Créée
400 Requête incorrecte (erreur de validation)
401 Non autorisé (jeton ou clé API manquant ou invalide)
404 Ressource introuvable
429 Limite de débit atteinte
500 Erreur du serveur

Format de réponse d'erreur

Toutes les erreurs utilisent une enveloppe cohérente avec un champ error :

{
  "error": "Error message describing what went wrong."
}

Les erreurs de validation incluent un objet fields avec les détails par champ :

{
  "error": "Validation failed.",
  "fields": {
    "name": ["This field is required."],
    "collection": ["Collection not found."]
  }
}