---
title: "Die Talkspirit Partner-API"
description: "Die Partner-API ist ein versionierter REST-Vertrag für namentlich benannte Integrationspartner. Sie wird mit einem API-Schlüssel authentifiziert, den ein Administrator Ihrer Organisation erstellt, und sie steht nicht für eine Selbstregistrierung offen."
category: integrations
section: api-and-webhooks
type: Reference
lastUpdated: 2026-11-16
locale: de
canonical: https://support.talkspirit.com/de/integrations/partner-api
---

# Die Talkspirit Partner-API


Talkspirit stellt eine REST-API unter dem Präfix `/v1` bereit, damit eine Integration die Mitglieder einer Organisation, ihre Struktur, ihre Meetings, Projekte, Ziele und Arbeitsvereinbarungen lesen und an einigen genau umrissenen Stellen schreiben kann, ohne dass jemand in der Talkspirit-Oberfläche arbeitet. Jede Antwort ist JSON, und die meisten Fehler sind ein RFC-7807-Problemdokument mit einem stabilen, maschinenlesbaren `code`. Ratenbegrenzung und Zeitüberschreitung sind die beiden Ausnahmen: ihre Antwortkörper haben eine eigene Form.

Es ist eine **Partner**-API, keine öffentliche. Der Ressourcenumfang ist bewusst eng, der Zugang wird pro benannter Integration bereitgestellt, und es gibt kein Entwicklerportal, in dem Sie sich anmelden oder selbst Zugangsdaten erzeugen könnten. Um einen Cloud-Speicher oder eine andere eingebaute Integration anzubinden, ist keine API-Arbeit nötig: siehe [Wie füge ich eine Integration hinzu oder entferne sie?](/de/integrations/enable-a-cloud-file-picker).

## Was vorhanden sein muss, damit ein Aufruf gelingt

Zwei Bedingungen, die beide bei der Talkspirit-Organisation liegen, mit der Sie sich integrieren:

1. **Das API-Modul ist für diese Organisation aktiviert.** Es ist ein optionales Modul und standardmäßig aus. Ohne es wird jede Anfrage mit `401` abgewiesen, selbst wenn der Schlüssel gültig ist. Wird das Modul später abgeschaltet, funktionieren bereits ausgegebene Schlüssel nach kurzer Verzögerung nicht mehr.
2. **Sie haben einen API-Schlüssel für diese Organisation.** Ein Administrator der Organisation erstellt ihn in der Administration unter Sicherheit auf der Seite **API**. Der Talkspirit-Support gibt keine Schlüssel heraus, und von der Partnerseite aus können Sie keinen erzeugen.

Bitten Sie den Administrator, dem die Organisation gehört, beides einzurichten. Das Vorgehen steht in [API-Token als Administrator verwalten](/de/integrations/manage-api-tokens-as-an-admin).

## Wo finde ich die Referenzdokumentation?

Die API dokumentiert sich selbst. Der Dienst veröffentlicht unter demselben Host, der die API bereitstellt:

- `/v1/docs`, eine interaktive Referenz, gerendert mit Scalar. Sie liest `/v1/openapi.json`, listet jede Operation mit ihren Schemata und kann Testanfragen direkt von der Seite senden.
- `/v1/openapi.json`, das maschinenlesbare OpenAPI-Dokument, zur Client-Generierung.

Beide sind ohne Zugangsdaten lesbar. `/v1/redoc` war früher eine eigene Leseseite und antwortet inzwischen mit `301` auf `/v1/docs`, es gibt also eine Referenzseite statt zwei.

Der Vertrag wird aus dem laufenden Dienst erzeugt und in der Continuous Integration geprüft, er kann also nicht von dem abweichen, was die API tatsächlich ausliefert. Behandeln Sie ihn als die Autorität: dieser Artikel erklärt die Form, die Referenz erklärt jedes Feld. Er trägt eine eigene Versionsnummer, unabhängig vom Pfad `/v1`: dieser Artikel wurde gegen **0.85.1** geprüft.

## Wie die Authentifizierung funktioniert

Übergeben Sie Ihren Schlüssel bei jeder Anfrage als Bearer-Token:

```http
Authorization: Bearer <Ihr API-Schlüssel>
```

Der Schlüssel ist eine opake Zeichenfolge, die mit `ts_partner_` beginnt. Talkspirit speichert nur einen Fingerabdruck davon, der vollständige Wert wird also einmal bei der Erstellung angezeigt und ist danach nicht wiederherstellbar. Ein verlorener Schlüssel wird ersetzt, nie zurückgeholt. Verwechseln Sie ihn nicht mit einem MCP-Schlüssel, der mit `tsk_` beginnt, von jedem Mitglied im eigenen Kontobereich erstellt wird und den separaten MCP-Endpunkt authentifiziert, nicht diese API.

Im Hintergrund prüft der Dienst Ihren Schlüssel und tauscht ihn gegen ein kurzlebiges Token eines technischen Benutzers, der Ihrer Integration zugeordnet ist. Ihre Integration sieht daher genau das, was dieser technische Benutzer sehen darf: die Kreise, Rollen und Boards, die ihm in der Organisation gegeben wurden, und, bei einer Aufgabe, die zu keinem Projekt gehört, nur die Aufgaben, die dieser Benutzer im Produkt sehen darf. Ein Geltungsbereich auf dem Schlüssel erweitert das nie.

Behandeln Sie den Schlüssel wie ein Passwort. Halten Sie ihn aus der Versionsverwaltung heraus und bitten Sie den Administrator, ihn zu widerrufen und neu auszugeben, falls er je offengelegt wird. Der Widerruf wirkt sofort, mit einem Kulanzfenster von bis zu etwa fünf Minuten für ein bereits getauschtes Token.

## Was die API bereitstellt

Achtundsechzig Operationen unter `/v1`, plus `GET /healthz`. Siebzehn davon schreiben; alle anderen lesen.

| Ressource | Lese-Endpunkte | Geltungsbereich |
| --- | --- | --- |
| Benutzer | `GET /v1/users`, `GET /v1/users/{user_id}`, `GET /v1/users/{user_id}/memberships` | `users:read` |
| Alle Mitgliedschaften der Organisation | `GET /v1/memberships` | `users:read` |
| Kreise | `GET /v1/circles`, `GET /v1/circles/{circle_id}`, `GET /v1/circles/{circle_id}/members` | `circles:read` |
| Rollen | `GET /v1/roles`, `GET /v1/roles/{role_id}`, `GET /v1/roles/{role_id}/members` | `roles:read` |
| Rollenvorlagen | `GET /v1/role-templates`, `GET /v1/role-templates/{role_template_id}` | `roles:read` |
| Definitionen benutzerdefinierter Felder | `GET /v1/custom-fields` | `roles:read`, `circles:read` oder `users:read`, je nach angefragtem `entity_type` |
| Meetings | `GET /v1/meetings`, `GET /v1/meetings/{meeting_id}`, `GET /v1/meetings/{meeting_id}/agenda-items` | `meetings:read` |
| Projekte | `GET /v1/projects`, `GET /v1/projects/{project_id}`, `GET /v1/projects/{project_id}/comments` | `projects:read` |
| Abschnitte | `GET /v1/sections`, `GET /v1/sections/{section_id}` | `projects:read` |
| Labels | `GET /v1/labels`, `GET /v1/labels/{label_id}` | `projects:read` |
| Aufgaben | `GET /v1/tasks`, `GET /v1/tasks/{task_id}`, `GET /v1/tasks/{task_id}/comments` | `tasks:read` |
| Ziele | `GET /v1/goals`, `GET /v1/goals/{goal_id}`, `GET /v1/goals/{goal_id}/key-results`, `GET /v1/goals/{goal_id}/comments` | `goals:read` |
| Zeiträume | `GET /v1/time-periods`, `GET /v1/time-periods/{time_period_id}` | `goals:read` |
| Arbeitsvereinbarungen | `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` |
| Strukturexporte | `GET /v1/structure-exports/{export_id}`, `GET /v1/structure-exports/{export_id}/file`, nach einem `POST /v1/structure-exports`, das den Export startet | `structure_export:read` |
| Zielexporte | `GET /v1/goal-exports/{export_id}`, `GET /v1/goal-exports/{export_id}/file`, nach einem `POST /v1/goal-exports`, der den Export startet | `goal_export:read` |
| Aufgabenexporte | `GET /v1/task-exports/{export_id}`, `GET /v1/task-exports/{export_id}/file`, nach einem `POST /v1/task-exports`, der den Export startet | `task_export:read` |
| Mitgliederexporte | `GET /v1/user-exports/{export_id}`, `GET /v1/user-exports/{export_id}/file`, nach einem `POST /v1/user-exports`, der den Export startet | `user_export:read` |
| Exporte von Checklisten und Kennzahlen | `GET /v1/checklist-metric-exports/{export_id}`, `GET /v1/checklist-metric-exports/{export_id}/file`, nach einem `POST /v1/checklist-metric-exports`, der den Export startet | `checklist_metric_export:read` |
| Aktivitätsverlauf | `GET /v1/activities` | `activity:read` |
| Aktivitätsprotokoll | `GET /v1/audit-logs` | `audit_log:read` |
| Ihre eigene Identität | `GET /v1/whoami` | keiner |

Zwei Zuordnungen sind bemerkenswert, weil sie dem Pfadnamen nicht folgen: Abschnitte und Labels werden mit `projects:read` gelesen, Zeiträume mit `goals:read`.

Der Text einer Arbeitsvereinbarung ist eine eigene Unterressource, `GET /v1/documents/{document_id}/content`, eine Liste von Dokumenten trägt also nie eine Seite voller Volltexte. Sie liefert die Fassung, die das Konto des Schlüssels im Produkt sieht: die veröffentlichte, oder den neuesten Entwurf, solange nichts veröffentlicht wurde. Eine Arbeitsvereinbarung, die es gibt, die aber keinen Text enthält, antwortet mit `200` und leerem Text statt mit `404`.

`GET /v1/memberships` liefert alle Mitgliedschaften der Organisation, eine Seite pro Aufruf: ein vollständiger Abgleich der Struktur kostet also so viele Aufrufe, wie es Seiten gibt, und nicht einen Aufruf pro Mitglied. Jede Zeile ist genau eine Zeile von `GET /v1/users/{user_id}/memberships`, mit der `user_id` des Mitglieds. Übergeben Sie `?updated_since=`, um nur die Mitgliedschaften zu erhalten, die seit einem bestimmten Zeitpunkt hinzugefügt oder bearbeitet wurden; ein solcher Durchlauf kann eine entfernte Mitgliedschaft nicht sehen, gleichen Sie also von Zeit zu Zeit mit einem vollständigen Durchlauf ab.

`GET /v1/audit-logs` ist das Aktivitätsprotokoll der Organisation, das Neueste zuerst: Anmeldungen (erfolgreiche und abgelehnte), Veröffentlichungen, Kommentare sowie Beitritte zu und Austritte aus Gruppen. Da es alle Mitglieder abdeckt, muss das Konto hinter dem Schlüssel Administrator der Organisation sein, und der Schlüssel muss zusätzlich `audit_log:read` tragen. Übergeben Sie `?occurred_after=`, um nur zu lesen, was seit einem bestimmten Zeitpunkt geschehen ist.

`/v1/structure-exports` erzeugt die Datei des Bildschirms **Organisation exportieren**: die Kreise, die Rollen und wer sie innehat, mit der E-Mail-Adresse jedes Rolleninhabers, und die geltenden Richtlinien, als XLSX-Arbeitsmappe (Standard) oder als ZIP-Archiv mit CSV-Dateien. `POST /v1/structure-exports` startet den Export im Hintergrund und antwortet mit `202`, seine Adresse steht im Header `Location`. Fragen Sie `GET /v1/structure-exports/{export_id}` ab, bis `status` `completed` oder `failed` ist, und rufen Sie dann `GET /v1/structure-exports/{export_id}/file` auf. Die Route antwortet mit `302` auf die Datei, die Sie vor `file_expires_at` abholen müssen; danach antwortet sie mit `410`. Ein Schlüssel kann einen Export 24 Stunden nach seinem Ende lesen, und nur, wenn er als das Konto handelt, das ihn gestartet hat. Da die Datei die E-Mail-Adresse jedes Mitglieds enthält, muss das Konto hinter dem Schlüssel Administrator der Organisation sein, wie beim Aktivitätsprotokoll. Die Organisation kann pro gleitender Stunde zehn Exporte starten, die von diesem Bildschirm aus gestarteten eingeschlossen (siehe Ratenbegrenzung).

`GET /v1/activities` ist der Verlauf, wer wen in der Struktur wohin gesetzt hat. `type=assignment` ist Pflicht und derzeit der einzige Wert: Er listet jedes Mal auf, wenn ein Mitglied auf eine Rolle gesetzt oder von ihr entfernt, oder zu einem Kreis hinzugefügt oder aus ihm entfernt wurde, das Neueste zuerst. Eine Zeile enthält `member_id` (das Mitglied, um das es bei der Änderung geht), `actor_id` (das Mitglied, das sie vorgenommen hat), `action` (`assigned` oder `unassigned`), `occurred_at` und entweder `role_id` und `role_name` oder `circle_id` und `circle_name`. Beide Mitglieds-IDs sind die `id`, die `GET /v1/users` zurückgibt. `cause` nennt den Grund, wenn der Akteur die Änderung nicht direkt vorgenommen hat (`election`, `left_circle`, `left_source_role`, `member_suspended`, `invited_role_copy` oder `other`; behandeln Sie jeden anderen Wert als künftigen Wert), und `reason` ist der Text des Akteurs. Filtern Sie mit `member`, `actor`, `role_id`, `circle_id` (der auch die Änderungen an den Rollen dieses Kreises und die Mitgliedschaftsänderungen seiner direkten Unterkreise liefert) und einem Zeitfenster `occurred_after` / `occurred_before`, Grenzen eingeschlossen; die Filter werden kombiniert. Durchlaufen Sie die Seiten mit dem `cursor` und senden Sie auf jeder Seite denselben `type` und dasselbe Fenster erneut. Verwechseln Sie ihn nicht mit dem weiter oben beschriebenen Aktivitätsprotokoll, das Anmeldungen, Veröffentlichungen und Kommentare erfasst.

Der Schlüssel liest, was sein Konto in der Aktivitätsansicht der App sieht: Der Schlüssel eines Gasts liest daher nur die Änderungen, die ihn betreffen, und eine Administratorrolle ist nicht nötig. Vier Grenzen sind wichtig, bevor Sie sich darauf verlassen:

- **Der Verlauf ist jung.** Er beginnt am 5. November 2026, außer bei Wahlen, die ab dem 21. September 2026 erfasst sind. Frühere Änderungen und aus Holaspirit migrierte Zuweisungen haben keine Zeile: Für sie liefert `assigned_at` auf `GET /v1/roles/{role_id}?include=members` das Datum, aber nicht den Urheber. Eine leere Seite bedeutet also „in diesem Zeitraum nichts erfasst“, nie „nichts ist passiert“.
- **`actor_id` kann `null` sein.** Keine Person hat die Änderung vorgenommen: Die Plattform hat sie selbst vorgenommen, zum Beispiel wenn ein gesperrtes Mitglied von seinen Rollen gelöst wird oder wenn eine Wahl automatisch angenommen wird, nachdem ihr Vorschlag abgelaufen ist. Solche Zeilen passen nie auf einen `actor`-Filter: Um sie zu lesen, durchlaufen Sie die Sammlung ohne `actor` und behalten Sie die Zeilen, deren `actor_id` `null` ist (die Angabe der ausschließlich aus Nullen bestehenden ID wird abgelehnt, siehe Fehlertabelle).
- **Eine Rollenzeile trägt ihren Kreis nicht.** Lesen Sie ihn über `GET /v1/roles/{role_id}`.
- **Manche Austritte werden nicht erfasst:** solche, die durch das Löschen einer Rolle oder eines Kreises oder durch das Löschen der Daten eines Mitglieds ausgelöst werden, sowie die Kreismitgliedschaft, die eine Rollenbesetzung mit sich bringt.

Die Zeilen von `GET /v1/goals/{goal_id}/key-results` tragen zwei Arrays, `task_ids` und `project_ids`: die mit diesem Key Result verknüpften Aufgaben und Projekte, die das Konto des Schlüssels sehen kann, jede ID einmal, und `[]`, wenn es keine gibt. Ein verknüpftes Element, das das Konto nicht sehen kann, und ein archiviertes werden nicht aufgeführt, und die Reihenfolge der IDs hat keine Bedeutung. Zum Lesen genügt `goals:read`; das Element selbst lesen Sie mit `GET /v1/tasks/{task_id}` (`tasks:read`) oder `GET /v1/projects/{project_id}` (`projects:read`).

Vier weitere Exporte funktionieren wie der Strukturexport: `/v1/goal-exports` (Ziele und Key Results, XLSX), `/v1/task-exports` (Aufgaben und Projekte, XLSX), `/v1/user-exports` (Mitglieder mit ihren E-Mail-Adressen, CSV) und `/v1/checklist-metric-exports` (Checklisten und Kennzahlen, XLSX). Jeder liefert die Datei des entsprechenden Administrationsbildschirms. Sie starten ihn mit einem `POST`, der `202` und einen `Location`-Header zurückgibt, fragen `GET .../{export_id}` ab, bis `status` `completed` oder `failed` ist, und laden dann `GET .../{export_id}/file` (ein `302`) vor `file_expires_at` herunter. Ein Lauf bleibt 24 Stunden lesbar. Das Konto hinter dem Schlüssel muss Administrator der Organisation sein, und für den Zielexport muss das Modul Ziele, für den Aufgabenexport das Modul Projekte aktiv sein; andernfalls antwortet der Start mit `403 FORBIDDEN_UPSTREAM`. Die Ziel- und Aufgabendateien enthalten private Elemente nur, solange die Administratoraufsicht der Organisation aktiv ist, und der Lauf zeigt das in `includes_private_content` an. In der Datei der Checklisten und Kennzahlen enthält die Spalte Recurrence eines von acht voreingestellten Wörtern (`DAILY` bis `YEARLY`) oder, bei einem Element mit eigenem Zeitplan, `CUSTOM: ` gefolgt von der Regel in englischen Worten und ihrem Startdatum. Behandeln Sie diesen Text als Bezeichnung, nicht als Format, das Sie auswerten.

An den Zugewiesenen einer Aufgabe (`?include=assignees` bei `GET /v1/tasks` und `GET /v1/tasks/{task_id}`) geben vier nullbare Felder, `via_role_id`, `via_role_name`, `via_role_circle_id` und `via_role_circle_name`, die Rolle an, in der das Mitglied der Aufgabe zugewiesen wurde, so wie sie damals erfasst wurde, und den Kreis, in dem diese Rolle definiert ist. Es kann eine Rolle sein, die das Mitglied nicht mehr innehat oder die inzwischen entfernt wurde: Sind die Namen einer entfernten Rolle nicht mehr lesbar, bleibt `via_role_id` gesetzt und die anderen drei sind `null`. Alle vier sind `null` bei Kreis-, Rollen- und Gruppenzeilen und bei einem Mitglied, das ohne Rolle zugewiesen wurde.

`GET /v1/meetings/{meeting_id}/agenda-items` liefert die vollständige Tagesordnung eines Meetings, jeden Punkt darauf, gleich wer ihn hinzugefügt hat, in der Reihenfolge, in der das Meeting sie abarbeitet. Ein Punkt, der aus einer Tension auf die Tagesordnung gesetzt wurde, trägt die Id dieser Tension in `source_tension_id`; ein direkt im Meeting getippter Punkt hat keine und ist keine Tension, die Tension-Endpunkte liefern ihn also nie. `POST` auf demselben Pfad fügt einen Punkt am Ende der Tagesordnung hinzu; siehe die Schreiboperationen unten.

Eine Aufgabe trägt ihren Platz in einem Baum aus Unteraufgaben und ihren Text. Jede Aufgabe hat `parent_task_id` (`null` bei einer Aufgabe der obersten Ebene) und `subtask_count`, die Zahl ihrer nicht archivierten Unteraufgaben, ohne die privaten, die das Konto des Schlüssels nicht sehen darf; die Liste mit `?parent_task_id=` wendet die volle Leseregel an und kann daher weniger enthalten. `GET /v1/tasks` listet die Aufgaben der obersten Ebene. Übergeben Sie `?parent_task_id=` mit der Id einer Aufgabe, um stattdessen deren Unteraufgaben zu listen; eine Id, die keine für das Konto lesbare Aufgabe benennt, listet nichts, und ein Wert, der keine Aufgaben-Id ist, wird mit `400 INVALID_PARENT_TASK_ID` abgelehnt. Eine Unteraufgabe wird wie jede Aufgabe über ihre eigene Id gelesen. `GET /v1/tasks/{task_id}` und die Antwort von `POST /v1/tasks` tragen immer `description` und `description_format` (`blocknote_json` oder `text`); in der Liste fordern Sie sie mit `?include=description` an. `?include=attachments` listet die an eine Aufgabe hochgeladenen Dateien (`id`, `name`, `size`, `content_type`, `added_at`). Es liefert keinen Download-Link, und an eine Aufgabe angehängte Links werden nicht gelistet.

Mehrere Listen akzeptieren außerdem Filter, zum Beispiel die Rollen, die ein Mitglied innehat, die Kreise, denen ein Mitglied angehört, die mit einer Rollenvorlage verknüpften Rollen, die Aufgaben oder Meetings, an denen ein Mitglied beteiligt ist, die Unteraufgaben einer Aufgabe, oder die Tensions auf der Tagesordnung eines Meetings. Die Referenzdokumentation listet jeden Filter, den ein Endpunkt akzeptiert.

### Felder, die eine Erläuterung brauchen

Mehrere Felder tragen mehr Bedeutung, als ihr Name vermuten lässt.

- **`last_activity_at`, an einem Mitglied.** `GET /v1/users`, `GET /v1/users/{user_id}` und die Antwort von `PATCH /v1/users/{user_id}` veröffentlichen die zuletzt erfasste Aktivität des Mitglieds. Es ist ein Aktivitätssignal, keine Anmeldung: Es wird erfasst, wenn ein authentifiziertes Mitglied das Produkt nutzt, und etwa einmal pro Stunde aktualisiert statt bei jeder Anfrage. Lesen Sie es also als „kürzlich aktiv“ und niemals als Authentifizierungsereignis. Es ist `null`, wenn nie eine Aktivität erfasst wurde, und bei einem anonymisierten Mitglied. Aufrufe, die Sie mit Ihrem eigenen Schlüssel machen, erfassen Aktivität für den technischen Benutzer hinter dem Schlüssel, nie für die Mitglieder, die er liest oder ändert.
- **`avatar_url`, an einem Mitglied.** `GET /v1/users`, `GET /v1/users/{user_id}` und die Antwort von `PATCH /v1/users/{user_id}` veröffentlichen die Adresse des aktuellen Profilbilds des Mitglieds, wenn Talkspirit es hostet. Sie ist `null`, wenn das Mitglied kein Bild hat und wenn das Bild ein Link auf eine andere Website ist. Talkspirit fügt dieser Adresse weder Token noch Signatur hinzu: Wer sie kennt, kann das Bild herunterladen, und sie ändert sich, wenn das Mitglied sein Bild wechselt, speichern Sie sie also nicht als dauerhaften Link.
- **`assigned_at` und `updated_at`, an einer Zuordnung.** Jede Zeile von `GET /v1/roles/{role_id}/members`, `GET /v1/circles/{circle_id}/members`, `GET /v1/users/{user_id}/memberships` und `GET /v1/memberships` sowie jede Mitgliedszeile, die `GET /v1/roles` und `GET /v1/roles/{role_id}` mit `?include=members` zurückgeben, trägt beide. Die einzige Ausnahme ist eine Vertreterzeile von `GET /v1/circles/{circle_id}/members`, unten beschrieben: Sie steht für keine Zuordnung in diesem Kreis, daher sind dort beide `null`. `assigned_at` ist der Zeitpunkt, an dem die Zuordnung begann: bei einer aus Holaspirit migrierten Organisation das Datum, das die Zuordnung dort hatte, und nicht das Datum der Migration. Zeilen, deren Quelle kein solches Datum trug, fallen auf den Zeitpunkt ihres Importlaufs zurück – daran erkennen Sie sie, denn sie teilen sich alle einen Wert. `updated_at` ist der Zeitpunkt, an dem die Zeile zuletzt geschrieben wurde: ihre Bezeichnung, ihre Entscheider- und Administrator-Kennzeichen, ein Weggang oder eine Rückkehr. Es bewegt sich nicht, wenn sich eine Allokation ändert, es ist also kein Strom von Zuordnungsänderungen, und keines der beiden Felder ist eine Zuordnungshistorie.
- **`expires_at` und `mandate_kind`, an einer Zuordnung.** Sie stehen in denselben Zeilen wie `assigned_at` und sind immer vorhanden, ob `null` oder nicht. `expires_at` ist das Enddatum, das an der Zuordnung gesetzt wurde, ein Kalendertag in der Schreibweise `JJJJ-MM-TT`, oder `null`, wenn sie keines hat, was der Normalfall ist. `mandate_kind` sagt, warum die Zuordnung ein Enddatum hat, wenn das erfasst wurde: `ELECTED` für einen in die Rolle gewählten Inhaber, `INTERIM` für einen ohne Wahl eingesetzten Inhaber einer Rolle, die normalerweise eine Wahl verlangt, und `null` für eine gewöhnliche Zuordnung. Behandeln Sie jeden anderen Wert als künftigen Wert.
- **Vertreter in der Mitgliederliste eines Kreises.** `GET /v1/circles/{circle_id}/members` listet zuerst die Mitglieder des Kreises selbst, dann seine Vertreter: alle, die in einem direkt darin verschachtelten Kreis eine Rolle mit der Einstellung **Vertritt den Unterkreis** innehaben. Sie nehmen an den Entscheidungen des Kreises teil, ohne ihm zugeordnet zu sein. Sie folgen auf die Mitglieder, nach `user_id` sortiert, in denselben Seiten und unter demselben Cursor, und wer zugleich Mitglied und Vertreter ist, erscheint nur einmal, als Mitglied. Eine Vertreterzeile nennt keine Rolle: `role_id`, `role_name`, `scope`, `assigned_at`, `updated_at`, `expires_at` und `mandate_kind` sind `null`, `is_decision_maker` ist `true` und `is_circle_admin` ist `false`. Ein Skript, das die Mitglieder eines Kreises durchläuft, erhält daher auch diese Zeilen und sollte ein `assigned_at` mit `null` nicht als Fehler behandeln.
- **`content_restricted_to_members` und `meeting_reports_restricted_to_members`, an einem Kreis.** Das sind die beiden Datenschutz-Einstellungen des Kreises, nur lesbar. Die erste ist `true`, wenn der Kreis seine Inhalte, also die Dokumente des Kreises und seiner Rollen sowie seine Links, nur seinen Mitgliedern vorbehält. Die zweite ist `true`, wenn die Protokolle seiner Meetings nur für seine Mitglieder sichtbar sind. Beide sind `true`, solange niemand sie geöffnet hat. Sie beschreiben den Kreis und ändern nichts daran, was Ihr Schlüssel liest, nämlich immer das, was sein Konto sehen darf. `null` heißt, dass die Einstellung nicht gelesen werden konnte, nicht, dass der Kreis offen ist.
- **`assignees`, an einem Projekt.** `GET /v1/projects` und `GET /v1/projects/{project_id}` akzeptieren `?include=assignees`. Es listet die Kreise und Rollen, denen das Projekt zugeordnet ist, jeweils mit `assignee_type` (`CIRCLE` oder `ROLE`), `assignee_id`, `assignee_name`, `project_role` (`OWNER`, `EDITOR`, `CONTRIBUTOR` oder `VIEWER`, der Zugriff, den diese Zuordnung auf das Projekt gibt) und `assigned_at`. Einzelne Mitglieder und Gruppen, die dem Projekt zugeordnet sind, werden nicht gelistet, die Liste ist also nicht die aller, die das Projekt öffnen können.
- **`options`, an der Definition eines Mitglieds-Zusatzfelds.** `GET /v1/custom-fields?entity_type=user` veröffentlicht den vollständigen Optionskatalog jedes Felds mit Einfach- und Mehrfachauswahl, wo es zuvor nichts veröffentlichte: jede konfigurierte Option, auch die, die noch kein Mitglied trägt, als Paar `{value, label}`. `value` ist die Options-Id, die `PATCH /v1/users/{user_id}/custom-fields` annimmt; `label` ist das, als was der Wert eines Mitglieds meist zu lesen ist. Ordnen Sie den Wert eines Mitglieds daher zuerst über `label` zu und über `value`, wenn das fehlschlägt, und rechnen Sie damit, dass zwei Optionen desselben Felds dieselbe Bezeichnung tragen können. Die Optionen kommen nach Bezeichnung sortiert, bis zu 5.000 pro Feld, und `options_truncated` an derselben Definition sagt, ob diese Grenze gegriffen hat. Ein Auswahlfeld ohne konfigurierte Option meldet eine leere Liste; `null` bedeutet weiterhin, dass der Feldtyp überhaupt keine Optionsliste hat. Die Werte aus `GET /v1/users?include=custom_fields` sind unverändert.

- **`source_template_id`, an einer Rolle.** Die Rollenvorlage, mit der die Rolle verknüpft ist, die Id, die `GET /v1/role-templates` zurückgibt, oder `null`, wenn sie mit keiner verknüpft ist. Eine Rolle beginnt verknüpft mit der Vorlage, aus der sie erstellt wurde, doch die Verknüpfung kann sich im Leben der Rolle ändern, in der App über einen Vorschlag oder den Architect-Modus: Der Wert kann von `null` auf eine Id wechseln, von einer Id auf eine andere oder zurück auf `null`, und eine Verknüpfung oder ihre Aufhebung setzt `updated_at` weiter. Das endgültige Löschen einer Rollenvorlage leert den Wert bei allen mit ihr verknüpften Rollen, ohne deren `updated_at` weiterzusetzen. `GET /v1/roles?source_template_id=` listet die Rollen auf, die zum Zeitpunkt des Aufrufs mit der Vorlage verknüpft sind. Eine Rollenvorlage ist eine wiederverwendbare Rollendefinition, etwa „Sekretär“. Eine eingeladene Kopie einer Rolle liest sich als `null`: ihre `source_role_id` führt zu der Rolle, die die Vorlage trägt. Wurde Ihre Organisation aus Holaspirit migriert, haben sich die Vorlagen-Ids mit der Migration geändert, lesen Sie sie also erneut aus `GET /v1/role-templates`.
- **Die persönlichen Felder eines Mitglieds.** `email`, `phone`, `last_activity_at` und die Werte der benutzerdefinierten Felder erreichen Ihren Schlüssel so, wie sie den technischen Benutzer im Produkt erreichen. Ein Administrator liest sie alle. Ein Mitglied liest sie alle bis auf eine E-Mail-Adresse, die ihr Inhaber ausgeblendet hat. Ein Gast, der mit diesem Mitglied keine aktive Gruppe teilt, liest keines davon. Ein zurückgehaltenes Feld ist `null`. Der technische Benutzer hinter einem Schlüssel ist meist kein Administrator, rechnen Sie also damit, dass `email` bei Mitgliedern, die sie ausgeblendet haben, `null` ist.
- **`priority`, an einer Tension.** Sie kann `NONE` sein, was bedeutet, dass niemand eine gesetzt hat, und das ist es, was eine ohne Priorität erstellte Tension jetzt erfasst. Behandeln Sie einen Wert, den Sie nicht kennen, als künftigen Wert und nicht als Fehler.

**Der Typwechsel eines Auswahlfelds verschiebt seine Werte zwischen zwei Slots.** Ein Feld, das ein Administrator von Einfach- auf Mehrfachauswahl umstellt, wird nicht mehr als `value`, ein einzelner Wert, gelesen, sondern als `values`, eine Liste – und ein Schreibvorgang muss denselben Slot verwenden. Der falsche wird mit einem `422 INVALID_CUSTOM_FIELD_VALUE` abgelehnt, dessen Meldung den zu verwendenden Slot nennt; still umgewandelt wird nie.

### Die siebzehn Schreiboperationen

| Operation | Geltungsbereich | Was Sie wissen müssen |
| --- | --- | --- |
| `POST /v1/tasks` | `tasks:write` | Erzeugt bei jedem Aufruf eine Aufgabe, ein blindes Wiederholen ist also nicht sicher. Der optionale Parameter `section_id` benennt die Spalte des Projekts, in die die Aufgabe kommt; ohne ihn wählt Talkspirit den ersten Abschnitt des Projekts, der nicht für erledigte oder blockierte Arbeit gedacht ist. Ein `Idempotency-Key`-Header wird mit `400` abgelehnt. |
| `POST /v1/tensions` | `tensions:write` | Erzeugt eine Tension. Eine weggelassene `priority` erfasst `NONE`. Mit `created_by_id` wird die Tension im Namen eines Mitglieds erfasst, das ihr Ersteller wird: Sie erscheint unter seinen Tensions, und es darf sie bearbeiten. Das Konto Ihres Schlüssels ist dann nicht mehr ihr Ersteller, `PATCH` und `DELETE` darauf antworten also mit `404`. Zum Senden von `created_by_id` brauchen Sie zusätzlich den Geltungsbereich `tensions:write_on_behalf` (sonst `403 FORBIDDEN_SCOPE`). Eine Id, die kein aktives Mitglied außer Gästen benennt, wird mit `422 UNKNOWN_MEMBER` abgelehnt. Senden Sie einen `Idempotency-Key`-Header, damit eine Wiederholung sicher ist, wie unter der Tabelle beschrieben. |
| `PATCH /v1/tensions/{tension_id}` | `tensions:write` | Bearbeitet eine Tension. |
| `PATCH /v1/tensions/{tension_id}/status` | `tensions:write` | Bewegt eine Tension durch ihre Status. Eine Tension, die ein noch laufender Vorschlag trägt, zu schließen oder zu lösen, wird mit `422 TENSION_CARRIED_BY_LIVE_PROPOSAL` abgelehnt: Lassen Sie den Vorschlag in Talkspirit annehmen, ablehnen oder zurückziehen und senden Sie die Änderung dann erneut. |
| `DELETE /v1/tensions/{tension_id}` | `tensions:delete` | **Eine harte Löschung ohne Rückholmöglichkeit.** Siehe unten. |
| `POST /v1/tensions/{tension_id}/links` | `tensions:write` | Hält fest, was aus einer Tension geworden ist, indem ein Element an sie angehängt wird. Nicht idempotent. Siehe unten. |
| `DELETE /v1/tensions/{tension_id}/links/{link_id}` | `tensions:delete` | Entfernt das aktuelle Ergebnis der Tension. **Nicht rückgängig zu machen.** Siehe unten. |
| `POST /v1/meetings/{meeting_id}/agenda-items` | `meetings:write` | Fügt am Ende der Tagesordnung eines Meetings einen Punkt hinzu, optional aus einer bestehenden Tension (`source_tension_id`). Sie erzeugt bei jedem Aufruf einen Punkt, ein blindes Wiederholen ist also nicht sicher: lesen Sie vor dem erneuten Senden die Tagesordnung, was zusätzlich `meetings:read` erfordert. Eine Tension kann nur auf der Tagesordnung eines einzigen noch nicht beendeten Meetings stehen. |
| `POST /v1/structure-exports` | `structure_export:read` | Startet einen Strukturexport, oben beschrieben. Es startet bei jedem Aufruf einen neuen Export, ein blindes Wiederholen ist also nicht sicher, und ein `Idempotency-Key`-Header wird mit `400` abgelehnt. Es liegt hinter einem Lese-Geltungsbereich, obwohl es ein `POST` ist, denn dem Schlüssel wird anvertraut, das ganze Register zu lesen. |
| `POST /v1/goal-exports` | `goal_export:read` | Startet einen Zielexport, siehe oben. Dieselben Regeln wie bei `POST /v1/structure-exports`: bei jedem Aufruf ein neuer Export, und ein `Idempotency-Key`-Header wird mit `400` abgelehnt. Das Konto Ihres Schlüssels kann jeweils einen ausführen (sonst `429 EXPORT_ALREADY_RUNNING`). |
| `POST /v1/task-exports` | `task_export:read` | Startet einen Aufgabenexport, siehe oben. Dieselben Regeln wie bei `POST /v1/goal-exports`. |
| `POST /v1/user-exports` | `user_export:read` | Startet einen Mitgliederexport, siehe oben. Dieselben Regeln wie bei `POST /v1/goal-exports`. Die Datei enthält die E-Mail-Adresse jedes Mitglieds. |
| `POST /v1/checklist-metric-exports` | `checklist_metric_export:read` | Startet einen Export von Checklisten und Kennzahlen, siehe oben. Bei jedem Aufruf ein neuer Export, und ein `Idempotency-Key`-Header wird mit `400` abgelehnt. |
| `PATCH /v1/users/{user_id}` | `users:write` | Bearbeitet ein Mitglied. |
| `PATCH /v1/users/{user_id}/custom-fields` | `users:write` | Setzt Werte benutzerdefinierter Felder an einem Mitglied. |
| `PATCH /v1/circles/{circle_id}/custom-fields` | `circles:write` | Setzt Werte benutzerdefinierter Felder an einem Kreis. |
| `PATCH /v1/roles/{role_id}/custom-fields` | `roles:write` | Setzt Werte benutzerdefinierter Felder an einer Rolle. |

**Das Löschen einer Tension ist unwiderruflich.** Die Tension und ihre Verknüpfungen sind weg, und kein Lesezugriff gibt sie danach zurück. Die Operation liegt hinter ihrem eigenen Geltungsbereich `tensions:delete`, den `tensions:write` bewusst nicht mitgewährt, damit diese Fähigkeit ausdrücklich erteilt und nicht geerbt wird. Eine Tension ist außerdem nur von ihrem Ersteller löschbar: ein Schlüssel kann die Tensions löschen, die sein eigener technischer Benutzer erstellt hat, und nichts anderes.

**Festhalten, was aus einer Tension geworden ist.** `POST /v1/tensions/{tension_id}/links` hängt einen Vorschlag, eine Aufgabe, ein Projekt, einen Tagesordnungspunkt oder ein Ziel als aktuelles Ergebnis an eine Tension an: Senden Sie `linked_item_type`, `linked_item_id`, `linked_service` und eine optionale `note`, und Sie erhalten `201` mit der Verknüpfung, wie `GET /v1/tensions/{tension_id}?include=links` sie auflistet. Das Anhängen eines anderen Elements ersetzt das aktuelle Ergebnis, und das Anhängen eines Vorschlags setzt die Tension auf `PROCESSING`. Nur eine Tension im Status `OPEN` oder `PARKED` kann umgewandelt werden (sonst `422 BUSINESS_RULE_VIOLATION`), und ein Element kann nur an eine einzige Tension angehängt werden (`422 CONFLICT`). Das Element selbst wird nicht nachgeschlagen: Eine ID, die nichts bezeichnet, wird unverändert gespeichert. Das Anhängen ist nicht idempotent, daher wird ein `Idempotency-Key`-Header mit `400` abgelehnt; ist eine Antwort verloren gegangen, lesen Sie die Tension mit `?include=links`, bevor Sie erneut senden.

`DELETE /v1/tensions/{tension_id}/links/{link_id}` entfernt das aktuelle Ergebnis der Tension und antwortet mit `204`. Es lässt sich nicht rückgängig machen, und das Entfernen der Verknüpfung eines Vorschlags öffnet eine Tension wieder, die `PROCESSING` war. Die Verknüpfung einer anderen Tension, ein früheres Ergebnis oder eine unbekannte ID antworten mit `404 TENSION_LINK_NOT_FOUND` und entfernen nichts. Beide Operationen folgen der Regel zum Schließen einer Tension: Der Ersteller der Tension darf sie nutzen, ebenso die Personen, die die offene Sitzung ihres Kreises leiten, solange die Tension darauf steht; jede andere Tension antwortet mit `404`. Weil das Entfernen hinter `tensions:delete` steht, kann ein Schlüssel mit diesem Geltungsbereich die Verknüpfung einer Tension entfernen, die sein Konto nicht erstellt hat, wenn dieses Konto eine solche Sitzung leitet; `DELETE /v1/tensions/{tension_id}` selbst bleibt dem Ersteller vorbehalten.

**Tensions brauchen das Holacracy-Add-on.** Jede `/v1/tensions`-Route, lesend wie schreibend, antwortet mit `403` und `code: TENSIONS_NEED_HOLACRACY_ADDON`, wenn die Organisation das Holacracy-Add-on nicht hat; die Prüfung des Geltungsbereichs kommt zuerst, und bereits ausgestellte Schlüssel werden nicht umgeschrieben, sie werden bei der Nutzung abgelehnt. Das Hinzufügen eines Tagesordnungspunkts mit einer `source_tension_id` antwortet in diesem Zustand mit `422` und demselben Code.

**Längere Titel.** Ein `title` darf bei `POST /v1/tasks`, `POST /v1/tensions`, `PATCH /v1/tensions/{tension_id}` und `POST /v1/meetings/{meeting_id}/agenda-items` bis zu 500 Zeichen enthalten; ein längerer wird weiterhin mit `422` abgelehnt.

**Das Erstellen einer Tension kann gefahrlos wiederholt werden.** Senden Sie mit jeder neuen Tension einen `Idempotency-Key`-Header: 1 bis 255 sichtbare ASCII-Zeichen, ohne Leerzeichen (eine UUID ist die übliche Wahl). Eine Wiederholung derselben Anfrage mit demselben Schlüssel innerhalb von 24 Stunden erstellt nichts: Sie liefert die erste `201`-Antwort erneut, mit demselben Body und dem Header `Idempotent-Replayed: true`. Der Schlüssel gehört zu dem API-Schlüssel, der ihn gesendet hat: Ein anderer API-Schlüssel, auch derselben Organisation, erhält nie seine Antwort. Erstellungen im Namen eines Mitglieds sind ebenfalls abgedeckt, und `created_by_id` ist Teil der Anfrage, an die der Schlüssel gebunden ist. Ohne den Header ändert sich nichts: Zwei Aufrufe erstellen zwei Tensions.

- Derselbe Schlüssel mit einem anderen Body wird mit `422` abgelehnt, Eintrag `code: IDEMPOTENCY_KEY_REUSED`, `field: Idempotency-Key`. Verwenden Sie für eine neue Tension einen neuen Schlüssel.
- Eine Wiederholung, während die erste Anfrage noch läuft, antwortet mit `409 IDEMPOTENCY_REQUEST_IN_PROGRESS`. Warten Sie die Frist aus `Retry-After` ab und wiederholen Sie dann mit demselben Schlüssel: Sie erhalten die Antwort der ersten Anfrage.
- Ist die erste Anfrage fehlgeschlagen, nachdem die Tension möglicherweise erstellt wurde, antwortet eine Wiederholung mit `409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN`. Lesen Sie `GET /v1/tensions?sort=-created_at`, und wenn Ihre Tension dort nicht steht, senden Sie sie mit einem neuen Schlüssel erneut.
- Eine Anfrage, die abgelehnt wurde, bevor etwas geschrieben werden konnte, etwa eine `422`-Ablehnung oder ein `403`, gibt ihren Schlüssel frei.
- Ein Wert, den die API nicht berücksichtigen kann (leer, länger als 255 Zeichen, mit Leerzeichen oder mit Nicht-ASCII-Zeichen), wird mit `400 IDEMPOTENCY_KEY_INVALID` abgelehnt, und es wird nichts erstellt.

Drei Grenzen bleiben. Ist der Speicher, der die Schlüssel aufbewahrt, kurzzeitig nicht verfügbar, wird eine Anfrage mit Schlüssel ohne diesen Schutz erstellt, wie vor Vertragsversion 0.77.0. Wird der Dienst angehalten, während eine Erstellung noch läuft, kann eine einige Minuten später gesendete Wiederholung die Tension erneut erstellen. Hat Talkspirit ein langes Textfeld anders gespeichert, als Sie es gesendet haben, antwortet eine Wiederholung mit `409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN` statt mit der ersten `201`-Antwort. Die anderen erstellenden Schreiboperationen und `PATCH /v1/tensions/{tension_id}/status` lehnen den Header weiterhin mit `400 IDEMPOTENCY_KEY_NOT_SUPPORTED` ab.

## Die Geltungsbereiche

Ein Administrator wählt die Geltungsbereiche bei der Erstellung des Schlüssels. Vierundzwanzig sind definiert:

- Ohne Modulbindung: `users:read`, `users:write`, `audit_log:read`, `user_export:read`
- Modul Struktur: `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`
- Modul Ziele: `goals:read`, `goal_export:read`
- Modul Projekte: `projects:read`, `tasks:read`, `tasks:write`, `task_export:read`
- Modul Meetings: `meetings:read`, `meetings:write`

Sie erscheinen nicht alle gleichzeitig. Ein Geltungsbereich wird nur angeboten, wenn das Modul, aus dem er liest, in der Organisation aktiv ist: `tasks:read` fehlt also, wenn Projekte aus ist, und der ganze Struktur-Block fehlt, wenn Struktur aus ist. Fragen Sie den Administrator, welche Module die Organisation betreibt, bevor Sie gegen einen Geltungsbereich entwickeln.

`audit_log:read` liest das Aktivitätsprotokoll, `GET /v1/audit-logs`. Er genügt allein nicht: das Konto hinter dem Schlüssel muss außerdem Administrator der Organisation sein, sonst antwortet die Route mit `403 FORBIDDEN_UPSTREAM`.

`activity:read` liest den Aktivitätsverlauf, `GET /v1/activities`. Er ist ausgeschaltet, solange ein Administrator nicht **Aktivitätsverlauf lesen** in der Gruppe Struktur der Geltungsbereiche des Schlüssels ankreuzt, und die Voreinstellung „nur lesen“ enthält ihn nicht, weil er benennt, wer wen gesetzt oder entfernt hat. Für das Konto hinter dem Schlüssel ist keine Administratorrolle nötig. Ein vor diesem Geltungsbereich ausgestellter Schlüssel trägt ihn nicht, und die Geltungsbereiche eines bestehenden Schlüssels lassen sich nicht ändern, daher erstellt ein Administrator einen neuen Schlüssel.

`structure_export:read` liest den Strukturexport, `/v1/structure-exports`. Wie `audit_log:read` genügt er allein nicht: das Konto hinter dem Schlüssel muss außerdem Administrator der Organisation sein, sonst antwortet der Start mit `403 FORBIDDEN_UPSTREAM`.

`goal_export:read`, `task_export:read`, `user_export:read` und `checklist_metric_export:read` lesen die Exporte von Zielen, Aufgaben, Mitgliedern sowie von Checklisten und Kennzahlen. Wie `structure_export:read` genügt keiner allein: Das Konto hinter dem Schlüssel muss außerdem Administrator der Organisation sein, sonst antwortet der Start mit `403 FORBIDDEN_UPSTREAM`. Keiner ist standardmäßig angekreuzt.

`tensions:write_on_behalf` wird nur benötigt, um beim Erzeugen einer Tension `created_by_id` zu senden. `tensions:write` erteilt ihn nicht, und die Geltungsbereiche eines bestehenden Schlüssels lassen sich nicht ändern: Ein Administrator erstellt also einen neuen Schlüssel, um ihn hinzuzufügen.

`meetings:write` fügt einen Tagesordnungspunkt hinzu, `POST /v1/meetings/{meeting_id}/agenda-items`. Er schließt `meetings:read` nicht ein: Geben Sie einem schreibenden Schlüssel beide, denn das erneute Lesen der Tagesordnung ist der einzige Weg zu erfahren, ob ein Schreibvorgang mit verlorener Antwort durchgegangen ist.

## Ihre erste Anfrage

`GET /v1/whoami` braucht keinen Geltungsbereich und dient gleichzeitig als Prüfung der Zugangsdaten. Er gibt den Partnernamen zurück, unter dem Ihr Schlüssel ausgegeben wurde, die Organisation, zu der er gehört, die Geltungsbereiche, die er trägt, `user_id`, das Mitglied, als das Ihr Schlüssel handelt, und `created_by_user_id`, den Administrator, der den Schlüssel erstellt hat (`null` bei einem älteren Schlüssel oder einem, den ein Talkspirit-Operator erstellt hat). Wird ein Aufruf abgelehnt oder liefert er weniger als erwartet, ist `user_id` das Konto, das Sie sich ansehen sollten.

```
curl -H "Authorization: Bearer <Ihr API-Schlüssel>" \
     https://partner-api.talkspirit.com/v1/whoami
```

Ein `200` bedeutet, dass der Schlüssel selbst gültig ist, und sagt Ihnen, was er trägt. Es beweist nicht, dass die Organisation das Konto dahinter noch akzeptiert: `whoami` prüft allein den Schlüssel und ruft Talkspirit nie auf, antwortet also weiter mit `200`, während jeder Endpunkt, der einen Geltungsbereich verlangt, mit `403` antwortet. Alles andere steht in der Fehlertabelle unten.

## Konventionen, nach denen Sie entwickeln sollten

- **Versionierung.** Alles liegt unter `/v1`. Eine brechende Änderung erscheint unter einem neuen Präfix, statt dieses zu verändern.
- **Paginierung.** Listen-Endpunkte nehmen `?cursor=` und `?limit=` und antworten mit einem `data`-Array plus einem `pagination`-Objekt mit `next_cursor` und `has_more`. Der Standardwert für `limit` ist überall 50. Das Maximum ist 199, mit zwei Ausnahmen: 100 bei `GET /v1/users` und 50 bei `GET /v1/meetings`. Der Cursor ist opak: geben Sie ihn unverändert zurück. Es gibt keinen Parameter `page`, `skip` oder `offset`, in keiner Schreibweise.
- **Feld-Erweiterung.** Antworten tragen einen minimalen Satz an Feldern. Fordern Sie mehr mit `?include=` an, einer kommagetrennten Liste, die an jedem Endpunkt dokumentiert ist. Ein Feld, das Sie nicht angefordert haben, fehlt in der Antwort, statt `null` zu sein: eine fehlende Liste bedeutet also „nicht angefordert" und `[]` bedeutet „angefordert, und es gibt keine".
- **Nur Server zu Server.** Cross-Origin-Anfragen aus einem Browser werden nicht unterstützt.
- **Wiederholungen.** Jedes `GET` kann gefahrlos wiederholt werden. `POST /v1/tensions` kann gefahrlos wiederholt werden, wenn Sie einen `Idempotency-Key`-Header senden (siehe Die elf Schreiboperationen). Die anderen Erstellungen sind nicht idempotent: `POST /v1/tasks`, `POST /v1/meetings/{meeting_id}/agenda-items` und `POST /v1/structure-exports` erzeugen bei jedem Aufruf einen Datensatz, deduplizieren Sie also auf Ihrer Seite, statt blind zu wiederholen: Bei diesen wird ein `Idempotency-Key`-Header mit `400` abgelehnt, statt ignoriert zu werden.

### Ratenbegrenzung

Derzeit darf jeder API-Schlüssel **100 Anfragen in jedem gleitenden Zeitraum von 60 Sekunden** senden. Lese- und Schreibzugriffe zählen gleich, jeder Schlüssel hat sein eigenes Kontingent, und eine abgelehnte Anfrage verbraucht nichts davon. Das Fenster gleitet: Eine Anfrage gibt ihren Platz 60 Sekunden nach dem Senden wieder frei. Die 101. Anfrage innerhalb einer Minute wird also abgelehnt, danach werden die Plätze nach und nach wieder frei. Lesen Sie den Wert aus dem Header `X-RateLimit-Limit` Ihrer eigenen Antworten, statt ihn fest einzutragen. Er ist eine Einstellung von Talkspirit, nicht Teil des Vertrags, und er kann sich ändern.

- **Exporte haben ein eigenes Limit.** Eine Organisation kann zehn Strukturexporte pro gleitender Stunde starten, die vom Bildschirm **Organisation exportieren** aus gestarteten eingeschlossen. Dieses `429` trägt den Code `STRUCTURE_EXPORT_LIMIT_REACHED` und ein `Retry-After` von einer Stunde. Die Aufrufe, die einen Export starten und verfolgen, zählen ebenfalls zu den 100 Anfragen des Schlüssels. Die Exporte von Zielen, Aufgaben, Mitgliedern sowie von Checklisten und Kennzahlen haben jeweils eigene Limits, ebenfalls für die ganze Organisation gezählt und mit den Administrationsbildschirmen geteilt: Darüber trägt ein `429` den Code `EXPORT_LIMIT_REACHED` und ein `Retry-After` von einer Stunde. Die Exporte von Zielen, Aufgaben und Mitgliedern erlauben außerdem nur einen Lauf je Konto gleichzeitig: Ein zweiter Start antwortet mit `429 EXPORT_ALREADY_RUNNING` und einem `Retry-After` von einer Minute.
- **Bei einem `429` warten Sie.** Warten Sie die Sekundenzahl aus dem Header `Retry-After` ab und senden Sie die Anfrage dann erneut. Das ist auch bei einer Schreiboperation gefahrlos, denn die Anfrage wird abgelehnt, bevor irgendetwas ausgeführt wird. Wenn die Ablehnungen anhalten, werden Sie langsamer und fügen jedem neuen Versuch eine kleine zufällige Verzögerung hinzu. Größere Seiten, `?include=` statt eines zusätzlichen Aufrufs und das Zwischenspeichern selten ändernder Daten bringen mehr als schnellere Wiederholungen.
- **Um mehr zu bitten,** wenden Sie sich an Ihren Talkspirit-Ansprechpartner oder an den Talkspirit-Support. Nennen Sie, was Sie brauchen: Ihre Spitze in Anfragen pro Minute, Ihr Tagesvolumen und die Endpunkte, die Sie aufrufen. Das Kontingent wird für ganz Talkspirit festgelegt, nicht an Ihrem Schlüssel, ein Administrator Ihrer Organisation kann es daher nicht erhöhen. Ein höherer Wert würde für alle Integrationen gelten, deshalb wird jede Anfrage geprüft, und keine wird zugesagt.

## Was die Fehler bedeuten

| Status und Code | Was passiert ist |
| --- | --- |
| `401 AUTHENTICATION_REQUIRED` | Kein `Authorization`-Header an der Anfrage. |
| `401 AUTHENTICATION_INVALID` | Der Schlüssel ist unbekannt oder widerrufen, oder die Organisation hat keinen API-Zugang. Die Meldung unterscheidet beides. |
| `403 FORBIDDEN_SCOPE` | Der Schlüssel ist gültig, aber der von diesem Endpunkt verlangte Geltungsbereich wurde ihm nicht erteilt. |
| `403 FORBIDDEN_UPSTREAM` | Der Schlüssel hat den Geltungsbereich, aber das Konto dahinter darf diese Änderung an einem Mitglied nicht vornehmen oder ist für das Aktivitätsprotokoll oder einen Export kein Administrator. Ein Administrator muss es erteilen. |
| `403 TENSIONS_NEED_HOLACRACY_ADDON` | Die Organisation hat das Holacracy-Add-on nicht, daher wird jede Tension-Route abgelehnt (`422` mit demselben Code, wenn ein Tagesordnungspunkt eine `source_tension_id` nennt). Ein Administrator muss handeln. |
| `403 FORBIDDEN_SIGN_IN_DISABLED`, `FORBIDDEN_MODULE_DISABLED`, `FORBIDDEN_ACCOUNT_SUSPENDED`, `FORBIDDEN_ACCOUNT_UNKNOWN` oder `FORBIDDEN_ACCESS_DENIED` | Der Geltungsbereich ist da, aber die Organisation weist das Konto hinter dem Schlüssel ab: seine Anmeldemethode wurde abgeschaltet, das Modul, das dieser Endpunkt liest, ist aus, das Konto ist gesperrt, es existiert in der Organisation nicht mehr, oder es darf das Angefragte nicht sehen. Verzweigen Sie über den `code`. |
| `400 INVALID_CURSOR`, `INVALID_INCLUDE` oder `INVALID_PARENT_TASK_ID` | Das Paginierungstoken ist fehlerhaft oder über seiner Grenze, ein `include`-Token akzeptiert dieser Endpunkt nicht, oder `parent_task_id` ist keine Aufgaben-Id oder kommt mehrfach vor. |
| `400 INVALID_ACTIVITY_TYPE`, `INVALID_MEMBER`, `INVALID_ACTOR`, `INVALID_ROLE_ID`, `INVALID_CIRCLE_ID`, `INVALID_OCCURRED_AFTER`, `INVALID_OCCURRED_BEFORE`, `OCCURRED_AFTER_CURSOR_MISMATCH` oder `OCCURRED_BEFORE_CURSOR_MISMATCH` | Bei `GET /v1/activities`: `type` fehlt, ist unbekannt oder wiederholt; ein Filter ist wiederholt oder keine einzelne ID bzw. kein einzelner Zeitpunkt mit UTC-Offset; `occurred_before` liegt vor `occurred_after`; oder ein Fenster weicht von dem ab, an das der `cursor` gebunden ist. `actor` mit der ausschließlich aus Nullen bestehenden ID `00000000-0000-0000-0000-000000000000` wird mit `INVALID_ACTOR` abgelehnt. Senden Sie auf jeder Seite eines Durchlaufs dieselben Werte erneut. |
| `400 IDEMPOTENCY_KEY_NOT_SUPPORTED` | Ein `Idempotency-Key`-Header wurde an eine Schreiboperation geschickt, die nicht dedupliziert: `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` oder `PATCH /v1/tensions/{tension_id}/status`. Entfernen Sie den Header. |
| `400 IDEMPOTENCY_KEY_INVALID` | Der an `POST /v1/tensions` gesendete `Idempotency-Key` besteht nicht aus 1 bis 255 sichtbaren ASCII-Zeichen. Es wurde nichts erstellt. |
| `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` oder `IDEMPOTENCY_KEY_OUTCOME_UNKNOWN` | Ein `POST /v1/tensions` wurde mit einem bereits verwendeten Schlüssel wiederholt. `IDEMPOTENCY_REQUEST_IN_PROGRESS`: Die erste Anfrage läuft noch, wiederholen Sie also mit demselben Schlüssel nach `Retry-After`. `IDEMPOTENCY_KEY_OUTCOME_UNKNOWN`: Die erste Anfrage ist fehlgeschlagen, nachdem die Tension möglicherweise erstellt wurde, lesen Sie also `GET /v1/tensions?sort=-created_at` und senden Sie sie nur mit einem neuen Schlüssel erneut, wenn sie dort nicht steht. |
| `409 ACTIVITY_LOG_DISABLED` | Die Organisation hat ihr Aktivitätsprotokoll nie eingeschaltet. Ein Administrator ändert diese Einstellung; ein erneuter Versuch hilft nicht. |
| `429 RATE_LIMIT_EXCEEDED`, `UPSTREAM_RATE_LIMITED` oder `STRUCTURE_EXPORT_LIMIT_REACHED` | `RATE_LIMIT_EXCEEDED`: Ihr Schlüssel hat mehr als 100 Anfragen in 60 Sekunden gesendet (siehe Ratenbegrenzung oben). `UPSTREAM_RATE_LIMITED`: Talkspirits eigene Dienste hinter der API begrenzen vorübergehend die Anfragen, oft wegen vieler paralleler Aufrufe. Ihr Kontingent bleibt unberührt, und es gibt keinen Wert zu erhöhen: Warten Sie und versuchen Sie es erneut. `STRUCTURE_EXPORT_LIMIT_REACHED`: Die Organisation hat ihre zehn Strukturexporte für die Stunde gestartet. Warten Sie die Sekundenzahl aus dem Header `Retry-After` ab. |
| `404 STRUCTURE_EXPORT_NOT_FOUND`, `409 STRUCTURE_EXPORT_NOT_READY` oder `STRUCTURE_EXPORT_FAILED`, `410 STRUCTURE_EXPORT_FILE_EXPIRED` | `404`: Den Export gibt es für diesen Schlüssel nicht, oder er ist vor mehr als 24 Stunden zu Ende gegangen. `409`: Der Export läuft noch, fragen Sie erneut ab, oder er ist fehlgeschlagen, starten Sie einen neuen. `410`: Die Adresse der Datei ist abgelaufen, starten Sie einen neuen Export. |
| `404 EXPORT_NOT_FOUND`, `409 EXPORT_NOT_READY` oder `EXPORT_FAILED`, `410 EXPORT_FILE_EXPIRED` | Wie beim Strukturexport oben, für die Exporte von Zielen, Aufgaben, Mitgliedern sowie von Checklisten und Kennzahlen. Ein Lauf anderer Art antwortet ebenfalls mit `404`. |
| `429 EXPORT_LIMIT_REACHED` oder `EXPORT_ALREADY_RUNNING` | `EXPORT_LIMIT_REACHED`: Die Organisation hat ihre Exporte dieser Art für die Stunde gestartet. `EXPORT_ALREADY_RUNNING`: Ihr Konto hat bereits einen Ziel-, Aufgaben- oder Mitgliederexport laufen. Warten Sie die Anzahl Sekunden aus dem `Retry-After`-Header ab. |
| `404 TENSION_LINK_NOT_FOUND` | Die Verknüpfung ist nicht das aktuelle Ergebnis dieser Tension, oder das Konto des Schlüssels darf sie nicht entfernen. Es wurde nichts entfernt. |
| `502 UPSTREAM_ERROR` oder `UPSTREAM_AUTH_ERROR` | Ein Dienst, von dem dieser Endpunkt abhängt, ist ausgefallen oder hat unerwartet geantwortet. Nichts hat sich geändert, wiederholen Sie mit wachsendem Abstand. |
| `504` | Die Anfrage hat das Zeitlimit des Servers überschritten und wurde abgebrochen. Ob eine Schreiboperation gewirkt hat, ist offen: wiederholen Sie sie nur, wenn das gefahrlos ist. |

Eine Ablehnung durch die Organisation, die fünf `403`-Codes in der Tabelle, ist endgültig: weder ein erneuter Versuch noch ein neuer Schlüssel hebt sie auf, ein Administrator der Organisation muss handeln. `FORBIDDEN_ACCESS_DENIED` antwortet auch, wenn die Organisation gerade gelöscht wird oder nicht mehr existiert: Dann kann kein Administrator helfen, wenden Sie sich an den Talkspirit-Support. Bis zur Vertragsversion 0.49.0 kamen diese Ablehnungen und die Ratenbegrenzung von Talkspirit beide als `502` an, was sich wie eine vorübergehende Störung liest. Eine Integration, die auf dieses alte Verhalten geschrieben wurde, wiederholt eine Ablehnung endlos und ignoriert `Retry-After` bei einer Begrenzung: prüfen Sie Ihre anhand der Tabelle oben.

Fehlerkörper sagen nie, ob ein Schlüssel existiert oder ob der Geltungsbereich gescheitert ist, versuchen Sie also nicht, daraus einen Zustand abzuleiten.

## Wie geht es weiter?

- [API-Token als Administrator verwalten](/de/integrations/manage-api-tokens-as-an-admin)
- [Wie füge ich eine Integration hinzu oder entferne sie?](/de/integrations/enable-a-cloud-file-picker)
