Zum Hauptinhalt springen

So funktioniert ein Board

Diese Seite erklärt das Board-Datenmodell und die Mechanik hinter jeder Board-Operation: wie Tabellen und Zeilen zusammenhängen, wie typisierte Spalten und Zellen funktionieren, wie Rich-Text und Dateianhänge sich verhalten, wie Zeilenkommentare und Sichtbarkeit gescoped sind, wie Zeilen-Authentifizierung funktioniert und wie Filterung, Sortierung und Exporte ausgewertet werden. Für eine schnelle Orientierung und Copy-Paste-Beispiele beginnen Sie mit der Boards-Einführung.

Das Datenmodell​

Boards bilden eine dreistufige Hierarchie:

  • Board — der Container auf oberster Ebene. Ein Board gruppiert zusammengehörige Tabellen.
  • Tabelle — gehört zu einem Board. Eine Tabelle definiert eine Menge von Spalten und hält Zeilen.
  • Zeile — ein einzelner Datensatz in einer Tabelle. Eine Zeile trägt einen Zellwert pro Spalte, plus eine Markdown-Beschreibung und optionale Kommentare.
Board
└── Table (columns: Name, Status, Owner, Notes…)
    ├── Row #1  (cells: "Acme", "In progress", …)
    ├── Row #2
    └── Row #3

Jede Zeile hat zwei Kennungen: eine interne _id (eine 24-stellige Object-ID, die in den meisten Endpunkten verwendet wird) und eine menschenfreundliche Zeilennummer (die kleine fortlaufende Nummer im Grid, z. B. 42). Sie können eine Zeile über beide abrufen.

Spalten und Zellen​

Die Spalten einer Tabelle haben jeweils eine columnId, ein label und einen type. Spaltentypen umfassen Status, Dropdown, Labels, Checkbox, Text, Paragraph, Link, Date, Email, Phone, Website, Number, Duration, Location und Users. Status-/Dropdown-/Labels-Spalten legen ihre wählbaren options offen (jeweils mit optionId, Label und Farbe); Status-Optionen tragen außerdem eine statusGroup von TODO, IN_PROGRESS oder DONE.

Beim Lesen einer Zeile erhalten Sie ein Array columns von Zellen, jeweils mit columnId und value. Link-Zellen verweisen auf andere Zeilen; Lookup-Zellen zeigen Werte aus verknüpften Zeilen.

Beim Schreiben einer Zeile übergeben Sie columns: [{ columnId, value }]. Einige Spaltentypen haben besondere Wertesemantik:

  • Link-Spalten erwarten ein Array von Zeilen-ID-Strings. [] leert den Link. Verknüpfte Zeilen müssen in der Ziel-Tabelle und im selben Workspace existieren.
  • Rich-Text- (Paragraph-)Spalten erwarten einen Markdown-String. Der Inhalt wird asynchron gesetzt und kann kurz nach dem Write erscheinen.
  • Duration-Spalten erwarten eine JSON-Zahl in Sekunden. Zum Beispiel steht 1800 für 30 Minuten. Formatierte Strings wie "00:30:00" sind ungültig.

Boards, Tabellen und Zeilen lesen​

  • Boards listen — liefert jedes Board, auf das Ihr Token zugreifen kann, optional mit q zum Filtern nach Name oder Beschreibung.
  • Board holen / Tabellen listen / Tabelle holen — in die Struktur eines Boards eintauchen und Spaltendefinitionen lesen.
  • Zeilen listen — liefert die Zeilen einer Tabelle. Unterstützt drei Query-Parameter, die zusammenwirken: q (groß-/kleinschreibungsunabhängige Suche über suchbare Spalten), filter (strukturierter JSON-Filter, siehe unten) und sort.
  • Zeile holen — über interne ID oder über Zeilennummer mit dem eigenen Row-Number-Endpunkt.

Zeilen filtern​

Der Query-Parameter filter ist ein JSON-String mit dieser Form:

{
  "match": "and",
  "conditions": [
    { "column_id": "<columnId>", "operator": "contains", "value": "acme" },
    { "column_id": "<statusColumnId>", "operator": "includes", "value": ["<optionId>"] }
  ]
}
  • match ist and (Standard) oder or.
  • conditions ist ein Array mit bis zu 20 Bedingungen. Jede nennt eine column_id, einen operator und (bei den meisten Operatoren) einen value.
  • Die gültigen Operatoren hängen vom Spaltentyp ab:
    • 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 (Werte sind Options-IDs).
    • Checkbox: equals, not_equals, is_empty, is_not_empty.
    • Date: equals, before, after, between (Wert ist ein Paar [startISO, endISO]), plus relative Operatoren ohne Wert wie today, last_7_days, current_month und is_empty / is_not_empty.

Eine unbekannte Spalten-ID oder ein Operator, der nicht zum Spaltentyp passt, liefert 400.

Zeilen sortieren​

Der Query-Parameter sort ist eine kommagetrennte Liste von Einträgen columnId:direction, wobei die Richtung asc (Standard) oder desc ist:

?sort=statusColumnId:asc,createdColumnId:desc
hinweis

Der HTTP-Query-String sort verwendet die Form columnId:direction. Manche SDK-Beispiele drücken Sortierung als Array von Objekten { column, dir } aus — beides beschreibt dieselbe Ordnung, nur in unterschiedlicher Form.

Zeilen schreiben​

  • Zeile anlegen — POST mit optionaler Markdown-description und einem Array columns (darf leer sein). Liefert die erzeugte Zeile.
  • Zeile aktualisieren — PATCH mit einem nicht leeren Array columns. Nur die gesendeten Spalten ändern sich; der Rest bleibt unberührt.
  • Zeile löschen — entfernt die Zeile dauerhaft.

Bots wirken wie Benutzer: Eine Aktion, die Ihr Token ausführt, kann die Automatisierungen des Boards auslösen, sodass programmatische Writes in dieselben Workflows greifen wie Ihr Team.

Zeilenbeschreibung und Rich-Text-Spalten​

Sowohl die Beschreibung einer Zeile als auch jede Rich-Text-Spalte sind Markdown. Lesen Sie sie mit dem entsprechenden …/md-GET-Endpunkt, der { "content": "…" } liefert.

Zum Schreiben POST mit operation replace, append oder prepend plus dem Markdown-content. Diese Writes werden asynchron verarbeitet und liefern HTTP 202 Accepted — der Inhalt erscheint kurz danach.

Dateianhänge​

FILE-Spalten speichern eine oder mehrere private Dateireferenzen in der Zeilenzelle. Über die Public API können Sie eine neue Datei per multipart/form-data direkt in eine FILE-Spaltenzelle hochladen, eine angehängte Datei über ihre fileId herunterladen oder eine Anhangsreferenz aus der Zelle entfernen.

Der Upload-Endpunkt hängt die hochgeladene Datei an den bestehenden Zellwert an und liefert die Anhangs-Metadaten (fileId, Name, MIME-Typ und Größe). Der Remove-Endpunkt löst nur diese fileId von der Zeilenzelle; er löscht weder den privaten Dateirekord noch die Bytes.

File-Spaltenzellen und Kommentar-Anhänge können direkt heruntergeladen werden. Die Download-Endpunkte streamen die rohen Dateibytes (mit passenden Content-Type- und Filename-Headern) statt einer signierten URL.

Zeilenkommentare​

Zeilen unterstützen threadbare Kommentare, jeweils mit einer Sichtbarkeit:

  • internal — nur für Workspace-Mitglieder sichtbar.
  • external — für alle mit Zeilenzugriff sichtbar, einschließlich Gäste.

Kommentare listen unterstützt Cursor-Paginierung (after / before) und einen Filter visibility von all (Standard), internal oder external. Kommentar anlegen nimmt HTML-content und eine visibility, die standardmäßig internal ist.

Zeile authentifizieren​

Tabellen können als leichter Credential-Store dienen. Der authenticate-Endpunkt nimmt Identifier-Spalte + Wert und Passwort-Spalte + Wert und liefert die passende Zeile (mit maskierten Passwort-Spalten), wenn die Credentials gültig sind:

  • 400 — keine Zeile passt zum Identifier.
  • 401 — das Passwort ist falsch.

So können Sie sign-in-artige Checks gegen eine Board-Tabelle bauen, ohne die Passwort-Zelle freizugeben.

Tabellen-View exportieren​

Der export-Endpunkt rendert eine Tabellen-View in eine Datei. Sie POSTen die viewId und ein format — CSV, XLSX, JSON, MARKDOWN, HTML, PDF, ZIP oder ICS — plus optionale Filter, Sortierung, Spaltenauswahl und formatbezogene Optionen.

Exporte laufen je nach Größe synchron oder asynchron:

  • Kleine Exporte liefern 200 OK mit der gerenderten Datei inline (Textformate als UTF-8, Binärformate base64-kodiert).
  • Große Exporte (sowie PDF/ZIP, die immer asynchron sind, oder jede Anfrage mit forceAsync: true) liefern 202 Accepted mit einem asyncJob, der den Job beschreibt, und sobald bereit einer downloadUrl. Sie können auch eine webhookUrl angeben, um benachrichtigt zu werden, wenn die Datei fertig ist.

Authentifizierung & Scope​

Board-Endpunkte akzeptieren ein volles Personal Access Token (cp_pat_) oder einen Integration API Key (cp_key_) und erfordern den Scope access_boards. Siehe Authentifizierung für Token-Typen und Fehlerbehandlung für das Standard-Fehlerformat.

Referenz​

  • Boards-Einführung — Orientierung, Quick Start und Parity.
  • Boards in der API-Referenz — jeder Board-, Tabellen-, Zeilen-, Kommentar-, Authenticate- und Export-Endpunkt mit Request-/Response-Schemas.
  • Paginierung — Cursor-Konventionen bei Zeilenkommentaren.
  • Rate Limits — Limits pro Endpunkt (Exporte sind enger limitiert als Reads).
  • Copera CLI und MCP-Server — dieselben Board-Operationen von der Kommandozeile und von KI-Clients.