Kaneme Compte API

openapi: 3.2.0
info:
  title: Kaneme Compte 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: Compte
paths:
  /api/v1/me:
    get:
      operationId: getAccount
      summary: Palier + crédits du compte
      tags:
      - Compte
      x-kaneme-credits: '0'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:read
      x-kaneme-risk: read
      x-kaneme-mcp-tool: get_account
      x-kaneme-timeout-seconds: 10
      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/AccountStatus'
              example:
                organization: null
                tier: discovery
                tierName: Gratuit
                credits:
                  used: 0
                  limit: 0
                  remaining: 15
                  purchased: 15
                  exhausted: false
                  unlimited: false
                  unlimitedReason: null
                meters:
                  voice:
                    meter: voice
                    window: balance
                    resetAt: null
                    used: 0
                    limit: 0
                    remaining: 15
                    exhausted: false
                    topup: 15
                    unlimited: false
                    unlimitedReason: null
        '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/estimate:
    get:
      operationId: estimateCost
      summary: Ce qu’une action coûtera AVANT de la lancer — sans argument, tout le tarif
      tags:
      - Compte
      x-kaneme-credits: '0'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:read
      x-kaneme-risk: read
      x-kaneme-mcp-tool: estimate_cost
      x-kaneme-timeout-seconds: 15
      parameters:
      - name: operation
        in: query
        required: false
        schema:
          type: string
          enum:
          - generate
          - improve
          - verify
          - compare
          - score
          - certify
          - create_voice
          - portage
          - add_project_context
          - add_voice_asset
          - create_document
          - create_project
          - record_signal
          - read
        description: Opération à chiffrer (ex. « generate »). Sans elle, la réponse rend TOUT le tarif.
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - draft
          - outline
          - section
          - challenge
          - bar-test
          - workflow
        description: Variante de l’opération, quand elle en a une (operation="generate").
      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/CostEstimate'
        '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/voice/executions/estimate:
    post:
      operationId: estimatePortableVerification
      summary: Confirme le coût de vérification dans un parcours portable suivi
      tags:
      - Compte
      x-kaneme-credits: '0'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:read
      x-kaneme-risk: read
      x-kaneme-mcp-tool: estimate_portable_verification
      x-kaneme-timeout-seconds: 15
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                executionId:
                  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)$
                  description: Identifiant rendu par prepare_voice_context.
              additionalProperties: false
              required:
              - executionId
      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/PortableVerificationEstimate'
        '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
  schemas:
    CostEstimate:
      type: object
      properties:
        estimate:
          anyOf:
          - type: object
            properties:
              operation:
                type: string
              credits:
                type: number
              conditional:
                type: boolean
              note:
                type: string
            required:
            - operation
            - credits
            - conditional
            - note
            additionalProperties: {}
          - type: 'null'
        pricing:
          type: array
          items:
            type: object
            properties:
              operation:
                type: string
              credits:
                type: number
              conditional:
                type: boolean
              note:
                type: string
            required:
            - operation
            - credits
            - conditional
            - note
            additionalProperties: {}
        credits:
          type: object
          properties:
            remaining:
              anyOf:
              - type: number
              - type: 'null'
            exhausted:
              type: boolean
          required:
          - remaining
          - exhausted
          additionalProperties: {}
        portage:
          type: object
          properties:
            credits:
              type: number
            freeLimit:
              type: number
            used:
              type: number
            freeRemaining:
              type: number
            resetsAt:
              anyOf:
              - type: string
              - type: 'null'
          required:
          - credits
          - freeLimit
          - used
          - freeRemaining
          - resetsAt
          additionalProperties: false
        affordable:
          anyOf:
          - type: boolean
          - type: 'null'
        disclaimer:
          type: string
      required:
      - estimate
      - pricing
      - credits
      - portage
      - affordable
      - disclaimer
      additionalProperties: {}
    PortableVerificationEstimate:
      type: object
      properties:
        estimate:
          type: object
          properties:
            operation:
              type: string
              const: verify
            credits:
              type: number
            conditional:
              type: boolean
            note:
              type: string
          required:
          - operation
          - credits
          - conditional
          - note
          additionalProperties: false
        credits:
          type: object
          properties:
            remaining:
              anyOf:
              - type: number
              - type: 'null'
            exhausted:
              type: boolean
          required:
          - remaining
          - exhausted
          additionalProperties: {}
        affordable:
          anyOf:
          - type: boolean
          - type: 'null'
        disclaimer:
          type: string
        executionReceipt:
          type: object
          properties:
            version:
              type: string
              const: kaneme.portable-execution.v1
            executionId:
              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)$
            status:
              type: string
              enum:
              - context_prepared
              - cost_estimated
              - verifying
              - verified
            createdAt:
              type: string
            completedAt:
              anyOf:
              - type: string
              - type: 'null'
            expiresAt:
              type: string
            voice:
              type: object
              properties:
                profileId:
                  type: string
                voiceRevision:
                  type: string
                referenceId:
                  type: string
                contextId:
                  type: string
                language:
                  type: string
                format:
                  type: string
              required:
              - profileId
              - voiceRevision
              - referenceId
              - contextId
              - language
              - format
              additionalProperties: false
            channel:
              type: string
            clientVersion:
              anyOf:
              - type: string
              - type: 'null'
            estimate:
              anyOf:
              - type: object
                properties:
                  operation:
                    type: string
                    const: verify
                  credits:
                    type: number
                  conditional:
                    type: boolean
                required:
                - operation
                - credits
                - conditional
                additionalProperties: false
              - type: 'null'
            candidateDigest:
              anyOf:
              - type: string
              - type: 'null'
            measurementId:
              anyOf:
              - type: string
              - type: 'null'
            outcome:
              anyOf:
              - type: string
                enum:
                - measured
                - abstained
              - type: 'null'
            steps:
              minItems: 4
              maxItems: 4
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    enum:
                    - context_prepared
                    - cost_estimated
                    - text_submitted
                    - voice_verified
                  status:
                    type: string
                    enum:
                    - completed
                    - pending
                  evidence:
                    type: string
                    enum:
                    - server_observed
                    - client_submitted
                  completedAt:
                    anyOf:
                    - type: string
                    - type: 'null'
                required:
                - id
                - status
                - evidence
                - completedAt
                additionalProperties: {}
            limitation:
              type: string
          required:
          - version
          - executionId
          - status
          - createdAt
          - completedAt
          - expiresAt
          - voice
          - channel
          - clientVersion
          - estimate
          - candidateDigest
          - measurementId
          - outcome
          - steps
          - limitation
          additionalProperties: {}
      required:
      - estimate
      - credits
      - affordable
      - disclaimer
      - executionReceipt
      additionalProperties: {}
    AccountStatus:
      type: object
      properties:
        organization:
          anyOf:
          - type: object
            properties:
              id:
                type: string
              name:
                type: string
              role:
                type: string
                enum:
                - owner
                - admin
                - member
              pays:
                type: boolean
              credits:
                type: object
                properties:
                  remaining:
                    anyOf:
                    - type: number
                    - type: 'null'
                  exhausted:
                    type: boolean
                required:
                - remaining
                - exhausted
                additionalProperties: {}
              memberBudget:
                anyOf:
                - type: object
                  properties:
                    limit:
                      type: number
                    used:
                      type: number
                    remaining:
                      type: number
                  required:
                  - limit
                  - used
                  - remaining
                  additionalProperties: {}
                - type: 'null'
            required:
            - id
            - name
            - role
            - pays
            - credits
            - memberBudget
            additionalProperties: {}
          - type: 'null'
        tier:
          type: string
          enum:
          - discovery
          - payg
          - business
        tierName:
          type: string
        credits:
          type: object
          properties:
            used:
              type: number
            limit:
              anyOf:
              - type: number
              - type: 'null'
            remaining:
              anyOf:
              - type: number
              - type: 'null'
            purchased:
              type: number
            exhausted:
              type: boolean
            unlimited:
              type: boolean
            unlimitedReason:
              anyOf:
              - type: string
                enum:
                - admin
                - dev
              - type: 'null'
          required:
          - used
          - limit
          - remaining
          - purchased
          - exhausted
          - unlimited
          - unlimitedReason
          additionalProperties: {}
        meters:
          type: object
          properties:
            voice:
              type: object
              properties:
                meter:
                  type: string
                  const: voice
                window:
                  type: string
                  enum:
                  - balance
                  - period
                resetAt:
                  anyOf:
                  - type: string
                  - type: 'null'
                used:
                  type: number
                limit:
                  anyOf:
                  - type: number
                  - type: 'null'
                remaining:
                  anyOf:
                  - type: number
                  - type: 'null'
                exhausted:
                  type: boolean
                topup:
                  type: number
                unlimited:
                  type: boolean
                unlimitedReason:
                  anyOf:
                  - type: string
                    enum:
                    - admin
                    - dev
                  - type: 'null'
              required:
              - meter
              - window
              - resetAt
              - used
              - limit
              - remaining
              - exhausted
              - topup
              - unlimited
              - unlimitedReason
              additionalProperties: {}
            portage:
              type: object
              properties:
                freeLimit:
                  type: number
                used:
                  type: number
                freeRemaining:
                  type: number
                resetsAt:
                  anyOf:
                  - type: string
                  - type: 'null'
              required:
              - freeLimit
              - used
              - freeRemaining
              - resetsAt
              additionalProperties: {}
          required:
          - voice
          - portage
          additionalProperties: {}
      required:
      - organization
      - tier
      - tierName
      - credits
      - meters
      additionalProperties: {}
  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.'
  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.'


# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/kaneme-com/openapi/kaneme-com-compte-api-openapi.yml