Kaneme Cycle de vie API

openapi: 3.2.0
info:
  title: Kaneme Cycle de vie API
  version: 5.4.0
  description: 'API REST de Kaneme : écrire dans ta voix, mesurer la fidélité d’un texte, attribuer sa paternité en probabilité calibrée, et gérer projets et documents. Les mêmes opérations, les mêmes bornes et les mêmes crédits que l’application. Deux axes distincts sont mesurés et jamais fusionnés : l’identité (mesurée) et la composition (déclarée, jamais détectée). Le TAMPON est calibré sur le français et sur l’anglais, chacun avec son propre moteur ; Q2 (toi ou un autre humain) rend une lecture indicative en français : sa probabilité est fournie, son libellé ne dépasse pas `Ambigu` ; en anglais, il ne conclut `signature` qu’au-dessus du seuil de son examen scellé, et dit `Ambigu` dessous. Sur un texte qui ne se lit ni en français ni en anglais, la vérification s’abstient et rend `probability: null` avec `unavailable: "unsupported_language"` ; quand la voix de référence n’est pas écrite dans la langue du texte, avec `"voice_language_mismatch"` ; quand une phrase entière, hors citation entre guillemets, est dans l’autre langue, avec `"mixed_language"` et les phrases dans `passages` — ce n’est PAS une panne, et le code se distingue de `embedding_layer` (couche indisponible) et `out_of_distribution` (registre non couvert). Une abstention n’est jamais facturée. Le RELEVÉ d’automatismes, lui, sort dans toutes les langues outillées : il compte ses marqueurs dans la langue qu’il a lue et rend `markerLanguage` pour dire lequel il a appliqué. Le champ `language` de chaque réponse porte la langue lue, `inDomain` dit si un verdict serait valide. L’API et le MCP sont ouverts à tout compte Kaneme, gratuit compris. Chaque opération se paie au crédit, exactement comme dans l’app : aucun second compteur. Le relevé d’automatismes (stylométrie locale) ne coûte rien ; un tampon coûte au plus 2 crédits, et rien quand le moteur s’abstient. Quand tes crédits disponibles sont épuisés, les opérations payantes s’arrêtent. Une recharge les réactive ; en espace personnel, la prochaine allocation mensuelle les réactive aussi. L’API renvoie HTTP 402 lorsque les crédits disponibles sont épuisés.'
servers:
- url: https://kaneme.com
security:
- apiKey: []
tags:
- name: Cycle de vie
paths:
  /api/v1/trash:
    get:
      operationId: listTrash
      summary: Liste la corbeille restaurable ; aucune purge définitive par API/MCP
      tags:
      - Cycle de vie
      x-kaneme-credits: '0'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:manage
      x-kaneme-risk: manage
      x-kaneme-mcp-tool: list_trash
      x-kaneme-timeout-seconds: 15
      responses:
        '200':
          description: Succès.
          headers:
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateRemaining'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/RateWindow'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrashList'
        '400':
          $ref: '#/components/responses/Invalide'
        '401':
          $ref: '#/components/responses/NonAutorise'
        '402':
          $ref: '#/components/responses/CreditsEpuises'
        '404':
          $ref: '#/components/responses/Introuvable'
        '409':
          $ref: '#/components/responses/Conflit'
        '422':
          $ref: '#/components/responses/NonMesurable'
        '429':
          $ref: '#/components/responses/TropDAppels'
        '500':
          $ref: '#/components/responses/ErreurServeur'
        '503':
          $ref: '#/components/responses/Indisponible'
  /api/v1/lifecycle:
    post:
      operationId: manageLifecycle
      summary: Prévisualise ou applique jusqu’à 10 archivages, mises à la corbeille…
      tags:
      - Cycle de vie
      x-kaneme-credits: '0'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:manage
      x-kaneme-risk: manage
      x-kaneme-mcp-tool: manage_lifecycle
      x-kaneme-timeout-seconds: 30
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: Rejouer le même appel avec la même clé rend le premier résultat sans re-débiter. Présent uniquement sur les opérations qui l’honorent réellement.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  minItems: 1
                  maxItems: 10
                  type: array
                  items:
                    type: object
                    properties:
                      resourceType:
                        type: string
                        enum:
                        - document
                        - project
                        - voice
                        - project_context
                        - voice_asset
                        - document_certificate
                        - voice_certificate
                      resourceId:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      action:
                        type: string
                        enum:
                        - trash
                        - restore
                        - archive
                        - unarchive
                        - revoke
                        - expire
                        - unexpire
                      expiresAt:
                        anyOf:
                        - type: string
                        - type: 'null'
                    required:
                    - resourceType
                    - resourceId
                    - action
                    additionalProperties: {}
                  description: Tableau de 1 à 10 actions de cycle de vie.
                dryRun:
                  type: boolean
                  description: true = vérifie et prévisualise sans modifier.
              additionalProperties: {}
              required:
              - items
      responses:
        '200':
          description: Succès.
          headers:
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateRemaining'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/RateWindow'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LifecycleResult'
        '400':
          $ref: '#/components/responses/Invalide'
        '401':
          $ref: '#/components/responses/NonAutorise'
        '402':
          $ref: '#/components/responses/CreditsEpuises'
        '404':
          $ref: '#/components/responses/Introuvable'
        '409':
          $ref: '#/components/responses/Conflit'
        '422':
          $ref: '#/components/responses/NonMesurable'
        '429':
          $ref: '#/components/responses/TropDAppels'
        '500':
          $ref: '#/components/responses/ErreurServeur'
        '503':
          $ref: '#/components/responses/Indisponible'
components:
  responses:
    Indisponible:
      description: Service ou compteur temporairement indisponible.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
            required:
            - code
            - message
    NonMesurable:
      description: Le moteur s’abstient ou le corpus est insuffisant.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
            required:
            - code
            - message
    ErreurServeur:
      description: Erreur interne.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
            required:
            - code
            - message
    NonAutorise:
      description: Clé absente, invalide ou révoquée.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
            required:
            - code
            - message
    TropDAppels:
      description: 'Cadence dépassée (code « rate_limited »). La réponse porte X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window et Retry-After — attends la fenêtre indiquée : un retry immédiat la prolonge. Les plafonds appliqués sont dans x-kaneme-rate-limits. Quand le refus vient d’un plafond PAR OPÉRATION (générer, créer un document ou un projet, déposer une source), ces nombres sont ceux de CETTE opération, pas ceux de la surface.'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
            required:
            - code
            - message
      headers:
        Retry-After:
          schema:
            type: integer
          description: Secondes à attendre. Ne part que sur un refus.
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateRemaining'
        X-RateLimit-Window:
          $ref: '#/components/headers/RateWindow'
    CreditsEpuises:
      description: 'Crédits insuffisants, OU surface non ouverte à ce compte. code = "subscription_required" : L’API et le MCP se paient en crédits, et ce compte n’en a plus. Recharge ton solde pour réactiver ta clé. code = "credits_exhausted" : lire `window` pour savoir quoi faire (recharger, attendre la période, demander à un admin de relever le budget, relever le plafond de la clé).'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
              window:
                type: string
                enum:
                - balance
                - period
                - budget
                - api_key
                description: 'Présent quand code = "credits_exhausted". `balance` : solde vide, la suite est une recharge. `period` : ancien abonnement, le quota repart à la période suivante. `budget` : membre d’une équipe dont le budget mensuel est pris — un admin le relève ; recharger n’y change rien. `api_key` : la clé appelante a pris son plafond mensuel (réglé par son propriétaire dans Connexions) ; l’app et les autres clés continuent. `budget` et `api_key` repartent le 1er du mois (UTC).'
              meter:
                type: string
                description: Compteur concerné (« voice »).
              budget:
                type: object
                description: 'Pour `window` = `budget` ou `api_key` : le plafond du mois et ce qui est déjà pris, en crédits.'
                properties:
                  limit:
                    type: integer
                  used:
                    type: integer
                required:
                - limit
                - used
            required:
            - error
    Conflit:
      description: Conflit d’état ou de clé d’idempotence.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
            required:
            - code
            - message
    Introuvable:
      description: Ressource introuvable.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
            required:
            - code
            - message
    Invalide:
      description: Requête invalide (champ manquant, borne dépassée, curseur illisible).
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Compatibility alias for the localized message.
              message:
                type: string
                description: Message in the verified account interface_locale; French when no account preference is available.
              code:
                type: string
                description: Stable machine code, independent of message language (for example, invalid_input).
            required:
            - code
            - message
  headers:
    RateWindow:
      schema:
        type: integer
      description: Durée de la fenêtre, en secondes.
    RateLimit:
      schema:
        type: integer
      description: Appels autorisés par fenêtre, pour le plafond qui s’applique à cet appel.
    RateRemaining:
      schema:
        type: integer
      description: Appels restants dans la fenêtre, au passage de la garde — le jeton de cette requête est déjà décompté.
    RequestId:
      schema:
        type: string
        format: uuid
      description: 'Identifiant de CETTE réponse. Journalise-le : c’est ce qu’on te demandera pour retrouver ton appel, et il est écrit dans nos traces sur les erreurs internes.'
  schemas:
    LifecycleResult:
      type: object
      properties:
        dryRun:
          type: boolean
        results:
          type: array
          items:
            type: object
            properties:
              resourceType:
                type: string
                enum:
                - document
                - project
                - voice
                - project_context
                - voice_asset
                - document_certificate
                - voice_certificate
              resourceId:
                type: string
              action:
                type: string
                enum:
                - trash
                - restore
                - archive
                - unarchive
                - revoke
                - expire
                - unexpire
              expiresAt:
                anyOf:
                - type: string
                - type: 'null'
              status:
                type: string
                enum:
                - previewed
                - applied
                - unchanged
                - not_found
                - refused
              reversible:
                type: boolean
              restorableDays:
                anyOf:
                - type: number
                - type: 'null'
              message:
                type: string
            required:
            - resourceType
            - resourceId
            - action
            - status
            - reversible
            - restorableDays
            - message
            additionalProperties: {}
      required:
      - dryRun
      - results
      additionalProperties: {}
    TrashList:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              resourceType:
                type: string
              id:
                type: string
              label:
                type: string
              deletedAt:
                type: string
            required:
            - resourceType
            - id
            - label
            - deletedAt
            additionalProperties: {}
        restorableDays:
          type: number
        permanentPurgeAvailable:
          type: boolean
          const: false
      required:
      - items
      - restorableDays
      - permanentPurgeAvailable
      additionalProperties: {}
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Clé d’API du compte, créée sur la page Connexions. En-tête : `Authorization: Bearer kaneme_…`. Les clés `frq_…` émises avant le changement de nom restent acceptées. C’est la voie MACHINE-À-MACHINE : un programme qui agit pour son propre compte. Ses portées sont choisies à la création ; les gestes sensibles restent décochés par défaut. Les clés historiques sans portées explicites conservent leur accès pour compatibilité. Pour qu’un agent agisse au nom d’un utilisateur, passer par le serveur MCP (`/api/mcp`), dont Kaneme émet les jetons OAuth.'
x-kaneme-contract-version: 5.4.0
x-kaneme-rate-limits:
- scope: Toute la surface
  countedBy: par clé (ou par client OAuth)
  limit: 60
  windowSeconds: 60
  detail: Compté sur l’ensemble des appels /api/v1 et /api/mcp du même porteur.
- scope: Générer un texte
  countedBy: par compte
  limit: 10
  windowSeconds: 10
  detail: 'Fenêtre PARTAGÉE avec l’éditeur de l’app : la clé ne contourne pas la cadence.'
- scope: Créer un document
  countedBy: par compte
  limit: 10
  windowSeconds: 10
  detail: Gratuit en crédits — la cadence est sa seule borne.
- scope: Créer un projet
  countedBy: par compte
  limit: 10
  windowSeconds: 10
  detail: Gratuit en crédits — la cadence est sa seule borne.
- scope: Archiver, mettre à la corbeille ou restaurer
  countedBy: par clé (ou client OAuth)
  limit: 10
  windowSeconds: 60
  detail: Lots de 10 maximum, prévisualisables avec dryRun. Aucune purge définitive par API/MCP.
- scope: Vérifier un certificat (sans clé)
  countedBy: par adresse IP
  limit: 60
  windowSeconds: 60
  detail: 'Ouverte sans compte : le plafond se compte sur l’appelant lui-même, pas sur un porteur.'
- scope: Lire les signaux de l’Observatoire (sans clé)
  countedBy: par adresse IP
  limit: 30
  windowSeconds: 60
  detail: Ouverte sans compte, gratuite ; rien n’est gardé du texte lu.
x-kaneme-rate-limit-headers:
  description: 'Toute réponse — succès compris — porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Window : ralentis en lisant Remaining, plutôt qu’en te cognant. Retry-After ne part QUE sur un 429 : c’est un en-tête de refus, et sur un succès il se lirait comme un ordre d’attendre. Remaining vaut ce qu’il valait au passage de la garde — le jeton de la requête en cours est déjà décompté. Pas de X-RateLimit-Reset : le limiteur ne connaît l’instant de remise à zéro qu’au refus, et un Reset approximatif ferait dormir un client à côté. Exception : GET /certificate/{token} est la seule réponse partageable de la surface (Cache-Control public) — elle omet Remaining, qui appartient à un appelant et non à un cache.'
  emittedOn:
  - toutes les réponses
  headers:
  - X-RateLimit-Limit
  - X-RateLimit-Remaining
  - X-RateLimit-Window
  refusalOnly:
  - Retry-After