Clés API et limites de débit
aqoon utilise des clés API pour authentifier l'accès programmatique à l'API de recherche, au serveur MCP et aux autres points d'accès développeur. Les clés sont préfixées par aqn_ suivi de 40 caractères aléatoires et sont stockées côté serveur sous forme de hachages SHA-256 — le texte en clair n'est affiché qu'une seule fois lors de la création.
Pour créer et gérer vos clés depuis l'interface, consultez le Guide utilisateur.
Types de clés
Il existe deux types de clés avec des portées d'accès différentes :
| Type | Portée d'accès | Usage courant |
|---|---|---|
| Accès complet | Toutes les collections possédées par ou souscrites par le propriétaire de la clé | Intégration MCP personnelle, scripts d'automatisation, outils internes |
| Limité | Uniquement les collections explicitement autorisées pour la clé | Partage de l'accès à la recherche avec des développeurs ou applications tiers |
Les clés limitées sont le choix le plus sûr par défaut pour distribuer les accès. Accordez l'accès à des collections spécifiques via l'interface de gestion des clés ou le point d'accès /api/keys/{uuid}/collections/.
Key Expiration
Keys can be created with an expiration date (30 days, 90 days, 6 months, or 1 year) or set to never expire. You can change the expiration at any time from the key detail page.
Expired keys are automatically rejected with a 401 error. To renew a key, set a new expiration from the key detail page. No new key needs to be created.
Point d'accès de recherche
Le point d'accès de recherche développeur accepte un jeton Bearer et renvoie des fragments de résultats classés provenant de toutes les collections accessibles à la clé :
POST /api/search/
Authorization: Bearer aqn_your_api_key
Content-Type: application/json
{
"query": "your search query",
"limit": 5,
"collection_id": "optional-uuid-to-scope-to-one-collection"
}Exemple avec curl :
curl -X POST https://your-instance/api/search/ \
-H "Authorization: Bearer aqn_your_api_key" \
-H "Content-Type: application/json" \
-d '{"query": "retrieval augmented generation", "limit": 10}'Consultez la Référence API pour les schémas complets de requête/réponse, les options de filtrage et les codes d'erreur. Utilisez le Playground de recherche pour tester de manière interactive.
Limitation de débit
Chaque clé API se voit attribuer un niveau de débit qui contrôle le nombre de requêtes autorisées sur trois fenêtres temporelles :
| Niveau | Par minute | Par jour | Par mois |
|---|---|---|---|
| Gratuit (par défaut) | 10 | 1,000 | 10,000 |
| Basic | 60 | 10,000 | 100,000 |
| Pro | 300 | 100,000 | 1,000,000 |
Les niveaux de débit sont gérés par l'administrateur de votre compte. Les limites sont appliquées par compte — toutes les clés API d'un même utilisateur partagent un seul jeu de compteurs. Chaque réponse API inclut les en-têtes suivants pour que votre application puisse suivre les limites de manière programmatique :
| En-tête | Description |
|---|---|
X-RateLimit-Limit |
Nombre maximum de requêtes autorisées dans la fenêtre en cours |
X-RateLimit-Remaining |
Requêtes restantes dans la fenêtre en cours |
Retry-After |
Secondes à attendre avant de réessayer (présent uniquement sur les réponses 429) |
Lorsqu'une limite est dépassée, l'API renvoie HTTP 429 Too Many Requests. Votre client doit respecter Retry-After et implémenter un backoff exponentiel pour la résilience.
Tableau de bord d'utilisation
Le tableau de bord d'utilisation est accessible dans la barre latérale sous Utilisation de l'API. Il fournit :
- Métriques de synthèse — Total des requêtes, nombre d'erreurs et temps de réponse moyen pour la période sélectionnée
- Graphique de volume quotidien — Requêtes et erreurs tracées sur 7, 30 ou 90 jours
- Détail par clé — Nombre de requêtes et taux d'erreurs par clé API
- Journal des requêtes récentes — Texte de la requête, nombre de résultats, temps de réponse et statut HTTP pour chaque requête
Facturation et tarifs
Le volume de requêtes API est mesuré par rapport à votre quota mensuel. Trois plans sont disponibles :
| Plan | Prix | Requêtes incluses/mois | Tarif de dépassement |
|---|---|---|---|
| Gratuit | $0/mois | 1,000 | — |
| Starter | $29/mois | 10,000 | $0.002 par requête |
| Pro | $99/mois | 100,000 | $0.001 par requête |
La facturation est gérée via Stripe. Les factures sont générées automatiquement à la fin de chaque cycle de facturation en fonction des données d'utilisation réelles. Les frais de dépassement ne sont appliqués que lorsque vous dépassez le quota inclus dans votre plan.