Vai al contenuto principale

Come funziona una Board

Questa pagina spiega il modello dati delle board e le meccaniche dietro ogni operazione board: come si relazionano table e row, come funzionano colonne e celle tipizzate, come si comportano rich-text e allegati file, come sono scopati commenti di riga e visibility, come funziona l'autenticazione di riga e come vengono valutati filtri, sort ed export. Per un orientamento rapido ed esempi copy-paste, parti dall'introduzione Boards.

Il modello dati​

Le board formano una gerarchia a tre livelli:

  • Board — il contenitore di primo livello. Una board raggruppa table correlate.
  • Table — appartiene a una board. Una table definisce un set di colonne e contiene righe.
  • Row — un singolo record in una table. Una riga porta un valore di cella per ogni colonna, più una description markdown e commenti opzionali.
Board
└── Table (columns: Name, Status, Owner, Notes…)
    ├── Row #1  (cells: "Acme", "In progress", …)
    ├── Row #2
    └── Row #3

Ogni riga ha due identificatori: un _id interno (un object id di 24 caratteri usato nella maggior parte degli endpoint) e un row number human-friendly (il piccolo numero sequenziale mostrato nella griglia, es. 42). Puoi recuperare una riga con uno dei due.

Colonne e celle​

Le colonne di una table hanno ciascuna un columnId, una label e un type. I tipi di colonna includono status, dropdown, labels, checkbox, text, paragraph, link, date, email, phone, website, number, duration, location e users. Le colonne status/dropdown/labels espongono le loro options selezionabili (ciascuna con un optionId, label e color); le opzioni status portano anche un statusGroup di TODO, IN_PROGRESS o DONE.

Quando leggi una riga ottieni un array columns di celle, ciascuna chiave per columnId con un value. Le celle Link referenziano altre righe; le celle lookup mostrano valori presi da righe collegate.

Quando scrivi una riga passi columns: [{ columnId, value }]. Alcuni tipi di colonna hanno semantiche di valore speciali:

  • Colonne Link prendono un array di stringhe row-id. Passare [] azzera il link. Le righe collegate devono esistere nella table target e nello stesso workspace.
  • Colonne rich-text (paragraph) prendono una stringa markdown. Il contenuto viene seedato in modo asincrono, quindi può comparire un momento dopo che la scrittura ritorna.
  • Colonne Duration prendono un numero JSON che rappresenta secondi. Ad esempio, 1800 rappresenta 30 minuti. Stringhe formattate come "00:30:00" non sono valide.

Leggere boards, tables e rows​

  • List boards — restituisce ogni board a cui il token può accedere, con un q opzionale per filtrare per nome o description.
  • Get a board / List tables / Get a table — scendi nella struttura di una board e leggi le definizioni delle colonne di una table.
  • List rows — restituisce le righe di una table. Supporta tre query parameter che si compongono: q (ricerca case-insensitive sulle colonne ricercabili), filter (un filtro JSON strutturato, sotto) e sort.
  • Get a row — per id interno, oppure per row number usando l'endpoint dedicato row-number.

Filtrare le righe​

Il query parameter filter è una stringa JSON con questa forma:

{
  "match": "and",
  "conditions": [
    { "column_id": "<columnId>", "operator": "contains", "value": "acme" },
    { "column_id": "<statusColumnId>", "operator": "includes", "value": ["<optionId>"] }
  ]
}
  • match è and (default) o or.
  • conditions è un array di fino a 20 condizioni. Ciascuna nomina un column_id, un operator e (per la maggior parte degli operatori) un value.
  • Gli operatori validi dipendono dal tipo della colonna:
    • 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 (i valori sono option id).
    • Checkbox: equals, not_equals, is_empty, is_not_empty.
    • Date: equals, before, after, between (il valore è una coppia [startISO, endISO]), più operatori relativi senza value come today, last_7_days, current_month e is_empty / is_not_empty.

Un column id sconosciuto o un operatore che non si applica al tipo di colonna restituisce un 400.

Ordinare le righe​

Il query parameter sort è una lista separata da virgole di entry columnId:direction, dove direction è asc (default) o desc:

?sort=statusColumnId:asc,createdColumnId:desc
nota

La query string HTTP sort usa la forma columnId:direction. Alcuni esempi SDK esprimono lo sorting come array di oggetti { column, dir } — entrambi descrivono lo stesso ordinamento, solo in forme diverse.

Scrivere righe​

  • Create a row — POST con una description markdown opzionale e un array columns (che può essere vuoto). Restituisce la riga creata.
  • Update a row — PATCH con un array columns non vuoto. Solo le colonne che invii vengono cambiate; il resto resta intatto.
  • Delete a row — rimuove permanentemente la riga.

I bot agiscono come utenti: un'azione che il token esegue può triggerare le automazioni della board, quindi le scritture programmatiche si integrano con gli stessi workflow che usa il team.

Description di riga e colonne rich-text​

Sia la description di una riga sia qualsiasi colonna rich-text sono markdown. Leggile con l'endpoint GET …/md corrispondente, che restituisce { "content": "…" }.

Per scriverle, POST un operation di replace, append o prepend più il markdown content. Queste scritture sono elaborate in modo asincrono e restituiscono HTTP 202 Accepted — il contenuto arriva un momento dopo.

Allegati file​

Le colonne FILE memorizzano uno o più riferimenti a file privati sulla cella della riga. Tramite la Public API puoi caricare un nuovo file direttamente su una cella di colonna FILE con multipart/form-data, scaricare un file allegato per il suo fileId, o rimuovere un riferimento di allegato dalla cella.

L'endpoint di upload appende il file caricato al valore di cella esistente e restituisce i metadati dell'allegato (fileId, name, MIME type e size). L'endpoint di remove stacca solo quel fileId dalla cella della riga; non elimina il record di file privato sottostante né i byte.

Le celle di colonna file e gli allegati dei commenti possono essere scaricati direttamente. Gli endpoint di download streamano i byte grezzi del file (con gli header content-type e filename appropriati) anziché restituire un signed URL.

Commenti di riga​

Le righe supportano commenti a thread, ciascuno con una visibility:

  • internal — visibile solo ai membri del workspace.
  • external — visibile a chiunque abbia accesso alla riga, inclusi i guest.

List comments supporta paginazione cursor (after / before) e un filtro visibility di all (default), internal o external. Create a comment prende HTML content e una visibility che di default è internal.

Autenticare una riga​

Le table possono agire come un leggero store di credenziali. L'endpoint authenticate prende una colonna identifier + value e una colonna password + value, e restituisce la riga corrispondente (con le colonne password mascherate) quando le credenziali sono valide:

  • 400 — nessuna riga corrisponde all'identifier.
  • 401 — la password non è corretta.

Questo ti consente di costruire check in stile sign-in contro una table di board senza esporre la cella password.

Esportare una view di table​

L'endpoint export renderizza una view di table in un file. Fai POST del viewId e di un format — CSV, XLSX, JSON, MARKDOWN, HTML, PDF, ZIP o ICS — insieme a filtri opzionali, sort, selezione colonne e opzioni per-format.

Gli export girano in modo sincrono o asincrono a seconda della dimensione:

  • Export piccoli restituiscono 200 OK con il file renderizzato inline (formati testo come UTF-8, formati binari base64-encoded).
  • Export grandi (e PDF/ZIP, che sono sempre async, o qualsiasi richiesta con forceAsync: true) restituiscono 202 Accepted con un asyncJob che descrive il job e, una volta pronto, un downloadUrl. Puoi anche fornire un webhookUrl per essere notificato quando il file è pronto.

Autenticazione e scope​

Gli endpoint Board accettano un Personal Access Token completo (cp_pat_) o un'integration API key (cp_key_), e richiedono lo scope access_boards. Vedi Autenticazione per i tipi di token e Gestione errori per la forma di errore standard.

Riferimento​

  • Introduzione Boards — orientamento, Quick Start e parità.
  • Boards nell'API Reference — ogni endpoint board, table, row, comment, authenticate ed export con schemi request/response.
  • Paginazione — convenzioni cursor usate dai commenti di riga.
  • Rate limit — limiti per-endpoint (gli export sono limitati più strettamente delle letture).
  • Copera CLI e MCP server — le stesse operazioni board dalla riga di comando e dai client IA.