Aller au contenu principal

Comment fonctionne un Board

Cette page explique le modèle de données des boards et les mécaniques derrière chaque opération board : comment tables et lignes se relient, comment les colonnes et cellules typées fonctionnent, comment se comportent le rich-text et les pièces jointes, comment les commentaires de ligne et la visibilité sont scopés, comment fonctionne l'authentification de ligne, et comment le filtrage, le tri et les exports sont évalués. Pour une orientation rapide et des exemples à copier-coller, commencez par l'introduction Boards.

Le modèle de données​

Les boards forment une hiérarchie à trois niveaux :

  • Board — le conteneur de premier niveau. Un board regroupe des tables liées.
  • Table — appartient à un board. Une table définit un ensemble de colonnes et contient des lignes.
  • Row (ligne) — un enregistrement unique dans une table. Une ligne porte une valeur de cellule pour chaque colonne, plus une description markdown et des commentaires optionnels.
Board
└── Table (columns: Name, Status, Owner, Notes…)
    ├── Row #1  (cells: "Acme", "In progress", …)
    ├── Row #2
    └── Row #3

Chaque ligne a deux identifiants : un _id interne (un object id de 24 caractères utilisé dans la plupart des endpoints) et un numéro de ligne lisible par un humain (le petit numéro séquentiel affiché dans la grille, p. ex. 42). Vous pouvez récupérer une ligne par l'un ou l'autre.

Colonnes et cellules​

Les colonnes d'une table ont chacune un columnId, un label et un type. Les types de colonnes incluent status, dropdown, labels, checkbox, text, paragraph, link, date, email, phone, website, number, duration, location et users. Les colonnes status/dropdown/labels exposent leurs options sélectionnables (chacune avec un optionId, un libellé et une couleur) ; les options status portent aussi un statusGroup de TODO, IN_PROGRESS ou DONE.

Lorsque vous lisez une ligne, vous obtenez un tableau columns de cellules, chacune clé par columnId avec une value. Les cellules Link référencent d'autres lignes ; les cellules lookup font remonter des valeurs tirées de lignes liées.

Lorsque vous écrivez une ligne, vous passez columns: [{ columnId, value }]. Quelques types de colonnes ont une sémantique de valeur particulière :

  • Colonnes Link prennent un tableau de chaînes d'id de ligne. Passer [] efface le lien. Les lignes liées doivent exister dans la table cible et le même workspace.
  • Colonnes rich-text (paragraph) prennent une chaîne markdown. Le contenu est amorcé de façon asynchrone, donc il peut apparaître un instant après le retour de l'écriture.
  • Colonnes Duration prennent un nombre JSON représentant des secondes. Par exemple, 1800 représente 30 minutes. Les chaînes formatées comme "00:30:00" sont invalides.

Lire boards, tables et lignes​

  • Lister les boards — renvoie chaque board auquel votre token peut accéder, avec un q optionnel pour filtrer par nom ou description.
  • Obtenir un board / Lister les tables / Obtenir une table — descendez dans la structure d'un board et lisez les définitions de colonnes d'une table.
  • Lister les lignes — renvoie les lignes d'une table. Prend en charge trois paramètres de requête qui se composent ensemble : q (recherche insensible à la casse dans les colonnes consultables), filter (un filtre JSON structuré, ci-dessous), et sort.
  • Obtenir une ligne — par id interne, ou par numéro de ligne via l'endpoint dédié au numéro de ligne.

Filtrer les lignes​

Le paramètre de requête filter est une chaîne JSON de cette forme :

{
  "match": "and",
  "conditions": [
    { "column_id": "<columnId>", "operator": "contains", "value": "acme" },
    { "column_id": "<statusColumnId>", "operator": "includes", "value": ["<optionId>"] }
  ]
}
  • match est and (défaut) ou or.
  • conditions est un tableau d'au plus 20 conditions. Chacune nomme un column_id, un operator, et (pour la plupart des opérateurs) une value.
  • Les opérateurs valides dépendent du type de la colonne :
    • Text : equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty.
    • Number : equals, not_equals, gt, gte, lt, lte, includes, not_includes, is_empty, is_not_empty.
    • Select (status / dropdown / labels) : equals, not_equals, includes, not_includes, is_empty, is_not_empty (les valeurs sont des ids d'options).
    • Checkbox : equals, not_equals, is_empty, is_not_empty.
    • Date : equals, before, after, between (la valeur est une paire [startISO, endISO]), plus des opérateurs relatifs sans valeur comme today, last_7_days, current_month, et is_empty / is_not_empty.

Un id de colonne inconnu ou un opérateur qui ne s'applique pas au type de colonne renvoie un 400.

Trier les lignes​

Le paramètre de requête sort est une liste séparée par des virgules d'entrées columnId:direction, où la direction est asc (défaut) ou desc :

?sort=statusColumnId:asc,createdColumnId:desc
note

La chaîne de requête HTTP sort utilise la forme columnId:direction. Certains exemples SDK expriment le tri comme un tableau d'objets { column, dir } — les deux décrivent le même ordre, juste sous des formes différentes.

Écrire des lignes​

  • Créer une ligne — POST avec une description markdown optionnelle et un tableau columns (qui peut être vide). Renvoie la ligne créée.
  • Mettre à jour une ligne — PATCH avec un tableau columns non vide. Seules les colonnes que vous envoyez sont modifiées ; le reste reste intact.
  • Supprimer une ligne — supprime définitivement la ligne.

Les bots agissent comme des utilisateurs : une action effectuée par votre token peut déclencher les automatisations du board, donc les écritures programmatiques s'intègrent aux mêmes workflows que votre équipe utilise.

Description de ligne et colonnes rich-text​

La description d'une ligne et toute colonne rich-text sont du markdown. Lisez-les avec l'endpoint GET …/md correspondant, qui renvoie { "content": "…" }.

Pour les écrire, POST une operation de replace, append ou prepend plus le content markdown. Ces écritures sont traitées de façon asynchrone et renvoient HTTP 202 Accepted — le contenu arrive un instant plus tard.

Pièces jointes fichier​

Les colonnes FILE stockent une ou plusieurs références de fichiers privés sur la cellule de ligne. Via la Public API, vous pouvez envoyer un nouveau fichier directement vers une cellule de colonne FILE avec multipart/form-data, télécharger un fichier joint par son fileId, ou retirer une référence de pièce jointe de la cellule.

L'endpoint d'upload ajoute le fichier envoyé à la valeur de cellule existante et renvoie les métadonnées de la pièce jointe (fileId, nom, type MIME et taille). L'endpoint de suppression détache uniquement ce fileId de la cellule de ligne ; il ne supprime pas l'enregistrement de fichier privé sous-jacent ni les octets.

Les cellules de colonnes fichier et les pièces jointes de commentaires peuvent être téléchargées directement. Les endpoints de download stream les octets bruts du fichier (avec les en-têtes content-type et filename appropriés) plutôt que de renvoyer une URL signée.

Commentaires de ligne​

Les lignes prennent en charge des commentaires en fil, chacun avec une visibilité :

  • internal — visible uniquement pour les membres du workspace.
  • external — visible pour toute personne ayant accès à la ligne, y compris les invités.

Lister les commentaires prend en charge la pagination par curseur (after / before) et un filtre visibility de all (défaut), internal ou external. Créer un commentaire prend un content HTML et une visibility qui vaut par défaut internal.

Authentifier une ligne​

Les tables peuvent servir de magasin d'identifiants léger. L'endpoint authenticate prend une colonne d'identifiant + valeur et une colonne de mot de passe + valeur, et renvoie la ligne correspondante (avec les colonnes de mot de passe masquées) lorsque les identifiants sont valides :

  • 400 — aucune ligne ne correspond à l'identifiant.
  • 401 — le mot de passe est incorrect.

Cela vous permet de construire des vérifications de type connexion contre une table de board sans exposer la cellule de mot de passe.

Exporter une vue de table​

L'endpoint export rend une vue de table en fichier. Vous POST le viewId et un format — CSV, XLSX, JSON, MARKDOWN, HTML, PDF, ZIP ou ICS — avec des filtres, tri, sélection de colonnes et options par format optionnels.

Les exports s'exécutent de façon synchrone ou asynchrone selon la taille :

  • Petits exports renvoient 200 OK avec le fichier rendu en ligne (formats texte en UTF-8, formats binaires encodés en base64).
  • Gros exports (et PDF/ZIP, toujours async, ou toute requête avec forceAsync: true) renvoient 202 Accepted avec un asyncJob décrivant le job et, une fois prêt, une downloadUrl. Vous pouvez aussi fournir une webhookUrl pour être notifié lorsque le fichier est prêt.

Authentification et scope​

Les endpoints board acceptent un Personal Access Token complet (cp_pat_) ou une Integration API Key (cp_key_), et exigent le scope access_boards. Voir Authentification pour les types de tokens et Gestion des erreurs pour la forme d'erreur standard.

Référence​