Kaneme Projets API

openapi: 3.2.0
info:
  title: Kaneme Projets 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: Projets
paths:
  /api/v1/projects:
    get:
      operationId: listProjects
      summary: Liste tes projets — pour savoir où ranger
      tags:
      - Projets
      x-kaneme-credits: '0'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:read
      x-kaneme-risk: read
      x-kaneme-mcp-tool: list_projects
      x-kaneme-timeout-seconds: 15
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: number
        description: Taille de page (max 100).
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Curseur de pagination rendu par l’appel précédent. Un curseur illisible est une ERREUR, jamais un retour au début — sans quoi l’appelant boucle sur la première page en croyant avancer.
      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/ProjectList'
        '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'
    post:
      operationId: createProject
      summary: Crée un projet (mémoire de marque) relié à une voix
      tags:
      - Projets
      x-kaneme-credits: '0'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:write
      x-kaneme-risk: write
      x-kaneme-mcp-tool: create_project
      x-kaneme-timeout-seconds: 15
      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:
                name:
                  type: string
                  description: Nom du projet.
                instructions:
                  type: string
                  description: Consignes permanentes du projet.
                context:
                  type: string
                  description: Contexte initial.
                profileId:
                  type: string
                  description: Voix visée. Par défaut, la voix active du compte.
              additionalProperties: {}
              required:
              - name
            example:
              name: Lancement Q4
              instructions: Toujours parler au « nous ». Jamais de superlatifs.
      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/ProjectCreated'
        '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/sources:
    post:
      operationId: addProjectContext
      summary: Ajoute au CONTEXTE d’un projet (recherche web, notes) — nourrit le RAG du projet
      tags:
      - Projets
      x-kaneme-credits: '1'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:write
      x-kaneme-risk: write
      x-kaneme-mcp-tool: add_project_context
      x-kaneme-timeout-seconds: 60
      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:
                projectId:
                  type: string
                  description: Projet nourri.
                text:
                  type: string
                  description: Matière versée au contexte.
                title:
                  type: string
                  description: Intitulé.
              additionalProperties: {}
              required:
              - projectId
              - text
            example:
              projectId: 3f2a91c7-58d6-4e0b-b1aa-7c9d2e4f6b10
              text: 'Notes de l’entretien client du 12/08 : le sujet qui revient est le délai de mise en route.'
              title: Entretien client — 12/08
      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/ProjectContextAdded'
        '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/projects/{projectId}/contexts:
    get:
      operationId: listProjectContexts
      summary: Liste la matière vectorisée d’un projet, active, archivée ou à la corbeille
      tags:
      - Projets
      x-kaneme-credits: '0'
      x-kaneme-credit-meter: voice
      x-kaneme-required-scope: voice:read
      x-kaneme-risk: read
      x-kaneme-mcp-tool: list_project_contexts
      x-kaneme-timeout-seconds: 15
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          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 de la ressource.
      - name: includeArchived
        in: query
        required: false
        schema:
          type: boolean
        description: Inclure les pièces archivées.
      - name: includeTrashed
        in: query
        required: false
        schema:
          type: boolean
        description: Inclure les pièces à la corbeille.
      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/ProjectContextList'
        '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:
    ProjectCreated:
      type: object
      properties:
        id:
          type: string
        workspaceId:
          type: string
        name:
          type: string
        instructions:
          anyOf:
          - type: string
          - type: 'null'
        context:
          anyOf:
          - type: string
          - type: 'null'
        profileId:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - id
      - workspaceId
      - name
      - instructions
      - context
      - profileId
      additionalProperties: {}
    ProjectContextList:
      type: object
      properties:
        projectId:
          type: string
        contexts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
              fileType:
                type: string
              sizeBytes:
                anyOf:
                - type: number
                - type: 'null'
              createdAt:
                type: string
              archivedAt:
                anyOf:
                - type: string
                - type: 'null'
              deletedAt:
                anyOf:
                - type: string
                - type: 'null'
            required:
            - id
            - title
            - fileType
            - sizeBytes
            - createdAt
            - archivedAt
            - deletedAt
            additionalProperties: {}
      required:
      - projectId
      - contexts
      additionalProperties: {}
    ProjectList:
      type: object
      properties:
        projects:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              profileId:
                anyOf:
                - type: string
                - type: 'null'
              updatedAt:
                type: string
            required:
            - id
            - name
            - profileId
            - updatedAt
            additionalProperties: {}
        nextCursor:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - projects
      - nextCursor
      additionalProperties: {}
    ProjectContextAdded:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        fileId:
          type: string
        chunksProcessed:
          type: number
        creditsUsed:
          type: number
      required:
      - ok
      - fileId
      - chunksProcessed
      - creditsUsed
      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