API Kanera

L'API publique de Kanera vous permet de créer des intégrations autour du même travail que votre équipe gère dans l'application : espaces de travail, tableaux, cartes, listes, séparateurs de tableaux, commentaires, listes de contrôle, notes, pièces jointes, étiquettes, champs personnalisés, devoirs, files d'attente classées suivantes, activités et liens externes.

Utilisez l'API lorsque Kanera doit se connecter à un autre système, alimenter un flux de travail interne, migrer des données, créer des rapports ou laisser un autre outil créer et mettre à jour Kanera.

Ce que vous pouvez construire

Les cas d'utilisation courants de l'API incluent :

Synchronisez les cartes Kanera avec un autre tracker de travail.
Créez des cartes à partir de formulaires, de tickets d'assistance, de messages de discussion ou d'enregistrements CRM.
Créez des tableaux de bord de rapports personnalisés à partir de tableaux, d'affectations, d'étiquettes, de champs personnalisés et d'activités.
Importez le travail dans Kanera à partir d’un autre système.
Conservez des enregistrements externes liés aux cartes ou notes Kanera.
Ajoutez des commentaires ou des mises à jour de statut à partir d'un autre outil.
Téléchargez et joignez des fichiers à des cartes ou des notes.
Lisez l’historique des activités à des fins d’audit, de reporting ou d’automatisation.

Les intégrations Kanera peuvent cibler des tableaux ou des espaces de travail autonomes. Un tableau autonome possède ses propres listes, étiquettes et champs personnalisés. Un espace de travail partage ces ressources entre ses tableaux, ce qui facilite la cohérence des flux de travail de reporting et de synchronisation entre les tableaux.

Clients officiels

Vous n'êtes pas obligé de commencer par curl. Deux clients propriétaires incluent la même API :

Client	Installer	Utilisez-le pour
Kanera CLI	`npm install --global @kanera/cli`	Utilisation du terminal, scripts shell et agents IA pouvant exécuter des commandes.
SDK TypeScript	`npm install @kanera/sdk`	Intégrations TypeScript et JavaScript. Aucune dépendance d'exécution ; fonctionne sur Node, Bun, Deno, les travailleurs et les navigateurs.

Le SDK est sous licence MIT, donc son intégration dans votre propre application ne soulève aucune question de politique de licence. Utilisez les points de terminaison REST directement pour n’importe quelle autre langue.

Référence API

L'API REST de Kanera se trouve à :

https://api.kanera.app

Une référence détaillée au niveau des points finaux est disponible à l’adresse :

https://api.kanera.app/docs

Le service API public inclut la référence au niveau du point de terminaison :

Chemin	Utiliser
`/docs`	Référence de l'API scalaire interactive.
`/swagger`	Référence de l'interface utilisateur Swagger.
`/openapi.json`	Document OpenAPI pour la génération et les outils SDK.

Pour Kanera, ouvrez :

https://api.kanera.app/docs
https://api.kanera.app/swagger
https://api.kanera.app/openapi.json

Utilisez cette page comme guide de démarrage, puis utilisez la référence de l'API pour connaître les chemins exacts des points de terminaison, les corps de requête, les schémas de réponse et les types d'événements webhook disponibles.

Utiliser la référence du point de terminaison

Ouvert Scalaire pour la référence du critère d’évaluation principal. Chaque opération affiche sa méthode et son chemin, la portée requise, les paramètres de chemin et de requête, le schéma de demande, le schéma de réponse et les réponses d'erreur. Utiliser Autoriser pour fournir un jeton au porteur lorsque vous souhaitez tenter une demande.

Utiliser Interface utilisateur Swagger lorsque vos outils ou flux de travail sont construits autour de Swagger. Télécharger OuvrirAPI JSON pour la génération du SDK, la validation des demandes ou l'importation de l'API dans un autre client.

Le document OpenAPI est la source de vérité. Copiez un exemple de la référence plutôt que de deviner le corps d'une requête et testez les opérations d'écriture ou de suppression sur l'espace de travail prévu avant de les automatiser.

Groupes de points de terminaison

Groupe	Opérations typiques
Espaces de travail et tableaux	Découvrez des travaux accessibles, ouvrez l'état complet du tableau, gérez les membres et les invités, et créez ou réorganisez des tableaux.
Listes, séparateurs et cartes	Créez, mettez à jour, positionnez, déplacez, complétez, archivez, dupliquez et modifiez en masse des travaux.
Notes et pièces jointes	Créez des notes imbriquées, gérez les verrous et les backlinks, téléchargez des fichiers directement ou via un lien de téléchargement unique et lisez les octets d'une pièce jointe.
Bloc-notes	Lisez les pages privées du Bloc-notes de l'appelant et capturez des tâches rapides dans une page de boîte de réception. Informations d'identification personnelles uniquement.
Champs et étiquettes	Gérez les champs personnalisés, les options et les étiquettes de cartes réutilisables au niveau de l'espace de travail.
Commentaires et activité	Lisez les flux de cartes, rédigez des commentaires et des réactions et examinez l'activité du tableau.
Prochaines priorités	Découvrez des files d'attente lisibles, répertoriez l'ordre des équipes et ajoutez, déplacez ou supprimez des cartes classées.
Suite	Regardez ou arrêtez de regarder des cartes et des tableaux, définissez, effacez ou répertoriez vos rappels de cartes privées et interrogez votre boîte de réception de notifications. Informations d'identification personnelles uniquement.
L'agent s'exécute	Annoncez qu'un agent travaille sur une carte, battez-vous pendant son exécution et enregistrez comment cela s'est terminé.
Recherche et liens externes	Recherchez du contenu accessible et maintenez des mappages idempotents avec des enregistrements dans d'autres systèmes.
Webhooks	Enregistrez et gérez les points de terminaison, inspectez ou réessayez les livraisons et recevez des événements de modification signés sans interrogation.

Choisissez un type de clé API

Kanera propose deux types de clés API. Ils s'authentifient de la même manière, mais leur modèle d'accès est différent.

Type de clé	Créez-le à partir de	Utilisez-le quand	Modèle d'accès
Clé API personnelle	Paramètres du profil -> Clés API	Vous connectez votre propre client script, CLI ou MCP et souhaitez qu'il fonctionne sur tous les tableaux auxquels vous pouvez accéder personnellement.	Agit comme vous, dans chaque espace de travail et tableau auquel vous pouvez accéder, en respectant votre rôle au sein de chaque tableau. C'est Lire ou Écrire la portée limite ce qu’elle peut faire dans le cadre de cet accès. Il ne peut pas effectuer d'actions d'administrateur d'espace de travail.
Clé API de l'espace de travail ou du tableau	Paramètres de l'espace de travail -> API ou Paramètres du tableau -> API	Vous configurez une intégration d'équipe, un compte de service, un producteur de webhook, une tâche de synchronisation ou une automatisation pour un espace de travail ou un tableau autonome.	Adapté à cet espace de travail ou à ce tableau autonome. C'est Lire, Écrire, ou Administrateur scope contrôle ce que l’intégration peut faire.

Utilisez une clé personnelle pour les flux de travail appartenant à l'utilisateur. Utilisez un espace de travail limité ou une clé de tableau pour les intégrations partagées ou de production qui doivent être détenues, alternées et auditées avec la destination.

Exigences du plan

Les clés API personnelles et les connexions interactives des agents IA fonctionnent sur chaque plan, y compris hébergé gratuitement. Ils agissent comme un utilisateur présent, ils accèdent donc exactement aux tableaux que l'utilisateur peut ouvrir, aussi bien dans les organisations gratuites que professionnelles.

Clés API de l'espace de travail et du tableau, agents de service OAuth sans surveillance, webhooks et destinations de discussion nécessaires Pro ou les 30 jours Essai professionnel. Ils s'exécutent au nom de l'organisation sans que personne ne soit connecté, ils ne sont donc pas disponibles sur Free hébergé, où la page des paramètres de l'espace de travail l'explique au lieu d'afficher le formulaire de création. Demandes bloquées par un retour de limite de plan 403 avec le code erreur PLAN_LIMIT, une intégration peut donc distinguer un problème de plan d'un problème d'autorisation.

Création de clés API d'espace de travail ou de tableau, de clients OAuth et de destinations de discussion administrateur de l'espace de travail autorisation. Les administrateurs gèrent également chaque point de terminaison de webhook dans un espace de travail ; un identifiant API compatible en écriture ou un agent OAuth interactif peut enregistrer des points de terminaison étendus à sa propre connexion lorsque son utilisateur est membre de l'espace de travail. Les clés API personnelles ne nécessitent pas de création de rôle dans l'espace de travail.

La porte ne concerne pas seulement la création. Lorsqu'une organisation hébergée migre vers Free, Kanera révoque ses clés API d'espace de travail et de tableau actives, ce qui désactive également les agents de service OAuth construits sur celles-ci, et /api/v1 les rejette au moment de la demande, donc une clé qui survit ailleurs ne peut toujours pas être utilisée. Les clés API personnelles et les connexions d'agents interactifs continuent de fonctionner. Les points de terminaison Webhook et les destinations de discussion sont suspendus par la même rétrogradation. La mise à niveau vers Pro restaure les clés et les points de terminaison touchés par la rétrogradation.

Limites de taux

Les requêtes provenant de clés API et d'agents IA, sur REST et MCP, sont limitées par utilisateur, dans les limites du forfait de l'organisation propriétaire du tableau auquel vous accédez :

Organisation du tableau	Par seconde	Par minute
Hébergé gratuitement	5	60
Pro hébergé ou essai Pro	20	400
Auto-hébergé	20	400 (configurable)

Un utilisateur qui appartient à la fois à une organisation Free et Pro obtient les limites de chaque organisation sur ses propres forums. Les demandes dépassant la limite ne sont pas immédiatement refusées : jusqu'à 10 personnes attendent dans une file d'attente, pendant 10 secondes maximum, et sont servies comme libérations de capacité. Seules les demandes au-delà de cette file d'attente reçoivent 429 avec un Retry-After en-tête. Le serveur CLI, SDK et MCP s'arrête et réessaye automatiquement.

Les opérateurs auto-hébergés peuvent modifier les limites avec PUBLIC_API_KEY_RATE_LIMIT_PER_SECOND, PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE, PUBLIC_API_RATE_LIMIT_QUEUE_SIZE, et PUBLIC_API_RATE_LIMIT_QUEUE_MAX_WAIT_MS. Voir Webhooks pour le comportement de déclassement complet.

Créer une clé API personnelle

Ouvert Paramètres du profil.
Aller à Clés API onglet.
Créez une clé API personnelle.
Choisissez Lecture seule ou Lire et écrire.
Ajoutez une étiquette privée facultative afin que vous puissiez reconnaître où la clé est utilisée.
Copiez le secret lorsqu'il est affiché.

Les clés personnelles sont toujours liées à l'utilisateur qui les a créées. Ils suivent l'accès et le rôle réels du propriétaire au tableau, et l'activité apparaît en tant que propriétaire. Il n'y a pas de portée administrateur : une clé personnelle ne peut jamais effectuer l'administration de l'espace de travail, quel que soit le rôle de son propriétaire.

Clés personnelles en lecture seule

Une clé personnelle est lire et écrire sauf si vous en décidez autrement, c'est ce que vous offre une clé existante ou un flux de création inchangé.

Choisissez Lecture seule lorsque les informations d'identification vont quelque part, vous ne regarderez pas : un agent IA, un travail de reporting, une vérification CI, un tableau de bord. Une clé en lecture seule peut répertorier, lire, rechercher et signaler, et Kanera refuse chaque mutation avec 403 et le code erreur FORBIDDEN. Étant donné que le refus se produit au niveau de l'API plutôt que chez le client, un agent qui se comporte mal ou qui a reçu une injection rapide ne peut toujours pas modifier votre travail.

La portée est fixée lors de la création de la clé. Pour la modifier, créez une nouvelle clé et révoquez l'ancienne.

Le secret est révélé une fois. Stockez-le dans votre gestionnaire de secrets local, la configuration du client MCP ou vos variables d'environnement.

Créer une clé API d'espace de travail ou de tableau

Ouvrez l'espace de travail ou le tableau autonome.
Aller à Paramètres de l'espace de travail -> API ou Paramètres du tableau -> API.
Créez une clé API d'espace de travail.
Choisissez la plus petite portée qui correspond à l'intégration.
Copiez le secret lorsqu'il est affiché.

Les clés API de l'espace de travail sont limitées à l'espace de travail. Une clé ne peut accéder qu'aux ressources de l'espace de travail où elle a été créée et où son créateur a toujours accès.

Le secret est révélé une fois. Stockez-le dans le gestionnaire de secrets ou les variables d'environnement de votre intégration.

Portées des clés de l'API Workspace

Portée	Utilisez-le quand
Lire	L'intégration n'a besoin que de lire, rechercher, rapporter ou exporter des données Kanera.
Écrire	L'intégration doit créer ou mettre à jour des travaux, tels que des cartes, des commentaires, des étiquettes, des destinataires, des valeurs de champs personnalisés, des notes ou des pièces jointes.
Administrateur	L'intégration nécessite des opérations d'API publique au niveau de l'administrateur lorsqu'elles sont prises en charge. Utilisez-le avec parcimonie.

Lire, Écrire, et Administrateur s'appliquent aux clés de l'espace de travail et du tableau. Clés personnelles, choisissez entre Lire et Écrire uniquement, et hérite toujours des autorisations du propriétaire au niveau du tableau en plus de cela.

Utilisez des clés API distinctes pour des intégrations distinctes. Cela facilite la révocation, la rotation et l’audit de l’accès. Pour les systèmes partagés, préférez les clés d'espace de travail afin que l'accès ne soit pas lié aux outils personnels d'une seule personne.

Authentification

Envoyez la clé API sous forme de jeton de porteur :

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer kanera_live_..."

Les clés API Kanera utilisent des préfixes pour l'environnement :

Préfixe	Environnement
`kanera_live_...`	Fabrication
`kanera_stg_...`	Mise en scène
`kanera_dev_...`	Développement
`kanera_test_...`	Tester

Les clés personnelles portent un u marqueur après le préfixe du fournisseur, donc kanera_u_live_... est une clé personnelle et kanera_live_... est une clé d'espace de travail ou de tableau. Les deux s’authentifient de la même manière.

Retour de clés manquantes ou invalides 401. Clés valides sans autorisation pour un retour de ressource ou d'opération 403 - y compris une tentative d'écriture avec une clé de portée lecture.

OAuth pour les agents IA

Kanera prend en charge OAuth 2.0 afin qu'un agent IA compatible puisse se connecter à Kanera MCP via le consentement du navigateur ou une connexion de service au lieu de stocker une clé API.

Une connexion OAuth est destinée à MCP ; il ne s'agit pas d'un identifiant API grand public. Utilisez une clé API personnelle, d'espace de travail ou de tableau lorsque votre propre intégration doit appeler /api/v1 directement.

Il existe trois chemins OAuth :

Agents interactifs utilisez le flux de code d’autorisation avec PKCE. Une personne approuve la connexion une fois dans le navigateur et l'agent agit en tant qu'utilisateur. C'est ainsi que les clients MCP compatibles tels que Claude, ChatGPT, Copilot et Codex se connectent sans clé API.
Clients d'appareil utiliser l'octroi d'autorisation d'appareil (urn:ietf:params:oauth:grant-type:device_code). Le client affiche un code court, une personne l'approuve dans un navigateur sur n'importe quel appareil et le client recherche des jetons. Utilisez-le pour un client CLI ou sans tête qui ne peut pas recevoir de redirection de navigateur. Voir le référence d'autorisation de l'appareil.
Agents sans surveillance utiliser le client_credentials subvention. Vous créez un identifiant client et un secret dans Paramètres de l'espace de travail -> API et échangez-les contre des jetons de courte durée, sans étape de navigateur. Utilisez-les pour les agents CI, cron ou côté serveur.

Voir Connecter un agent IA pour la configuration, les étendues et la gestion des connexions. Les auteurs de clients OAuth personnalisés peuvent trouver les détails du protocole dans le Référence technique MCP.

URL de base et gestion des versions

Les points de terminaison REST vivent sous /api/v1 sur le service API public.

Par exemple :

https://api.kanera.app/api/v1/workspaces

Chemins d'assistance opérationnels tels que /docs, /swagger, /openapi.json, les URL de médias signés et la découverte d'événements webhook peuvent résider en dehors du /api/v1 préfixe. Traitez les URL de médias signées renvoyées par l'API comme des URL opaques et utilisez-les comme prévu.

Premières demandes

Vérifiez à qui appartient l'identifiant. GET /api/v1/session renvoie l'utilisateur, l'organisation, le type d'identifiant et scope (read signifie que toute modification est refusée), plus l'avis de l'utilisateur timeZone et today, la date actuelle dans cette zone, afin qu'un client puisse résoudre « aujourd'hui » ou « demain » de la même manière que Kanera tamponne les dates d'échéance :

curl "$KANERA_PUBLIC_API_URL/api/v1/session" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Répertoriez les espaces de travail auxquels la clé API peut accéder :

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Répertoriez ensuite les tableaux dans un espace de travail :

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces/$WORKSPACE_ID/boards" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Ouvrez un tableau pour obtenir le tableau, les listes d'espaces de travail, les séparateurs de tableau, les cartes visibles, les membres, les étiquettes et les champs personnalisés nécessaires au rendu ou à la synchronisation du travail :

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/open" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY"

Créez une carte :

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/cards" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Follow up with Acme"}'

Une création peut également définir labelIds, assigneeIds, dueDateLocalDate (YYYY-MM-DD), et dueDateSlot dans la même écriture, la carte arrive donc entièrement décrite et ses automatisations d'étiquettes s'exécutent une seule fois.

Créez plusieurs cartes à la fois, jusqu'à 50 par demande sur un seul tableau. Chaque carte nomme sa propre liste et atterrit au bas de celle-ci dans l'ordre de demande :

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/cards/bulk/create" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"cards\":[{\"listId\":\"$LIST_ID\",\"title\":\"Draft the brief\",\"labelIds\":[\"$LABEL_ID\"]},{\"listId\":\"$LIST_ID\",\"title\":\"Review with legal\",\"assigneeIds\":[\"$USER_ID\"],\"dueDateLocalDate\":\"2026-11-02\"}]}"

Chaque carte est vérifiée avant qu'une autre ne soit créée, de sorte qu'une liste, une étiquette ou un destinataire inconnu rejette l'intégralité de la demande avec un 400 qui nomme l'entrée, telle que cards[1]: one or more label ids are invalid. Chaque carte déclenche ensuite les mêmes automatisations, notifications et webhooks qu'une seule création.

Les réponses des cartes incluent l'immuable workspaceId, opaque organisationKey, positif number, actuel lisible par l'homme key comme PROJ-123et un navigateur propre url. Un préfixe d’espace de travail peut changer, mais pas le numéro de carte.

Résolvez une clé de carte actuelle ou historique avant d'appeler un point de terminaison de mutation basé sur l'identifiant :

curl "$KANERA_PUBLIC_API_URL/api/v1/organisations/$ORGANISATION_KEY/cards/by-key/$CARD_KEY" \
  -H "Authorization: Bearer $KANERA_API_KEY"

La résolution n'est pas sensible à la casse et renvoie l'identifiant actuel de la carte, l'espace de travail, le tableau, la liste, le numéro, la clé et l'URL du navigateur. La clé d'organisation est la valeur opaque renvoyée par Kanera, et non un nom d'organisation ou un slug. Les cartes manquantes et inaccessibles reviennent toutes les deux 404.

Mettre à jour une carte :

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Imported from CRM"}'

Ajouter un commentaire :

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/comments" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Customer confirmed the rollout window."}'

Remplacez les étiquettes ou les destinataires de la carte par un ensemble exact :

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/labels" \
  -X PUT \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"labelIds\":[\"$LABEL_ID\"]}"

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/assignees" \
  -X PUT \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"userIds\":[\"$USER_ID\"]}"

Ces deux PUT les opérations remplacent l’ensemble. Envoyez un tableau vide pour l'effacer ; utilisez les opérations d'ajout/suppression en masse documentées lorsque vous avez besoin d'une sémantique de correctif sur les cartes sélectionnées.

Compléter une carte :

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/completion" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

Gérer les séparateurs de cartes

Un séparateur est un élément appartenant au tableau, intitulé et éventuellement coloré dans la voie de commande mixte de cartes et de séparateurs d'une liste de flux de travail. Créez-en un à une ancre typée exactement :

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/separators" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"This week\",\"color\":\"blue\",\"beforeItem\":{\"type\":\"card\",\"id\":\"$CARD_ID\"}}"

Mettez à jour son titre ou sa couleur avec PATCH /api/v1/separators/{id}, déplace-le avec POST /api/v1/separators/{id}/move, et supprimez-le avec DELETE /api/v1/separators/{id}. Déplacer les corps, nommer la destination listId et fournissez exactement un beforeItem ou afterItem; l'article peut être un { "type": "card", "id": "..." } ou { "type": "separator", "id": "..." } référence. Un null afterItem signifie le haut et un null beforeItem signifie le fond. La suppression d'un séparateur laisse les cartes inchangées.

Gérer la prochaine commande

L'API expose les mêmes files d'attente classées que celles utilisées par Accueil, Mes cartes et Cartes d'équipe :

Point de terminaison	Utiliser
`GET /api/v1/work/priority-targets`	Répertoriez les utilisateurs dont les informations d'identification peuvent lire les files d'attente.
`GET /api/v1/work/priorities`	Lisez chaque file d'attente autorisée en une seule réponse.
`GET /api/v1/work/priorities/{userId}`	Lisez une file d'attente par ordre de classement.
`POST /api/v1/work/priorities/{userId}/cards`	Ajoutez une carte active attribuée à une position ancrée.
`POST /api/v1/card-priorities/{id}/move`	Déplacez une entrée de file d’attente avant ou après une autre entrée visible.
`DELETE /api/v1/card-priorities/{id}`	Supprimez l'entrée sans changer la carte.

Les informations d'identification personnelles peuvent toujours lire leur propre file d'attente. La lecture de la file d'attente d'une autre personne nécessite une autorité d'administrateur efficace dans un espace de travail partagé, et les écritures nécessitent également des informations d'identification capables d'écrire ainsi que des autorisations pour la carte cible. Utilisez les identifiants d'entrée renvoyés par la file d'attente comme ancres de déplacement ; les rangs sont des valeurs de présentation, pas des identifiants de mutation.

Joindre et lire des fichiers

POST /api/v1/cards/{id}/attachments effectue un téléchargement en plusieurs parties. Lorsque le fichier se trouve dans un endroit à partir duquel l'appelant ne peut pas diffuser directement, comme le bac à sable d'un agent IA, créez plutôt un lien de téléchargement unique et PUT les octets bruts:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/MKT-42/attachments/upload-links" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"test-run.log"}'

# The response includes uploadUrl; no Authorization header is needed for the upload itself.
curl -fsS -T ./test-run.log "$UPLOAD_URL"

Le lien fonctionne une fois, expire au bout de 15 minutes et cesse de fonctionner si la clé qui l'a créé est révoquée.
Kanera stocke le fichier sous le nom et le type enregistrés lors de la création du lien, déduisant le type de l'extension lorsque vous omettez mimeType. Fichiers journaux (.log, .out, .jsonl, et similaires) sont stockés sous forme de texte brut.
La création d'un lien nécessite un identifiant capable d'écrire et un accès éditeur à la carte. Les limites de stockage sont vérifiées à la fois lors de la création du lien et à l'arrivée du fichier.
La réponse de téléchargement est la nouvelle pièce jointe, et toute personne regardant la carte la voit apparaître immédiatement.

Lire les octets d'une pièce jointe avec GET /api/v1/cards/{id}/attachments/{attachmentId}/content. Il prend en charge Range demandes, et ?variant=cover (jusqu'à 1200px) ou ?variant=thumbnail (400px) renvoie les copies JPEG effectuées par Kanera à partir d'images PNG, JPEG, GIF et WebP.

Capturer dans le Bloc-notes

POST /api/v1/scratchpad/capture ajoute une tâche ouverte au privé de l'appelant Bloc-notes, sur la première page intitulée pageTitle (par défaut Inbox), et crée la page lorsqu'elle est manquante :

curl "$KANERA_PUBLIC_API_URL/api/v1/scratchpad/capture" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Renew the venue insurance"}'

GET /api/v1/scratchpad/notes répertorie chaque page avec son contenu, et PATCH /api/v1/scratchpad/notes/{id} remplace une page. Passez le updatedAt tu lis comme baseUpdatedAt recevoir 409 SCRATCHPAD_STALE au lieu d'écraser les modifications apportées depuis. Le Scratchpad appartient à une seule personne, les clés API de l'espace de travail reçoivent donc 403; utilisez une clé personnelle ou une connexion OAuth.

Regardez les cartes et définissez des rappels

Le Suite les points de terminaison gèrent les propres abonnements de l'appelant, de sorte que les clés API de l'espace de travail reçoivent 403; utilisez une clé personnelle ou une connexion OAuth. Leur modification nécessite un identifiant capable d'écrire, mais uniquement un accès en lecture à la carte.

Point de terminaison	Utiliser
`GET /api/v1/cards/{id}/follow`	Que vous regardiez la carte et votre rappel dessus.
`PUT` / `DELETE /api/v1/cards/{id}/watch`	Regardez ou arrêtez de regarder une carte. Renvoie le même état que `follow`.
`PUT` / `DELETE /api/v1/boards/{id}/watch`	Regardez ou arrêtez de regarder un tableau.
`PUT /api/v1/cards/{id}/reminder`	Définissez votre rappel : `{"remindAt": "2026-10-16T15:00:00+01:00"}`.
`DELETE /api/v1/cards/{id}/reminder`	Effacez votre rappel.
`GET /api/v1/reminders`	Vos rappels en attente, le plus tôt possible. `?status=all` inclut ceux qui ont déjà tiré.
`GET /api/v1/notifications`	Interrogez votre boîte de réception de notification à partir d'un curseur. Voir ci-dessous.

remindAt est un instant ISO avec un décalage, dans le futur et au maximum 56 jours (huit semaines) à l'avance. Vous détenez un rappel par carte, donc le réinitialiser le remplace et le réarme. Vos autres sessions ouvertes sont mises à jour immédiatement. Ni la surveillance ni les rappels n'apparaissent dans l'activité de la carte. Voir Rappels.

GET /api/v1/notifications est destiné à un script ou à un agent qui ne peut pas recevoir de webhooks, comme celui exécuté sur un ordinateur portable. Il renvoie les mêmes lignes que votre tiroir de notifications (réponses, mentions, devoirs et modifications sur les cartes que vous regardez ou qui sont attribuées), les plus anciennes en premier. Appelez-le une fois sans since pour les dernières lignes, puis transmettez le code de chaque réponse cursor de retour comme since, en répétant pendant hasMore est true, pour obtenir uniquement ce qui est nouveau. Chaque ligne porte une seule ligne summary, le card clé et URL, le actor, et un commentExcerpt pour les commentaires. Les lignes apparaissent quelques secondes après l'événement. Une connexion d'agent IA ne voit pas les notifications provoquées par ses propres écritures, sauf si vous ajoutez includeSelf=true, et les sondages ne marquent jamais rien de lu.

Suivre le travail en vol d'un agent

Lorsque l'appelant est un agent IA plutôt qu'un travail de synchronisation, il peut annoncer le travail qu'il effectue sur une carte. Kanera affiche ensuite une puce en direct sur la vignette de la carte, répertorie le parcours en détail et enregistre les lignes d'activité de la carte pour le début et la fin - afin qu'une personne puisse voir que quelque chose se passe et qui le fait, sans attendre le résultat.

Point de terminaison	Utiliser
`POST /api/v1/cards/{cardId}/agent-runs`	Commencez une course. Le corps prend `title` (obligatoire), `summary`, et `externalUrl`.
`GET /api/v1/cards/{cardId}/agent-runs`	Répertoriez les courses d'une carte. Vivez uniquement par défaut ; passer `includeEnded=true` pour l'histoire, le plus récent en premier.
`GET /api/v1/agent-runs/{id}`	Lisez une exécution.
`PATCH /api/v1/agent-runs/{id}`	Mettez à jour, battez le cœur ou terminez une exécution. Chaque champ est facultatif, donc `{}` est un simple battement de cœur.

Commencez la course et gardez le id de la réponse :

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/agent-runs" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Implementing OAuth refresh","externalUrl":"https://github.com/acme/api/pull/482"}'

Ensuite, signalez les progrès et clôturez-le :

curl "$KANERA_PUBLIC_API_URL/api/v1/agent-runs/$RUN_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"succeeded","summary":"Merged in PR 482; realtime suite green."}'

Les statuts sont running, blocked, succeeded, failed, cancelled, et stalled:

running et blocked sont les deux états vivants. Utiliser blocked pendant que l'agent attend une personne, comme une question ou une approbation ; la puce de la carte devient orange.
succeeded, failed, et cancelled sont terminaux. Un statut de terminal met fin à l'exécution et la rend immuable, donc plus tard PATCH retours 409 avec message: agent run has already ended.
stalled est défini par Kanera, et non par vous, lorsqu'une exécution en direct arrête de battre pendant quinze minutes, de sorte qu'un agent en panne ne peut pas laisser indéfiniment une carte indiquant "fonctionner". Une exécution bloquée n'est pas terminée : l'agent peut toujours la clôturer avec un statut de terminal, ou définir running pour reprendre.

Chaque PATCH rafraîchit le rythme cardiaque, dont un qui ne change rien, alors envoyez un puits de maintien dans la fenêtre de quinze minutes sur un travail long. Démarrage ou mise à jour d'un tableau des besoins d'exécution Éditeur accès et un identifiant capable d'écrire, exactement comme n'importe quelle autre carte d'écriture. Les courses émettent également le agentRun:started et agentRun:updated événements de webhooks.

Un agent connecté via OAuth est enregistré comme l'agent agissant pour son utilisateur : ses exécutions, ses commentaires et ses lignes d'activité portent le nom de l'agent, et la personne pour laquelle il agit est informée de ce qu'elle a fait. Une clé API personnelle utilisée par votre propre script agit toujours en tant que propriétaire.

Enregistrer un webhook à partir d'une intégration

Les administrateurs de Workspace peuvent gérer chaque point de terminaison de webhook générique. Un identifiant API non-administrateur compatible en écriture ou un agent OAuth interactif peut également en créer un lorsque son utilisateur appartient à l'espace de travail ; Kanera marque ce point final scope: "connection", et seuls les mêmes administrateurs de connexion et d’espace de travail peuvent le répertorier ou le gérer. Cela permet à un agent de s'abonner aux événements du forum sans recevoir l'autorité d'administrateur de l'espace de travail.

Utiliser POST /api/v1/workspaces/{workspaceId}/webhooks pour créer le point de terminaison et enregistrer le point unique secret de la réponse. La même ressource expose les opérations de liste, de mise à jour, de suppression, de rotation des secrets, d’historique de remise et de nouvelle tentative de remise en cas d’échec. Voir Webhooks pour la carte des points de terminaison et les règles de signature.

Un flux d'intégration fiable

Appeler GET /api/v1/workspaces ou GET /api/v1/boards pour découvrir uniquement les ressources auxquelles les informations d'identification peuvent accéder.
Utiliser POST /api/v1/boards/{id}/open lorsque vous avez besoin du tableau ainsi que de ses listes, cartes, membres, étiquettes et champs personnalisés en une seule réponse.
Stocke les identifiants renvoyés pour les mutations d’API. Les noms sont modifiables ; une clé de carte lisible par l'homme peut être résolue en identifiant de carte actuel lorsqu'une personne ou un enregistrement externe en fournit un.
Validez les corps d'écriture par rapport au schéma d'opération en Scalar ou OpenAPI.
Traiter 401 comme authentification invalide, 403 comme un accès insuffisant ou un portail en plan, 404 comme données manquantes ou inaccessibles, 409 comme un conflit d'État, et 429 comme un signal de recul.
Enregistrez la réponse x-request-id dans les journaux d'intégration sans enregistrer les informations d'identification ou le contenu sensible.

Relations avec les cartes

Les relations relient les cartes dans le même espace de travail, y compris entre ses tableaux. direction lit à partir de la carte dans le chemin : blocks signifie que cette carte bloque la cible, blocked_by signifie que la cible bloque cette carte, et relates_to n'a pas d'ordre requis.

Méthode et chemin	Objectif
`GET /api/v1/cards/{cardId}/relations`	Lire les relations visibles et `hiddenBlockerCount`.
`POST /api/v1/cards/{cardId}/relations`	Ajouter `{ "targetCardId": "<UUID>", "direction": "blocked_by" }`.
`DELETE /api/v1/cards/{cardId}/relations/{relationId}`	Supprimez une relation par son ID.

Les détails de la carte comprennent relations et hiddenBlockerCount; les résumés de cartes exposent blockedByCount. Une carte active est bloquée alors qu'au moins un prérequis est incomplet et non archivé. Utiliser filters: { blockedOnly: true } avec POST /api/v1/work/cards/query pour restituer uniquement les cartes ouvertes bloquées, ou atRiskOnly: true pour les cartes ouvertes dont le bloqueur visible est en retard ou dû après elles. POST /api/v1/work/portfolio/query retours blocked et atRisk compte par tableau et dans ses totaux.

L'ajout d'une relation existante est idempotent. Les auto-liens, les liens entre espaces de travail, les cycles de dépendance et une carte complétée en tant que nouveau bloqueur sont rejetés. Les écritures nécessitent un accès en modification à la carte de chemin et à la carte bloquée, ainsi qu'un accès en lecture à l'autre carte. Les relations inaccessibles sont omises des lectures ; leurs bloqueurs actifs contribuent uniquement à hiddenBlockerCount.

La suppression du dernier bloqueur actif peut exécuter des automatisations et envoyer des notifications de transfert. La réouverture ou la restauration d'un bloqueur peut bloquer à nouveau la carte. La réalisation via l'API reste disponible sans l'avertissement interactif de l'application Web. Voir Relations avec les cartes et blocage pour le comportement du cycle de vie.

Graphiques de dépendance

POST /api/v1/cards/dependency-graph lit le graphique derrière la vue Dépendances. Transmettez exactement une portée :

{ "boardId": "<board UUID>" }

Alternativement, passez { "workspaceId": "<workspace UUID>" } ou { "cardIds": ["<card UUID>"] }. Une étendue d’identification de carte accepte 1 à 2 000 UUID. Ce POST est une lecture sans effets secondaires.

La réponse contient des résumés compacts de cartes, des bords, des recherches de tableau/liste/étiquette/personnes, des champs personnalisés au recto de la carte et truncated. Chaque carte ajoute inScope et son canonique url. Chaque tableau comprend canEdit pour l'autorité de modification des dépendances de l'appelant. Un blocks le bord part de sourceCardId (la condition préalable) pour targetCardId (la personne à charge); relates_to est symétrique.

La marche commence à partir de cartes de portée ouvertes et non archivées avec des relations, suit les bords de blocage dans les deux sens à travers des tableaux lisibles et s'arrête aux cartes terminées. Les voisins associés sont inclus à un saut des graines. Les cartes inaccessibles sont omises ; blockedByCount compte toujours leurs bloqueurs actifs. Le graphique s'arrête à 400 cartes et ensembles truncated: true; restreindre la portée lorsqu’une chaîne complète est nécessaire. Les informations d’identification de l’espace de travail restent dans leur espace de travail.

Voir Vue Dépendances pour savoir comment l'application présente et modifie ces données. MCP renvoie une projection étendue orientée agent plutôt que ces résumés compacts.

Modèle de tableau et d'espace de travail

L'API de Kanera représente les deux modèles destinés à l'utilisateur :

Un espace de travail standard contient plusieurs tableaux.
Une carte autonome est renvoyée avec kind: "board" par des points de terminaison qui exposent son conteneur de support, mais les utilisateurs le vivent comme une carte indépendante.
Les tableaux contiennent des cartes.
Les listes, les étiquettes et les champs personnalisés appartiennent uniquement à un tableau autonome ou sont partagés sur tous les tableaux d'un espace de travail standard.
Les points de terminaison d’attribution peuvent renvoyer les cartes attribuées à tous les tableaux de l’espace de travail.
Les tableaux privés ne sont visibles que là où la clé API a accès.
Une clé personnelle peut voir les tableaux dans les espaces de travail auxquels son propriétaire a accès.
Une clé d'espace de travail ne peut voir les tableaux qu'à l'intérieur de son espace de travail.

Ceci est important lors de la création d’intégrations. Utilisez une carte autonome lorsque son schéma doit rester indépendant. Dans un espace de travail, réutilisez les listes et les champs existants afin que les rapports, les requêtes d'affectation et l'agrégation des champs personnalisés restent cohérents. L'interface utilisateur de Global Work peut couvrir tous les tableaux auxquels la personne connectée peut accéder, tandis qu'une clé API d'espace de travail reste limitée à son seul espace de travail.

Pagination et erreurs

Répertoriez les points de terminaison qui prennent en charge l'utilisation de la pagination :

Paramètre	Signification
`limit`	Nombre d'enregistrements à renvoyer.
`before`	Filtre de style curseur pour les enregistrements avant un horodatage.

Les erreurs renvoient JSON avec :

Champ	Signification
`code`	Code d'erreur stable.
`message`	Message d'erreur lisible par l'homme.
`issues`	Détails de validation facultatifs.

Utilisez le code d'état HTTP et le code d'erreur ensemble pour décider de réessayer, de corriger la saisie ou de demander à un administrateur de mettre à jour l'accès.

Webhooks

Les webhooks permettent aux systèmes externes de réagir lorsque le travail change dans Kanera. Voir Webhooks pour la configuration, la vérification de la livraison et la liste complète des types d'événements webhook pris en charge.

Si l'objectif est de publier l'activité des cartes dans un canal de discussion d'équipe, vous n'avez rien à créer : utilisez Destinations de discussion pour Slack, Discord, Telegram ou Zulip.

Liens externes

Les liens externes permettent aux intégrations de stocker des mappages durables entre les enregistrements Kanera et les enregistrements d'un autre système.

Utilisez des liens externes lorsque vous avez besoin que les tâches de synchronisation soient idempotentes. Par exemple, une synchronisation Trello peut mémoriser quelle carte Kanera correspond à quelle carte Trello sans mettre de métadonnées d'intégration cachées dans la description de la carte.

Recommandations de sécurité

Utilisez une clé API par intégration.
Utilisez la portée la plus basse qui fonctionne.
Stockez les clés et les secrets des webhooks dans un gestionnaire de secrets.
Faites pivoter les clés et les secrets des webhooks lorsque des personnes partent ou que les systèmes changent.
Ne placez pas de clés API dans Scratchpad, Notes, cartes, commentaires, contrôle de code source, journaux ou captures d'écran.
Vérifiez les signatures des webhooks avant de traiter les charges utiles.
Rendre les gestionnaires de webhooks idempotents, car les livraisons peuvent être réessayées.
Enregistrez suffisamment d'ID de requête et d'événement pour déboguer le comportement de synchronisation sans enregistrer de secrets.

Ce que vous pouvez construire​

Clients officiels​

Référence API​

Utiliser la référence du point de terminaison​

Groupes de points de terminaison​

Choisissez un type de clé API​

Exigences du plan​

Limites de taux​

Créer une clé API personnelle​

Clés personnelles en lecture seule​

Créer une clé API d'espace de travail ou de tableau​

Portées des clés de l'API Workspace​

Authentification​

OAuth pour les agents IA​

URL de base et gestion des versions​

Premières demandes​

Gérer les séparateurs de cartes​

Gérer la prochaine commande​

Joindre et lire des fichiers​

Capturer dans le Bloc-notes​

Regardez les cartes et définissez des rappels​

Suivre le travail en vol d'un agent​

Enregistrer un webhook à partir d'une intégration​

Un flux d'intégration fiable​

Relations avec les cartes​

Graphiques de dépendance​

Modèle de tableau et d'espace de travail​

Pagination et erreurs​

Webhooks​

Liens externes​

Recommandations de sécurité​

Pages connexes​