---
title: "L’API Partenaire Talkspirit"
description: "L’API Partenaire est un contrat REST versionné destiné à des partenaires d’intégration nommés. Elle s’authentifie à l’aide d’une clé API qu’un administrateur de votre organisation crée, et elle n’est pas ouverte à une inscription en libre-service."
category: integrations
section: api-and-webhooks
type: Reference
lastUpdated: 2026-11-16
locale: fr
canonical: https://support.talkspirit.com/fr/integrations/partner-api
---

# L’API Partenaire Talkspirit


Talkspirit expose une API REST sous un préfixe `/v1` pour qu’une intégration puisse lire les membres d’une organisation, sa structure, ses réunions, ses projets, ses objectifs et ses accords de fonctionnement, et écrire à quelques endroits précis, sans que personne n’intervienne dans l’interface Talkspirit. Chaque réponse est en JSON, et la plupart des échecs sont un document de problème RFC 7807 portant un `code` stable et exploitable par une machine. La limitation de débit et les dépassements de délai font exception : leurs corps ont une forme qui leur est propre.

C’est une API **partenaire**, pas une API publique. L’ensemble des ressources est délibérément restreint, l’accès est provisionné par intégration nommée, et il n’existe aucun portail développeur où vous pourriez vous inscrire ou générer vous-même une clé. Pour connecter un service de stockage cloud ou une autre intégration intégrée, aucun travail d’API n’est nécessaire : consultez [Comment ajouter ou supprimer une intégration ?](/fr/integrations/enable-a-cloud-file-picker).

## Ce qui doit être en place pour qu’un appel aboutisse

Deux conditions, toutes deux détenues par l’organisation Talkspirit avec laquelle vous vous intégrez :

1. **Le module API est activé sur cette organisation.** C’est un module optionnel, désactivé par défaut. Sans lui, chaque requête est rejetée avec un `401`, même si la clé est valide. Si le module est désactivé plus tard, les clés déjà émises cessent de fonctionner, après un court délai de propagation.
2. **Vous disposez d’une clé API pour cette organisation.** Un administrateur de l’organisation la crée dans l’Administration, sous Sécurité, sur la page **API**. Le support Talkspirit ne distribue pas de clés, et vous ne pouvez pas en créer depuis le côté partenaire.

Demandez à l’administrateur qui détient l’organisation d’organiser les deux. La procédure figure dans [Gérer les jetons API en tant qu’administrateur](/fr/integrations/manage-api-tokens-as-an-admin).

## Où se trouve la documentation de référence ?

L’API se documente elle-même. Le service publie, sous le même hôte que celui qui sert l’API :

- `/v1/docs`, une référence interactive rendue avec Scalar. Elle lit `/v1/openapi.json`, liste chaque opération avec ses schémas et permet d’envoyer des requêtes de test depuis la page.
- `/v1/openapi.json`, le document OpenAPI exploitable par une machine, pour générer un client.

Les deux sont consultables sans identifiant. `/v1/redoc` était auparavant une page de lecture distincte et répond désormais `301` vers `/v1/docs` : il y a donc une seule page de référence, et non deux.

Le contrat est généré depuis le service en fonctionnement et vérifié en intégration continue : il ne peut donc pas dériver de ce que l’API sert réellement. Considérez-le comme l’autorité : cet article explique la forme, la référence explique chaque champ. Il porte son propre numéro de version, distinct du chemin `/v1` : cet article a été vérifié sur la version **0.85.1**.

## Comment fonctionne l’authentification

Transmettez votre clé comme jeton bearer sur chaque requête :

```http
Authorization: Bearer <votre clé API>
```

La clé est une chaîne opaque commençant par `ts_partner_`. Talkspirit n’en stocke qu’une empreinte : la valeur complète n’est affichée qu’une fois, à la création, et ne peut pas être récupérée ensuite. Une clé perdue est remplacée, jamais retrouvée. Ne la confondez pas avec une clé MCP, qui commence par `tsk_`, que chaque membre crée dans son propre espace de compte, et qui authentifie le point de terminaison MCP distinct plutôt que cette API.

En coulisses, le service vérifie votre clé, puis l’échange contre un jeton de courte durée appartenant à un utilisateur technique dédié à votre intégration. Votre intégration voit donc exactement ce que cet utilisateur technique est autorisé à voir : les cercles, les rôles et les tableaux qui lui ont été donnés dans l’organisation, et, pour une tâche qui n’appartient à aucun projet, seulement les tâches que cet utilisateur peut voir dans le produit. Une portée sur la clé n’élargit jamais cela.

Traitez la clé comme un mot de passe. Gardez-la hors du code source, et demandez à l’administrateur de la révoquer et de la réémettre si elle est exposée. La révocation prend effet immédiatement, avec une fenêtre de tolérance d’environ cinq minutes pour un jeton déjà échangé.

## Ce que l’API expose

Soixante-huit opérations sous `/v1`, plus `GET /healthz`. Dix-sept d’entre elles écrivent ; toutes les autres lisent.

| Ressource | Points de terminaison en lecture | Portée |
| --- | --- | --- |
| Utilisateurs | `GET /v1/users`, `GET /v1/users/{user_id}`, `GET /v1/users/{user_id}/memberships` | `users:read` |
| Toutes les appartenances de l’organisation | `GET /v1/memberships` | `users:read` |
| Cercles | `GET /v1/circles`, `GET /v1/circles/{circle_id}`, `GET /v1/circles/{circle_id}/members` | `circles:read` |
| Rôles | `GET /v1/roles`, `GET /v1/roles/{role_id}`, `GET /v1/roles/{role_id}/members` | `roles:read` |
| Modèles de rôle | `GET /v1/role-templates`, `GET /v1/role-templates/{role_template_id}` | `roles:read` |
| Définitions de champs personnalisés | `GET /v1/custom-fields` | `roles:read`, `circles:read` ou `users:read`, selon l’`entity_type` demandé |
| Réunions | `GET /v1/meetings`, `GET /v1/meetings/{meeting_id}`, `GET /v1/meetings/{meeting_id}/agenda-items` | `meetings:read` |
| Projets | `GET /v1/projects`, `GET /v1/projects/{project_id}`, `GET /v1/projects/{project_id}/comments` | `projects:read` |
| Sections | `GET /v1/sections`, `GET /v1/sections/{section_id}` | `projects:read` |
| Libellés | `GET /v1/labels`, `GET /v1/labels/{label_id}` | `projects:read` |
| Tâches | `GET /v1/tasks`, `GET /v1/tasks/{task_id}`, `GET /v1/tasks/{task_id}/comments` | `tasks:read` |
| Objectifs | `GET /v1/goals`, `GET /v1/goals/{goal_id}`, `GET /v1/goals/{goal_id}/key-results`, `GET /v1/goals/{goal_id}/comments` | `goals:read` |
| Périodes | `GET /v1/time-periods`, `GET /v1/time-periods/{time_period_id}` | `goals:read` |
| Accords de fonctionnement | `GET /v1/documents`, `GET /v1/documents/{document_id}`, `GET /v1/documents/{document_id}/content`, `GET /v1/documents/{document_id}/comments` | `documents:read` |
| Tensions | `GET /v1/tensions`, `GET /v1/tensions/{tension_id}` | `tensions:read` |
| Exports de la structure | `GET /v1/structure-exports/{export_id}`, `GET /v1/structure-exports/{export_id}/file`, après un `POST /v1/structure-exports` qui lance l’export | `structure_export:read` |
| Exports des objectifs | `GET /v1/goal-exports/{export_id}`, `GET /v1/goal-exports/{export_id}/file`, après un `POST /v1/goal-exports` qui lance l’export | `goal_export:read` |
| Exports des tâches | `GET /v1/task-exports/{export_id}`, `GET /v1/task-exports/{export_id}/file`, après un `POST /v1/task-exports` qui lance l’export | `task_export:read` |
| Exports des membres | `GET /v1/user-exports/{export_id}`, `GET /v1/user-exports/{export_id}/file`, après un `POST /v1/user-exports` qui lance l’export | `user_export:read` |
| Exports des checklists et des indicateurs | `GET /v1/checklist-metric-exports/{export_id}`, `GET /v1/checklist-metric-exports/{export_id}/file`, après un `POST /v1/checklist-metric-exports` qui lance l’export | `checklist_metric_export:read` |
| Historique d’activité | `GET /v1/activities` | `activity:read` |
| Journal d’activité | `GET /v1/audit-logs` | `audit_log:read` |
| Votre propre identité | `GET /v1/whoami` | aucune |

Deux regroupements méritent l’attention, car ils ne suivent pas le nom du chemin : les sections et les libellés se lisent avec `projects:read`, et les périodes avec `goals:read`.

Le texte d’un accord de fonctionnement est une sous-ressource à part entière, `GET /v1/documents/{document_id}/content` : lister les documents ne transporte donc jamais une page de textes complets. Elle sert la version que le compte de la clé voit dans le produit, c’est-à-dire la version publiée, ou le dernier brouillon si rien n’a encore été publié. Un accord de fonctionnement qui existe mais ne contient aucun texte répond `200` avec un texte vide plutôt que `404`.

`GET /v1/memberships` renvoie toutes les appartenances de l’organisation, une page par appel : une synchronisation complète de la structure coûte donc autant d’appels que de pages, et non un appel par membre. Chaque ligne est exactement une ligne de `GET /v1/users/{user_id}/memberships`, avec le `user_id` du membre. Passez `?updated_since=` pour ne recevoir que les appartenances ajoutées ou modifiées depuis un instant donné ; un tel parcours ne peut pas voir une appartenance qui a été supprimée : réconciliez donc de temps en temps avec un parcours complet.

`GET /v1/audit-logs` est le journal d’activité de l’organisation, du plus récent au plus ancien : connexions (réussies et refusées), publications, commentaires, et accès aux groupes et sorties de groupes. Comme il couvre tous les membres, le compte derrière la clé doit être un administrateur de l’organisation, en plus de la portée `audit_log:read` que la clé doit porter. Passez `?occurred_after=` pour ne lire que ce qui s’est passé depuis un instant donné.

`/v1/structure-exports` produit le fichier de l’écran **Exporter l’organisation** : les cercles, les rôles et qui les occupe, avec l’adresse e-mail de chaque titulaire, et les politiques en vigueur, sous forme de classeur XLSX (par défaut) ou d’archive ZIP de fichiers CSV. `POST /v1/structure-exports` lance l’export en arrière-plan et répond `202`, avec son adresse dans l’en-tête `Location`. Interrogez `GET /v1/structure-exports/{export_id}` jusqu’à ce que `status` vaille `completed` ou `failed`, puis appelez `GET /v1/structure-exports/{export_id}/file`. Il répond `302` vers le fichier, que vous devez récupérer avant `file_expires_at` ; ensuite il répond `410`. Une clé peut lire un export pendant 24 heures après sa fin, et seulement si elle agit comme le compte qui l’a lancé. Comme le fichier contient l’adresse e-mail de chaque membre, le compte derrière la clé doit être un administrateur de l’organisation, comme pour le journal d’activité. L’organisation peut lancer dix exports par heure glissante, ceux lancés depuis cet écran compris (voir Limites de débit).

`GET /v1/activities` est l’historique de qui a placé qui où dans la structure. `type=assignment` est obligatoire et reste la seule valeur aujourd’hui : il liste chaque fois qu’un membre a été placé sur un rôle ou retiré d’un rôle, ou ajouté à un cercle ou retiré d’un cercle, du plus récent au plus ancien. Une ligne porte `member_id` (le membre concerné par le changement), `actor_id` (le membre qui l’a fait), `action` (`assigned` ou `unassigned`), `occurred_at`, et soit `role_id` et `role_name`, soit `circle_id` et `circle_name`. Les deux identifiants de membre sont l’`id` que renvoie `GET /v1/users`. `cause` dit pourquoi lorsque l’auteur n’a pas fait le changement directement (`election`, `left_circle`, `left_source_role`, `member_suspended`, `invited_role_copy` ou `other` ; traitez toute autre valeur comme une valeur future), et `reason` est le texte de l’auteur. Filtrez avec `member`, `actor`, `role_id`, `circle_id` (qui renvoie aussi les changements sur les rôles de ce cercle et les changements d’appartenance de ses sous-cercles directs) et une fenêtre `occurred_after` / `occurred_before`, bornes comprises ; les filtres se combinent. Parcourez les pages avec le `cursor` et renvoyez les mêmes `type` et fenêtre à chaque page. Ne le confondez pas avec le journal d’activité décrit plus haut, qui enregistre les connexions, les publications et les commentaires.

La clé lit ce que son compte voit dans la vue d’activité de l’application : la clé d’un invité ne lit donc que les changements qui le concernent, et aucun rôle d’administrateur n’est nécessaire. Quatre limites comptent avant de vous y fier :

- **L’historique est récent.** Il commence le 5 novembre 2026, sauf les élections, enregistrées depuis le 21 septembre 2026. Les changements antérieurs et les affectations migrées depuis Holaspirit n’ont pas de ligne : pour eux, `assigned_at` sur `GET /v1/roles/{role_id}?include=members` donne la date mais pas l’auteur. Une page vide signifie donc « rien d’enregistré sur cette période », jamais « rien ne s’est passé ».
- **`actor_id` peut être `null`.** Aucune personne n’a fait le changement : la plateforme l’a fait seule, par exemple lorsqu’un membre suspendu est détaché de ses rôles, ou lorsqu’une élection est adoptée automatiquement après l’expiration de sa proposition. Ces lignes ne correspondent jamais à un filtre `actor` : pour les lire, parcourez la collection sans `actor` et gardez les lignes dont `actor_id` est `null` (envoyer l’identifiant composé uniquement de zéros est refusé, voir le tableau des erreurs).
- **Une ligne de rôle ne porte pas son cercle.** Lisez-le sur `GET /v1/roles/{role_id}`.
- **Certaines sorties ne sont pas enregistrées :** celles causées par la suppression d’un rôle ou d’un cercle, par l’effacement des données d’un membre, ainsi que l’appartenance au cercle que l’attribution d’un rôle apporte.

Les lignes de `GET /v1/goals/{goal_id}/key-results` portent deux tableaux, `task_ids` et `project_ids` : les tâches et les projets liés à ce résultat clé que le compte de la clé peut voir, chaque identifiant une seule fois, et `[]` s’il n’y en a aucun. Un élément lié que le compte ne peut pas voir, ou archivé, n’est pas listé, et l’ordre des identifiants ne signifie rien. Les lire ne demande que `goals:read` ; lisez l’élément lui-même avec `GET /v1/tasks/{task_id}` (`tasks:read`) ou `GET /v1/projects/{project_id}` (`projects:read`).

Quatre autres exports fonctionnent comme l’export de la structure : `/v1/goal-exports` (objectifs et résultats clés, XLSX), `/v1/task-exports` (tâches et projets, XLSX), `/v1/user-exports` (membres avec leur adresse e-mail, CSV) et `/v1/checklist-metric-exports` (checklists et indicateurs, XLSX). Chacun produit le fichier de l’écran d’administration correspondant. Vous le lancez par un `POST` qui répond `202` avec un en-tête `Location`, interrogez `GET .../{export_id}` jusqu’à ce que `status` vaille `completed` ou `failed`, puis téléchargez `GET .../{export_id}/file` (un `302`) avant `file_expires_at`. Un export reste lisible 24 heures. Le compte derrière la clé doit être administrateur de l’organisation, et le module Objectifs doit être actif pour l’export des objectifs et le module Projets pour l’export des tâches ; sinon le lancement répond `403 FORBIDDEN_UPSTREAM`. Les fichiers des objectifs et des tâches ne contiennent d’éléments privés que lorsque la supervision par les administrateurs de l’organisation est active, et l’export l’indique dans `includes_private_content`. Dans le fichier des checklists et des indicateurs, la colonne Recurrence contient l’un de huit mots prédéfinis (`DAILY` à `YEARLY`) ou, pour un élément à planning personnalisé, `CUSTOM: ` suivi de la règle en anglais et de sa date de début. Traitez ce texte comme un libellé, pas comme un format à analyser.

Sur les assignés d’une tâche (`?include=assignees` sur `GET /v1/tasks` et `GET /v1/tasks/{task_id}`), quatre champs nullables, `via_role_id`, `via_role_name`, `via_role_circle_id` et `via_role_circle_name`, donnent le rôle dans lequel le membre a été assigné à la tâche, tel qu’enregistré à ce moment, et le cercle où ce rôle est défini. Ce peut être un rôle que le membre n’occupe plus ou qui a été supprimé depuis : lorsque les noms d’un rôle supprimé ne sont plus lisibles, `via_role_id` reste renseigné et les trois autres valent `null`. Les quatre valent `null` sur les lignes de cercle, de rôle et de groupe, et pour un membre assigné sans rôle.

`GET /v1/meetings/{meeting_id}/agenda-items` renvoie l’ordre du jour complet d’une réunion, tous les points qui s’y trouvent quel qu’en soit l’auteur, dans l’ordre où la réunion les déroule. Un point placé à l’ordre du jour à partir d’une tension porte l’identifiant de cette tension dans `source_tension_id` ; un point saisi directement dans la réunion n’en a pas, et ce n’est pas une tension : les points de terminaison des tensions ne le renvoient donc jamais. `POST` sur le même chemin ajoute un point à la fin de l’ordre du jour ; voir les écritures ci-dessous.

Une tâche porte sa place dans une arborescence de sous-tâches et son texte. Chaque tâche a `parent_task_id` (`null` pour une tâche de premier niveau) et `subtask_count`, le nombre de ses sous-tâches non archivées, sans les privées que le compte de la clé ne peut pas voir ; la liste `?parent_task_id=` applique toute la règle de lecture et peut donc en montrer moins. `GET /v1/tasks` liste les tâches de premier niveau. Passez `?parent_task_id=` avec l’identifiant d’une tâche pour lister à la place ses sous-tâches ; un identifiant qui ne désigne aucune tâche lisible par le compte ne liste rien, et une valeur qui n’est pas un identifiant de tâche est refusée avec `400 INVALID_PARENT_TASK_ID`. Une sous-tâche se lit par son propre identifiant, comme n’importe quelle tâche. `GET /v1/tasks/{task_id}` et la réponse de `POST /v1/tasks` portent toujours `description` et `description_format` (`blocknote_json` ou `text`) ; sur la liste, demandez-les avec `?include=description`. `?include=attachments` liste les fichiers téléversés sur une tâche (`id`, `name`, `size`, `content_type`, `added_at`). Il ne donne aucun lien de téléchargement, et les liens rattachés à une tâche ne sont pas listés.

Plusieurs listes acceptent aussi des filtres, par exemple les rôles que détient un membre, les cercles dont un membre fait partie, les rôles liés à un modèle de rôle, les tâches ou les réunions auxquelles un membre est associé, les sous-tâches d’une tâche, ou les tensions mises à l’ordre du jour d’une réunion. La documentation de référence liste tous les filtres qu’accepte un point de terminaison.

### Des champs qui méritent une explication

Plusieurs champs portent plus de sens que leur nom ne le laisse croire.

- **`last_activity_at`, sur un membre.** `GET /v1/users`, `GET /v1/users/{user_id}` et la réponse de `PATCH /v1/users/{user_id}` publient la dernière activité enregistrée du membre. C’est un signal d’activité, pas une connexion : il est enregistré quand un membre authentifié utilise le produit, et rafraîchi environ une fois par heure plutôt qu’à chaque requête. Lisez-le donc comme « actif récemment » et jamais comme un événement d’authentification. Il vaut `null` quand aucune activité n’a jamais été enregistrée, et pour un membre anonymisé. Les appels que vous faites avec votre propre clé enregistrent l’activité de l’utilisateur technique derrière la clé, jamais celle des membres qu’elle lit ou modifie.
- **`avatar_url`, sur un membre.** `GET /v1/users`, `GET /v1/users/{user_id}` et la réponse de `PATCH /v1/users/{user_id}` publient l’adresse de la photo de profil actuelle du membre lorsque Talkspirit l’héberge. Elle vaut `null` quand le membre n’a pas de photo, et quand la photo est un lien vers un autre site. Talkspirit n’ajoute ni jeton ni signature à cette adresse : quiconque la détient peut télécharger l’image, et elle change quand le membre change de photo, ne la conservez donc pas comme un lien permanent.
- **`assigned_at` et `updated_at`, sur une affectation.** Chaque ligne de `GET /v1/roles/{role_id}/members`, `GET /v1/circles/{circle_id}/members`, `GET /v1/users/{user_id}/memberships` et `GET /v1/memberships`, et chaque ligne de membre renvoyée par `GET /v1/roles` et `GET /v1/roles/{role_id}` avec `?include=members`, porte les deux. La seule exception est une ligne de représentant sur `GET /v1/circles/{circle_id}/members`, décrite plus bas : elle ne correspond à aucune affectation dans ce cercle, donc les deux y valent `null`. `assigned_at` est le moment où l’affectation a commencé : pour une organisation migrée depuis Holaspirit, la date que l’affectation avait là-bas, et non la date de la migration. Les lignes dont la source ne portait pas cette date retombent sur l’instant de leur exécution d’import, ce qui permet de les reconnaître : elles partagent toutes une même valeur. `updated_at` est le moment où la ligne a été écrite pour la dernière fois : son intitulé, ses indicateurs de décideur et d’administrateur, un départ ou un retour. Il ne bouge pas quand une allocation change, ce n’est donc pas un flux des changements d’affectation, et aucun des deux champs n’est un historique d’affectation.
- **`expires_at` et `mandate_kind`, sur une affectation.** Ils figurent sur les mêmes lignes que `assigned_at` et sont toujours présents, `null` ou non. `expires_at` est la date de fin fixée sur l’affectation, un jour calendaire écrit `AAAA-MM-JJ`, ou `null` quand elle n’en a pas, ce qui est l’état ordinaire. `mandate_kind` dit pourquoi l’affectation a une date de fin, quand cela a été enregistré : `ELECTED` pour un titulaire élu au rôle, `INTERIM` pour un titulaire nommé sans élection sur un rôle qui en exige normalement une, et `null` pour une affectation ordinaire. Traitez toute autre valeur comme une valeur future.
- **Les représentants, dans la liste des membres d’un cercle.** `GET /v1/circles/{circle_id}/members` liste d’abord les membres du cercle lui-même, puis ses représentants : toute personne qui occupe, dans un cercle directement imbriqué dans celui-ci, un rôle doté du réglage **Représente le sous-cercle**. Ils participent aux décisions du cercle sans y être rattachés. Ils viennent après les membres, triés par `user_id`, dans les mêmes pages et sous le même curseur, et une personne à la fois membre et représentante n’est listée qu’une fois, comme membre. Une ligne de représentant ne nomme aucun rôle : `role_id`, `role_name`, `scope`, `assigned_at`, `updated_at`, `expires_at` et `mandate_kind` valent `null`, `is_decision_maker` vaut `true` et `is_circle_admin` vaut `false`. Un script qui parcourt les membres d’un cercle reçoit donc aussi ces lignes, et ne doit pas traiter un `assigned_at` à `null` comme une erreur.
- **`content_restricted_to_members` et `meeting_reports_restricted_to_members`, sur un cercle.** Ce sont les deux réglages de confidentialité du cercle, en lecture seule. Le premier vaut `true` quand le cercle réserve son contenu, c’est-à-dire les documents du cercle et de ses rôles ainsi que ses liens, à ses seuls membres. Le second vaut `true` quand les comptes rendus de ses réunions ne sont visibles que de ses membres. Les deux valent `true` tant que personne ne les a ouverts. Ils décrivent le cercle et ne changent rien à ce que lit votre clé, qui est toujours ce que son compte peut voir. `null` signifie que le réglage n’a pas pu être lu, pas que le cercle est ouvert.
- **`assignees`, sur un projet.** `GET /v1/projects` et `GET /v1/projects/{project_id}` acceptent `?include=assignees`. Il liste les cercles et les rôles auxquels le projet est affecté, chacun avec `assignee_type` (`CIRCLE` ou `ROLE`), `assignee_id`, `assignee_name`, `project_role` (`OWNER`, `EDITOR`, `CONTRIBUTOR` ou `VIEWER`, l’accès que cette affectation donne sur le projet) et `assigned_at`. Les membres pris individuellement et les groupes affectés au projet ne sont pas listés : ce n’est donc pas la liste de tous ceux qui peuvent ouvrir le projet.
- **`options`, sur une définition de champ personnalisé de membre.** `GET /v1/custom-fields?entity_type=user` publie le catalogue complet des options de chaque champ à sélection simple et à sélection multiple, là où il ne publiait rien : toutes les options configurées, y compris celles qu’aucun membre ne porte encore, sous forme de paires `{value, label}`. `value` est l’identifiant d’option que `PATCH /v1/users/{user_id}/custom-fields` accepte ; `label` est ce à quoi la valeur d’un membre correspond le plus souvent. Faites donc correspondre la valeur d’un membre d’abord sur `label`, puis sur `value` si cela échoue, et attendez-vous à ce que deux options d’un même champ puissent partager un intitulé. Les options arrivent triées par intitulé, jusqu’à 5 000 par champ, et `options_truncated`, sur la même définition, indique si ce plafond a été atteint. Un champ à sélection sans aucune option configurée renvoie une liste vide ; `null` signifie toujours que le type du champ n’a pas de liste d’options. Les valeurs servies par `GET /v1/users?include=custom_fields` sont inchangées.

- **`source_template_id`, sur un rôle.** Le modèle de rôle auquel le rôle est lié, l’identifiant que renvoie `GET /v1/role-templates`, ou `null` quand il n’est lié à aucun. Un rôle commence lié au modèle dont il a été créé, mais ce lien peut changer pendant la vie du rôle, dans l’application par une proposition ou le mode Architecte : la valeur peut passer de `null` à un identifiant, d’un identifiant à un autre, ou revenir à `null`, et un lien ou une rupture de lien fait avancer `updated_at`. Supprimer définitivement un modèle de rôle vide la valeur sur tous les rôles qui lui sont liés, sans faire avancer leur `updated_at`. `GET /v1/roles?source_template_id=` liste les rôles liés au modèle au moment de l’appel. Un modèle de rôle est une définition de rôle réutilisable, par exemple « Secrétaire ». Une copie invitée d’un rôle vaut `null` : son `source_role_id` mène au rôle qui porte le modèle. Si votre organisation a été migrée depuis Holaspirit, les identifiants de modèle ont changé avec la migration : relisez-les depuis `GET /v1/role-templates`.
- **Les champs personnels d’un membre.** `email`, `phone`, `last_activity_at` et les valeurs des champs personnalisés parviennent à votre clé comme ils parviennent à l’utilisateur technique dans le produit. Un administrateur les lit tous. Un membre les lit tous, sauf un e-mail que son propriétaire a choisi de masquer. Un invité qui ne partage aucun groupe actif avec ce membre n’en lit aucun. Un champ retenu vaut `null`. L’utilisateur technique derrière une clé n’est généralement pas un administrateur : attendez-vous donc à ce que `email` soit `null` pour les membres qui l’ont masqué.
- **`priority`, sur une tension.** Elle peut valoir `NONE`, ce qui signifie que personne n’en a défini, et c’est ce qu’enregistre désormais une tension créée sans priorité. Traitez une valeur que vous ne reconnaissez pas comme une valeur future plutôt que comme une erreur.

**Changer le type d’un champ à sélection déplace ses valeurs d’un emplacement à l’autre.** Un champ qu’un administrateur fait passer de sélection simple à sélection multiple cesse d’être lu dans `value`, une valeur unique, et commence à être lu dans `values`, une liste ; une écriture doit utiliser le même emplacement. Envoyer le mauvais est refusé par un `422 INVALID_CUSTOM_FIELD_VALUE` dont le message nomme l’emplacement à utiliser ; il n’y a jamais de conversion silencieuse.

### Les dix-sept écritures

| Opération | Portée | Ce qu’il faut savoir |
| --- | --- | --- |
| `POST /v1/tasks` | `tasks:write` | Crée une tâche à chaque appel : ne relancez donc pas la requête à l’aveugle. Le paramètre facultatif `section_id` désigne la colonne du projet dans laquelle va la tâche ; sans lui, Talkspirit choisit la première section du projet qui n’est pas réservée au travail terminé ou bloqué. Un en-tête `Idempotency-Key` est refusé avec un `400`. |
| `POST /v1/tensions` | `tensions:write` | Crée une tension. Une `priority` omise enregistre `NONE`. Avec `created_by_id`, la tension est déposée au nom d’un membre, qui en devient le créateur : elle figure parmi ses tensions et il peut la modifier. Le compte de votre clé n’en est alors plus le créateur, donc `PATCH` et `DELETE` répondent `404` dessus. Envoyer `created_by_id` exige aussi la portée `tensions:write_on_behalf` (`403 FORBIDDEN_SCOPE` sans elle). Un identifiant qui ne désigne aucun membre actif non invité est refusé avec `422 UNKNOWN_MEMBER`. Envoyez un en-tête `Idempotency-Key` pour pouvoir relancer sans risque, comme décrit sous le tableau. |
| `PATCH /v1/tensions/{tension_id}` | `tensions:write` | Modifie une tension. |
| `PATCH /v1/tensions/{tension_id}/status` | `tensions:write` | Fait avancer une tension dans ses statuts. Clore ou résoudre une tension qu’une proposition encore en cours porte est refusé avec `422 TENSION_CARRIED_BY_LIVE_PROPOSAL` : faites adopter, rejeter ou retirer la proposition dans Talkspirit, puis renvoyez le changement. |
| `DELETE /v1/tensions/{tension_id}` | `tensions:delete` | **Une suppression définitive, sans retour arrière.** Voir ci-dessous. |
| `POST /v1/tensions/{tension_id}/links` | `tensions:write` | Enregistre ce qu’une tension est devenue, en lui rattachant un élément. Non idempotent. Voir ci-dessous. |
| `DELETE /v1/tensions/{tension_id}/links/{link_id}` | `tensions:delete` | Retire l’issue actuelle de la tension. **Sans retour arrière.** Voir ci-dessous. |
| `POST /v1/meetings/{meeting_id}/agenda-items` | `meetings:write` | Ajoute un point à la fin de l’ordre du jour d’une réunion, éventuellement à partir d’une tension existante (`source_tension_id`). Elle crée un point à chaque appel : ne relancez donc pas la requête à l’aveugle, lisez l’ordre du jour avant de renvoyer, ce qui exige aussi `meetings:read`. Une tension ne peut figurer qu’à l’ordre du jour d’une seule réunion non terminée. |
| `POST /v1/structure-exports` | `structure_export:read` | Lance un export de la structure, décrit plus haut. Il en lance un nouveau à chaque appel : ne relancez donc pas la requête à l’aveugle, et un en-tête `Idempotency-Key` est refusé avec `400`. Il est derrière une portée de lecture bien que ce soit un `POST`, car ce qu’on confie à la clé, c’est de lire tout le registre. |
| `POST /v1/goal-exports` | `goal_export:read` | Lance un export des objectifs, décrit plus haut. Mêmes règles que `POST /v1/structure-exports` : un nouvel export à chaque appel, et un en-tête `Idempotency-Key` est refusé avec `400`. Le compte de votre clé peut en exécuter un seul à la fois (sinon `429 EXPORT_ALREADY_RUNNING`). |
| `POST /v1/task-exports` | `task_export:read` | Lance un export des tâches, décrit plus haut. Mêmes règles que `POST /v1/goal-exports`. |
| `POST /v1/user-exports` | `user_export:read` | Lance un export des membres, décrit plus haut. Mêmes règles que `POST /v1/goal-exports`. Le fichier contient l’adresse e-mail de chaque membre. |
| `POST /v1/checklist-metric-exports` | `checklist_metric_export:read` | Lance un export des checklists et des indicateurs, décrit plus haut. Un nouvel export à chaque appel, et un en-tête `Idempotency-Key` est refusé avec `400`. |
| `PATCH /v1/users/{user_id}` | `users:write` | Modifie un membre. |
| `PATCH /v1/users/{user_id}/custom-fields` | `users:write` | Renseigne les valeurs des champs personnalisés d’un membre. |
| `PATCH /v1/circles/{circle_id}/custom-fields` | `circles:write` | Renseigne les valeurs des champs personnalisés d’un cercle. |
| `PATCH /v1/roles/{role_id}/custom-fields` | `roles:write` | Renseigne les valeurs des champs personnalisés d’un rôle. |

**Supprimer une tension est irréversible.** La tension et ses liens disparaissent, et aucune lecture ne les renvoie ensuite. L’opération est protégée par sa propre portée `tensions:delete`, que `tensions:write` n’accorde délibérément pas : la capacité doit donc être donnée explicitement plutôt qu’héritée. Une tension n’est par ailleurs supprimable que par son créateur : une clé peut supprimer les tensions créées par son propre utilisateur technique, et rien d’autre.

**Enregistrer ce qu’une tension est devenue.** `POST /v1/tensions/{tension_id}/links` rattache une proposition, une tâche, un projet, un point d’ordre du jour ou un objectif à une tension comme son issue actuelle : envoyez `linked_item_type`, `linked_item_id`, `linked_service` et une `note` facultative, et recevez `201` avec le lien tel que `GET /v1/tensions/{tension_id}?include=links` le liste. Rattacher un autre élément remplace l’issue actuelle, et rattacher une proposition fait passer la tension à `PROCESSING`. Seule une tension `OPEN` ou `PARKED` peut être transformée (sinon `422 BUSINESS_RULE_VIOLATION`), et un élément ne peut être rattaché qu’à une seule tension (`422 CONFLICT`). L’élément lui-même n’est pas recherché : un identifiant qui ne désigne rien est enregistré tel quel. Le rattachement n’est pas idempotent : un en-tête `Idempotency-Key` est donc refusé avec `400` ; si une réponse est perdue, lisez la tension avec `?include=links` avant de renvoyer.

`DELETE /v1/tensions/{tension_id}/links/{link_id}` retire l’issue actuelle de la tension et répond `204`. On ne peut pas l’annuler, et retirer le lien d’une proposition rouvre une tension qui était `PROCESSING`. Le lien d’une autre tension, une issue antérieure ou un identifiant inconnu répond `404 TENSION_LINK_NOT_FOUND` et ne retire rien. Les deux opérations suivent la règle de clôture d’une tension : le créateur de la tension peut les utiliser, de même que les personnes qui animent la réunion ouverte de son cercle tant que la tension y figure ; toute autre tension répond `404`. Comme le retrait relève de `tensions:delete`, une clé qui la détient peut retirer le lien d’une tension que son compte n’a pas créée lorsque ce compte anime une telle réunion ; `DELETE /v1/tensions/{tension_id}` lui-même reste réservé au créateur.

**Les tensions exigent l’extension Holacracy.** Chaque route `/v1/tensions`, en lecture comme en écriture, répond `403` avec `code: TENSIONS_NEED_HOLACRACY_ADDON` lorsque l’organisation n’a pas l’extension Holacracy ; la vérification de la portée passe d’abord, et les clés déjà émises ne sont pas modifiées : elles sont refusées à l’usage. Ajouter un point d’ordre du jour avec un `source_tension_id` répond `422` avec le même code dans cet état.

**Des titres plus longs.** Un `title` peut compter jusqu’à 500 caractères sur `POST /v1/tasks`, `POST /v1/tensions`, `PATCH /v1/tensions/{tension_id}` et `POST /v1/meetings/{meeting_id}/agenda-items` ; un titre plus long est toujours refusé avec `422`.

**La création d’une tension peut être relancée sans risque.** Envoyez un en-tête `Idempotency-Key` avec chaque nouvelle tension : de 1 à 255 caractères ASCII visibles, sans espace (un UUID est le choix habituel). Une répétition de la même requête avec la même clé dans les 24 heures ne crée rien : elle renvoie la première réponse `201`, avec le même corps et l’en-tête `Idempotent-Replayed: true`. La clé appartient à la clé API qui l’a envoyée : une autre clé API, même de la même organisation, ne reçoit jamais sa réponse. Les créations au nom d’un membre sont couvertes aussi, et `created_by_id` fait partie de la requête à laquelle la clé est liée. Sans l’en-tête, rien ne change : deux appels créent deux tensions.

- La même clé avec un corps différent est refusée avec un `422`, entrée `code: IDEMPOTENCY_KEY_REUSED`, `field: Idempotency-Key`. Utilisez une nouvelle clé pour une nouvelle tension.
- Une répétition pendant que la première requête est encore en cours répond `409 IDEMPOTENCY_REQUEST_IN_PROGRESS`. Attendez le délai indiqué dans `Retry-After`, puis relancez avec la même clé : vous recevez la réponse de la première requête.
- Si la première requête a échoué alors que la tension a peut-être été créée, une répétition répond `409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN`. Lisez `GET /v1/tensions?sort=-created_at`, et si votre tension n’y figure pas, renvoyez-la avec une nouvelle clé.
- Une requête refusée avant que quoi que ce soit ait pu être écrit, par exemple un rejet `422` ou un `403`, libère sa clé.
- Une valeur que l’API ne peut pas honorer (vide, de plus de 255 caractères, avec des espaces ou des caractères non ASCII) est refusée avec un `400 IDEMPOTENCY_KEY_INVALID`, et rien n’est créé.

Trois limites demeurent. Si le stockage qui conserve les clés est brièvement indisponible, une requête qui porte une clé est créée sans cette protection, comme avant la version 0.77.0 du contrat. Si le service est arrêté pendant qu’une création est encore en cours, une nouvelle tentative faite quelques minutes plus tard peut créer la tension une seconde fois. Si Talkspirit a enregistré un champ de texte long autrement que vous ne l’avez envoyé, une répétition répond `409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN` au lieu de la première réponse `201`. Les autres écritures qui créent, et `PATCH /v1/tensions/{tension_id}/status`, refusent toujours l’en-tête avec un `400 IDEMPOTENCY_KEY_NOT_SUPPORTED`.

## Les portées

Un administrateur choisit les portées à la création de la clé. Vingt-quatre sont définies :

- Sans conditionnement : `users:read`, `users:write`, `audit_log:read`, `user_export:read`
- Module Structure : `roles:read`, `roles:write`, `circles:read`, `circles:write`, `tensions:read`, `tensions:write`, `tensions:write_on_behalf`, `tensions:delete`, `documents:read`, `structure_export:read`, `activity:read`, `checklist_metric_export:read`
- Module Objectifs : `goals:read`, `goal_export:read`
- Module Projets : `projects:read`, `tasks:read`, `tasks:write`, `task_export:read`
- Module Réunions : `meetings:read`, `meetings:write`

Elles n’apparaissent pas toutes en même temps. Une portée n’est proposée que si le module dont elle lit les données est actif sur l’organisation : `tasks:read` est donc absente si Projets est désactivé, et tout le bloc Structure est absent si Structure est désactivé. Demandez à l’administrateur quels modules l’organisation utilise avant de concevoir votre intégration autour d’une portée.

`audit_log:read` lit le journal d’activité, `GET /v1/audit-logs`. Elle ne suffit pas à elle seule : le compte derrière la clé doit aussi être un administrateur de l’organisation, sinon la route répond `403 FORBIDDEN_UPSTREAM`.

`activity:read` lit l’historique d’activité, `GET /v1/activities`. Elle est désactivée tant qu’un administrateur ne coche pas **Lecture de l’historique d’activité** dans le groupe Structure des portées de la clé, et le préréglage en lecture seule ne l’inclut pas, car elle nomme qui a placé ou retiré qui. Aucun rôle d’administrateur n’est nécessaire pour le compte derrière la clé. Une clé émise avant l’existence de cette portée ne la porte pas, et les portées d’une clé existante ne peuvent pas être modifiées : un administrateur crée donc une nouvelle clé.

`structure_export:read` lit l’export de la structure, `/v1/structure-exports`. Comme `audit_log:read`, elle ne suffit pas à elle seule : le compte derrière la clé doit aussi être un administrateur de l’organisation, sinon le lancement répond `403 FORBIDDEN_UPSTREAM`.

`goal_export:read`, `task_export:read`, `user_export:read` et `checklist_metric_export:read` lisent les exports des objectifs, des tâches, des membres, et des checklists et indicateurs. Comme `structure_export:read`, aucune ne suffit à elle seule : le compte derrière la clé doit aussi être un administrateur de l’organisation, sinon le lancement répond `403 FORBIDDEN_UPSTREAM`. Aucune n’est cochée par défaut.

`tensions:write_on_behalf` n’est nécessaire que pour envoyer `created_by_id` en créant une tension. `tensions:write` ne l’accorde pas, et les portées d’une clé existante ne se modifient pas : un administrateur crée donc une nouvelle clé pour l’ajouter.

`meetings:write` ajoute un point à l’ordre du jour, `POST /v1/meetings/{meeting_id}/agenda-items`. Elle n’inclut pas `meetings:read` : donnez les deux à une clé qui écrit, car relire l’ordre du jour est le seul moyen de savoir si une écriture dont la réponse a été perdue a abouti.

## Votre première requête

`GET /v1/whoami` ne demande aucune portée et fait aussi office de vérification d’identifiant. Elle renvoie le nom du partenaire sous lequel votre clé a été émise, l’organisation à laquelle elle appartient, les portées qu’elle porte, `user_id`, le membre sous lequel agit votre clé, et `created_by_user_id`, l’administrateur qui a créé la clé (`null` pour une clé plus ancienne ou créée par un opérateur Talkspirit). Quand un appel est refusé ou renvoie moins que prévu, `user_id` est le compte à examiner.

```
curl -H "Authorization: Bearer <votre clé API>" \
     https://partner-api.talkspirit.com/v1/whoami
```

Un `200` signifie que la clé elle-même est valide, et vous indique ce qu’elle porte. Il ne prouve pas que l’organisation accepte encore le compte qui se trouve derrière : `whoami` ne vérifie que la clé et n’appelle jamais Talkspirit, elle continue donc de répondre `200` alors que chaque point de terminaison exigeant une portée répond `403`. Tout le reste figure dans le tableau des erreurs ci-dessous.

## Conventions à respecter

- **Versionnement.** Tout se trouve sous `/v1`. Un changement cassant est livré sous un nouveau préfixe au lieu de modifier celui-ci.
- **Pagination.** Les points de terminaison de liste acceptent `?cursor=` et `?limit=`, et répondent avec un tableau `data` et un objet `pagination` portant `next_cursor` et `has_more`. Le `limit` par défaut est de 50 partout. Le maximum est de 199, avec deux exceptions : 100 sur `GET /v1/users` et 50 sur `GET /v1/meetings`. Le curseur est opaque : renvoyez-le tel quel. Il n’existe aucun paramètre `page`, `skip` ou `offset`, sous quelque orthographe que ce soit.
- **Expansion des champs.** Les réponses portent un ensemble minimal de champs. Demandez-en davantage avec `?include=`, une liste séparée par des virgules documentée sur chaque point de terminaison. Un champ que vous n’avez pas demandé est absent de la réponse plutôt que `null` : une liste absente signifie donc « non demandée » et `[]` signifie « demandée, et il n’y en a aucune ».
- **De serveur à serveur uniquement.** Les requêtes cross-origin depuis un navigateur ne sont pas prises en charge.
- **Nouvelles tentatives.** Chaque `GET` peut être relancé sans risque. `POST /v1/tensions` peut être relancé sans risque si vous envoyez un en-tête `Idempotency-Key` (voir Les onze écritures). Les autres créations ne sont pas idempotentes : `POST /v1/tasks`, `POST /v1/meetings/{meeting_id}/agenda-items` et `POST /v1/structure-exports` créent un enregistrement à chaque appel, dédupliquez donc de votre côté plutôt que de relancer à l’aveugle : sur ces écritures, un en-tête `Idempotency-Key` est refusé avec un `400` plutôt qu’ignoré.

### Limites de débit

Actuellement, chaque clé API peut envoyer **100 requêtes sur n’importe quelle période glissante de 60 secondes**. Les lectures et les écritures comptent de la même façon, chaque clé a son propre quota, et une requête refusée n’en consomme rien. La fenêtre est glissante : une requête libère sa place 60 secondes après avoir été envoyée, donc la 101e requête en une minute est refusée, puis les places reviennent une à une. Lisez le chiffre dans l’en-tête `X-RateLimit-Limit` de vos propres réponses plutôt que de l’écrire en dur. C’est un réglage de Talkspirit, il ne fait pas partie du contrat et il peut changer.

- **Les exports ont leur propre limite.** Une organisation peut lancer dix exports de la structure par heure glissante, ceux lancés depuis l’écran **Exporter l’organisation** compris. Ce `429` porte le code `STRUCTURE_EXPORT_LIMIT_REACHED` et un `Retry-After` d’une heure. Les appels qui lancent et suivent un export comptent aussi dans les 100 requêtes de la clé. Les exports des objectifs, des tâches, des membres, et des checklists et indicateurs ont chacun leur limite, également comptée pour toute l’organisation et partagée avec les écrans d’administration : au-delà, un `429` porte `EXPORT_LIMIT_REACHED` et un `Retry-After` d’une heure. Les exports des objectifs, des tâches et des membres n’autorisent en outre qu’un lancement à la fois par compte : un second lancement répond `429 EXPORT_ALREADY_RUNNING` avec un `Retry-After` d’une minute.
- **Sur un `429`, attendez.** Patientez le nombre de secondes indiqué dans l’en-tête `Retry-After`, puis renvoyez la requête. C’est sans risque, même pour une écriture, car la requête est refusée avant que quoi que ce soit s’exécute. Si les refus persistent, ralentissez et ajoutez un petit délai aléatoire à chaque nouvelle tentative. Des pages plus grandes, `?include=` au lieu d’un appel supplémentaire et la mise en cache de ce qui change rarement vont plus loin qu’une relance plus rapide.
- **Pour demander plus,** adressez-vous à votre contact Talkspirit ou au support Talkspirit. Indiquez ce qu’il vous faut : votre pic en requêtes par minute, votre volume quotidien et les points de terminaison que vous appelez. Le quota est réglé pour l’ensemble de Talkspirit, pas sur votre clé : un administrateur de votre organisation ne peut donc pas le relever. Un chiffre plus élevé s’appliquerait à toutes les intégrations, chaque demande est donc étudiée et aucune n’est promise.

## Ce que signifient les erreurs

| Statut et code | Ce qui s’est passé |
| --- | --- |
| `401 AUTHENTICATION_REQUIRED` | Aucun en-tête `Authorization` sur la requête. |
| `401 AUTHENTICATION_INVALID` | La clé est inconnue ou révoquée, ou l’organisation n’a pas accès à l’API. Le message permet de distinguer les deux. |
| `403 FORBIDDEN_SCOPE` | La clé est valide mais la portée exigée par ce point de terminaison ne lui a pas été accordée. |
| `403 FORBIDDEN_UPSTREAM` | La clé a la portée, mais le compte qui se trouve derrière ne peut pas apporter cette modification à un membre, ou n’est pas administrateur pour le journal d’activité ou un export. C’est à un administrateur de l’accorder. |
| `403 TENSIONS_NEED_HOLACRACY_ADDON` | L’organisation n’a pas l’extension Holacracy : toutes les routes de tensions sont refusées (`422` avec le même code lorsqu’un point d’ordre du jour désigne un `source_tension_id`). C’est à un administrateur d’agir. |
| `403 FORBIDDEN_SIGN_IN_DISABLED`, `FORBIDDEN_MODULE_DISABLED`, `FORBIDDEN_ACCOUNT_SUSPENDED`, `FORBIDDEN_ACCOUNT_UNKNOWN` ou `FORBIDDEN_ACCESS_DENIED` | La portée est bien là, mais l’organisation refuse le compte qui se trouve derrière la clé : sa méthode de connexion a été désactivée, le module que lit ce point de terminaison est désactivé, le compte est suspendu, il n’existe plus dans l’organisation, ou il n’a pas le droit de voir ce que vous demandez. Aiguillez votre code sur le `code` reçu. |
| `400 INVALID_CURSOR`, `INVALID_INCLUDE` ou `INVALID_PARENT_TASK_ID` | Le jeton de pagination est mal formé ou au-delà de son plafond, un jeton `include` n’est pas accepté par ce point de terminaison, ou `parent_task_id` n’est pas un identifiant de tâche ou est répété. |
| `400 INVALID_ACTIVITY_TYPE`, `INVALID_MEMBER`, `INVALID_ACTOR`, `INVALID_ROLE_ID`, `INVALID_CIRCLE_ID`, `INVALID_OCCURRED_AFTER`, `INVALID_OCCURRED_BEFORE`, `OCCURRED_AFTER_CURSOR_MISMATCH` ou `OCCURRED_BEFORE_CURSOR_MISMATCH` | Sur `GET /v1/activities` : `type` est absent, inconnu ou répété ; un filtre est répété ou n’est pas un identifiant unique, ou un instant unique avec un décalage UTC ; `occurred_before` précède `occurred_after` ; ou une fenêtre diffère de celle à laquelle le `cursor` est lié. `actor` fixé à l’identifiant composé uniquement de zéros `00000000-0000-0000-0000-000000000000` est refusé avec `INVALID_ACTOR`. Renvoyez les mêmes valeurs à chaque page d’un parcours. |
| `400 IDEMPOTENCY_KEY_NOT_SUPPORTED` | Un en-tête `Idempotency-Key` a été envoyé à une écriture qui ne déduplique pas : `POST /v1/tasks`, `POST /v1/meetings/{meeting_id}/agenda-items`, `POST /v1/structure-exports`, `POST /v1/goal-exports`, `POST /v1/task-exports`, `POST /v1/user-exports`, `POST /v1/checklist-metric-exports`, `POST /v1/tensions/{tension_id}/links` ou `PATCH /v1/tensions/{tension_id}/status`. Retirez l’en-tête. |
| `400 IDEMPOTENCY_KEY_INVALID` | L’en-tête `Idempotency-Key` envoyé à `POST /v1/tensions` ne compte pas de 1 à 255 caractères ASCII visibles. Rien n’a été créé. |
| `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` ou `IDEMPOTENCY_KEY_OUTCOME_UNKNOWN` | Un `POST /v1/tensions` répété avec une clé déjà utilisée. `IDEMPOTENCY_REQUEST_IN_PROGRESS` : la première requête est encore en cours, relancez donc avec la même clé après `Retry-After`. `IDEMPOTENCY_KEY_OUTCOME_UNKNOWN` : la première requête a échoué alors que la tension a peut-être été créée, lisez donc `GET /v1/tensions?sort=-created_at` et ne renvoyez avec une nouvelle clé que si elle n’y figure pas. |
| `409 ACTIVITY_LOG_DISABLED` | L’organisation n’a jamais activé son journal d’activité. C’est un administrateur qui change ce réglage : relancer ne sert à rien. |
| `429 RATE_LIMIT_EXCEEDED`, `UPSTREAM_RATE_LIMITED` ou `STRUCTURE_EXPORT_LIMIT_REACHED` | `RATE_LIMIT_EXCEEDED` : votre clé a envoyé plus de 100 requêtes en 60 secondes (voir Limites de débit ci-dessus). `UPSTREAM_RATE_LIMITED` : les services propres à Talkspirit derrière l’API limitent temporairement les requêtes, souvent à cause de nombreux appels en parallèle. Votre quota est intact et il n’y a pas de chiffre à relever : attendez puis réessayez. `STRUCTURE_EXPORT_LIMIT_REACHED` : l’organisation a lancé ses dix exports de la structure pour l’heure. Attendez le nombre de secondes indiqué dans l’en-tête `Retry-After`. |
| `404 STRUCTURE_EXPORT_NOT_FOUND`, `409 STRUCTURE_EXPORT_NOT_READY` ou `STRUCTURE_EXPORT_FAILED`, `410 STRUCTURE_EXPORT_FILE_EXPIRED` | `404` : l’export n’existe pas pour cette clé, ou il s’est terminé il y a plus de 24 heures. `409` : l’export est encore en cours, interrogez-le de nouveau, ou il a échoué, lancez-en un nouveau. `410` : l’adresse du fichier a expiré, lancez un nouvel export. |
| `404 EXPORT_NOT_FOUND`, `409 EXPORT_NOT_READY` ou `EXPORT_FAILED`, `410 EXPORT_FILE_EXPIRED` | Comme pour l’export de la structure ci-dessus, pour les exports des objectifs, des tâches, des membres, et des checklists et indicateurs. Un export d’un autre type répond aussi `404`. |
| `429 EXPORT_LIMIT_REACHED` ou `EXPORT_ALREADY_RUNNING` | `EXPORT_LIMIT_REACHED` : l’organisation a lancé ses exports de ce type pour l’heure. `EXPORT_ALREADY_RUNNING` : votre compte a déjà un export des objectifs, des tâches ou des membres en cours. Attendez le nombre de secondes indiqué dans l’en-tête `Retry-After`. |
| `404 TENSION_LINK_NOT_FOUND` | Le lien n’est pas l’issue actuelle de cette tension, ou le compte de la clé ne peut pas le retirer. Rien n’a été retiré. |
| `502 UPSTREAM_ERROR` ou `UPSTREAM_AUTH_ERROR` | Un service dont dépend ce point de terminaison est en échec ou a répondu de façon inattendue. Rien n’a changé : relancez avec un délai croissant. |
| `504` | La requête a dépassé la limite de temps du serveur et a été abandonnée. Nul ne sait si une écriture a pris effet : ne la relancez que si la répéter est sans risque. |

Un refus de l’organisation, les cinq codes `403` du tableau, est définitif : ni une nouvelle tentative ni une nouvelle clé ne le lèvent, c’est à un administrateur de l’organisation d’agir. `FORBIDDEN_ACCESS_DENIED` répond aussi quand l’organisation est en cours de suppression ou n’existe plus : aucun administrateur ne peut alors aider, contactez le support Talkspirit. Jusqu’à la version 0.49.0 du contrat, ces refus et la limitation de débit de Talkspirit arrivaient tous deux sous la forme d’un `502`, qui se lit comme un incident passager. Une intégration écrite pour cet ancien comportement relance indéfiniment un refus et ignore `Retry-After` en cas de limitation : vérifiez la vôtre à l’aune du tableau ci-dessus.

Les corps d’erreur n’indiquent jamais si une clé existe ni si c’est la portée qui a échoué : n’essayez donc pas d’en déduire un état.

## Et ensuite ?

- [Gérer les jetons API en tant qu’administrateur](/fr/integrations/manage-api-tokens-as-an-admin)
- [Comment ajouter ou supprimer une intégration ?](/fr/integrations/enable-a-cloud-file-picker)
