Tout Quilly,
au bout d’une requête.

1. 1

   Crée une clé

   Dans Mon compte → Clés API. Choisis lecture seule ou écriture, et une échéance si tu veux.

2. 2

   Ajoute l’en-tête

   Authorization: Bearer aelby_sk_… sur chaque requête. Rien d’autre à configurer.

3. 3

   Appelle /api/v1

   L’index dit à qui est la clé, ce qu’elle peut faire, et où est chaque ressource.

curl "/api/v1" \
  -H "Authorization: Bearer $QUILLY_API_KEY"

Une requête de l’API voit exactement ce que tu vois dans l’application : tes notes, tes fichiers, mais aussi ce qu’on te partage — et rien de plus. Les mêmes règles s’appliquent, les mêmes partages, la même réserve. Une clé se révoque d’un geste dans Mon compte, et chacune garde le journal de ses appels.

La clé n’est jamais conservée en clair : seule son empreinte l’est. Garde-la hors de ton code (variable d’environnement), et jamais dans une page publique.

On teste success, on lit data — ou error, dont le code est stable et le message fait pour être lu. meta.request_id (aussi dans l’en-tête X-Request-Id) retrouve une requête dans les journaux. Les listes se paginent avec limit et offset, et disent s’il en reste (has_more).

{
  "success": true,
  "data": {
    "notes": [
      "…"
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 128,
      "has_more": true
    }
  },
  "meta": {
    "request_id": "5f0c…",
    "timestamp": "2026-10-02T09:41:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "« title » : 500 caractères maximum"
  },
  "meta": {
    "request_id": "9a41…",
    "timestamp": "2026-10-02T09:41:00.000Z"
  }
}

• 401unauthorizedunauthorizedPas de clé dans l’en-tête Authorization
• 401invalid_api_keyinvalid_api_keyClé inconnue
• 401api_key_inactiveapi_key_inactiveClé révoquée
• 401api_key_expiredapi_key_expiredClé expirée
• 403insufficient_permissioninsufficient_permissionClé en lecture seule, sur une route qui écrit
• 403forbiddenforbiddenAction non autorisée sur cet élément (partage en lecture…)
• 404resource_not_foundresource_not_foundIntrouvable — ou hors de portée, c’est volontairement pareil
• 409conflictconflictRefus avec une raison : quelqu’un écrit, partage refusé… (details.reason)
• 413payload_too_largepayload_too_largeTrop lourd pour cet appel
• 422validation_failedvalidation_failedUn champ ne convient pas — le message le nomme
• 400invalid_requestinvalid_requestCorps illisible, ou action refusée par la base
• 429rate_limit_exceededrate_limit_exceededTrop de requêtes : voir l’en-tête Retry-After
• 507insufficient_storageinsufficient_storageLa réserve ne suffit pas (details.verdict)
• 503not_configurednot_configuredUn service n’est pas configuré sur ce serveur
• 502upstream_errorupstream_errorUn service tiers (stockage, IA) n’a pas répondu
• 500internal_errorinternal_errorErreur interne — meta.request_id aide à la retrouver

Version 1.0.0. Les codes d’erreur et la forme des réponses sont stables au sein de la v1.