---
title: "The Talkspirit Partner API"
description: "The Partner API is a versioned REST contract for named integration partners. It is authenticated with an API key that an administrator of your organisation creates, and it is not open to self-serve signup."
category: integrations
section: api-and-webhooks
type: Reference
lastUpdated: 2026-11-16
locale: en
canonical: https://support.talkspirit.com/en/integrations/partner-api
---

# The Talkspirit Partner API


Talkspirit exposes a REST API under a `/v1` prefix so that an integration can read an organisation's members, structure, meetings, projects, goals and working agreements, and write in a few precise places, without anyone working in the Talkspirit interface. Every response is JSON, and most failures are an RFC 7807 problem document with a stable machine-readable `code`. Rate limiting and timeouts are the two exceptions: their bodies have their own shape.

It is a **partner** API, not a public one. The resource set is deliberately narrow, access is provisioned per named integration, and there is no developer portal where you can sign up or mint a credential yourself. If you want to connect a cloud storage service or another built-in integration, no API work is involved: see [How do I add or remove an integration?](/en/integrations/enable-a-cloud-file-picker).

## What has to be in place before a call succeeds

Two conditions, both of them owned by the Talkspirit organisation you integrate with:

1. **The API module is enabled on that organisation.** It is an optional module and it is off by default. Without it, every request is rejected with `401` even when the key itself is valid. If the module is switched off later, keys that were already issued stop working, after a short propagation delay.
2. **You have an API key for that organisation.** An administrator of the organisation creates it in Administration, under Security, on the **API** page. Talkspirit support does not hand keys out, and you cannot create one from the partner side.

Ask the administrator who owns the organisation to arrange both. The procedure is in [Managing API tokens as an admin](/en/integrations/manage-api-tokens-as-an-admin).

## Where is the reference documentation?

The API documents itself. The service publishes, under the same host that serves the API:

- `/v1/docs`, an interactive reference rendered with Scalar. It reads `/v1/openapi.json`, lists every operation with its schemas, and can send test requests from the page.
- `/v1/openapi.json`, the machine-readable OpenAPI document, for generating a client.

Both are readable without a credential. `/v1/redoc` used to be a separate reading page and now answers `301` to `/v1/docs`, so there is one reference page rather than two.

The contract is generated from the running service and checked in continuous integration, so it cannot drift away from what the API actually serves. Treat it as the authority: this article explains the shape, the reference explains every field. It carries its own version number, distinct from the `/v1` path: this article was checked against **0.85.1**.

## How authentication works

Pass your key as a bearer token on every request:

```http
Authorization: Bearer <your API key>
```

The key is an opaque string beginning with `ts_partner_`. Talkspirit stores only a fingerprint of it, so the full value is shown once, at creation, and cannot be recovered afterwards. A lost key is replaced, never retrieved. Do not confuse it with an MCP key, which begins with `tsk_`, is created by each member in their own account area, and authenticates the separate MCP endpoint rather than this API.

Behind the scenes the service verifies your key, then exchanges it for a short-lived token belonging to a technical user dedicated to your integration. Your integration therefore sees exactly what that technical user is allowed to see: the circles, roles and boards it has been given in the organisation, and, for a task that belongs to no project, only the tasks that user may see in the product. A scope on the key never widens that.

Treat the key like a password. Keep it out of source control, and ask the administrator to revoke and reissue it if it is ever exposed. Revocation takes effect immediately, with a grace window of up to about five minutes for a token already exchanged.

## What the API exposes

Sixty-eight operations under `/v1`, plus `GET /healthz`. Seventeen of them write; everything else reads.

| Resource | Read endpoints | Scope |
| --- | --- | --- |
| Users | `GET /v1/users`, `GET /v1/users/{user_id}`, `GET /v1/users/{user_id}/memberships` | `users:read` |
| Every membership of the organisation | `GET /v1/memberships` | `users:read` |
| Circles | `GET /v1/circles`, `GET /v1/circles/{circle_id}`, `GET /v1/circles/{circle_id}/members` | `circles:read` |
| Roles | `GET /v1/roles`, `GET /v1/roles/{role_id}`, `GET /v1/roles/{role_id}/members` | `roles:read` |
| Role templates | `GET /v1/role-templates`, `GET /v1/role-templates/{role_template_id}` | `roles:read` |
| Custom-field definitions | `GET /v1/custom-fields` | `roles:read`, `circles:read` or `users:read`, depending on the `entity_type` you ask for |
| Meetings | `GET /v1/meetings`, `GET /v1/meetings/{meeting_id}`, `GET /v1/meetings/{meeting_id}/agenda-items` | `meetings:read` |
| Projects | `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` |
| Labels | `GET /v1/labels`, `GET /v1/labels/{label_id}` | `projects:read` |
| Tasks | `GET /v1/tasks`, `GET /v1/tasks/{task_id}`, `GET /v1/tasks/{task_id}/comments` | `tasks:read` |
| Goals | `GET /v1/goals`, `GET /v1/goals/{goal_id}`, `GET /v1/goals/{goal_id}/key-results`, `GET /v1/goals/{goal_id}/comments` | `goals:read` |
| Time periods | `GET /v1/time-periods`, `GET /v1/time-periods/{time_period_id}` | `goals:read` |
| Working agreements | `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` |
| Structure exports | `GET /v1/structure-exports/{export_id}`, `GET /v1/structure-exports/{export_id}/file`, after a `POST /v1/structure-exports` that starts the export | `structure_export:read` |
| Goal exports | `GET /v1/goal-exports/{export_id}`, `GET /v1/goal-exports/{export_id}/file`, after a `POST /v1/goal-exports` that starts the export | `goal_export:read` |
| Task exports | `GET /v1/task-exports/{export_id}`, `GET /v1/task-exports/{export_id}/file`, after a `POST /v1/task-exports` that starts the export | `task_export:read` |
| Member exports | `GET /v1/user-exports/{export_id}`, `GET /v1/user-exports/{export_id}/file`, after a `POST /v1/user-exports` that starts the export | `user_export:read` |
| Checklist and metric exports | `GET /v1/checklist-metric-exports/{export_id}`, `GET /v1/checklist-metric-exports/{export_id}/file`, after a `POST /v1/checklist-metric-exports` that starts the export | `checklist_metric_export:read` |
| Activity history | `GET /v1/activities` | `activity:read` |
| Activity log | `GET /v1/audit-logs` | `audit_log:read` |
| Your own identity | `GET /v1/whoami` | none |

Two groupings are worth noting because they do not follow the path name: sections and labels are read with `projects:read`, and time periods with `goals:read`.

The text of a working agreement is a sub-resource of its own, `GET /v1/documents/{document_id}/content`, so listing documents never carries a page of full texts. It serves the version the key's account sees in the product: the published one, or the latest draft when nothing has been published yet. A working agreement that exists but holds no text answers `200` with an empty text rather than `404`.

`GET /v1/memberships` returns every membership held in the organisation, one page per call, so a full sync of the structure costs as many calls as there are pages rather than one call per member. Each row is exactly a row of `GET /v1/users/{user_id}/memberships`, with the member's `user_id`. Pass `?updated_since=` to receive only the memberships added or edited since a given instant; such a walk cannot see a membership that was removed, so reconcile with a full walk from time to time.

`GET /v1/audit-logs` is the organisation's activity log, newest first: connections (successful and refused), publications, comments, and accesses to and exits from groups. Because it covers every member, the account behind the key must be an administrator of the organisation as well as the key carrying `audit_log:read`. Pass `?occurred_after=` to read only what happened since a given instant.

`/v1/structure-exports` produces the file of the **Export the organisation** screen: the circles, roles and who holds what, with each holder's email address, and the policies in force, as an XLSX workbook (the default) or a ZIP of CSV files. `POST /v1/structure-exports` starts the export in the background and answers `202`, with its address in the `Location` header. Poll `GET /v1/structure-exports/{export_id}` until `status` is `completed` or `failed`, then call `GET /v1/structure-exports/{export_id}/file`. It answers `302` to the file, which you must fetch before `file_expires_at`; afterwards it answers `410`. A key can read an export for 24 hours after it ended, and only if it acts as the account that started it. Because the file holds every member's email address, the account behind the key must be an administrator of the organisation, as for the activity log. The organisation can start ten exports per rolling hour, those started from that screen included (see Rate limits).

`GET /v1/activities` is the history of who put whom where in the structure. `type=assignment` is required and is the only value today: it lists each time a member was seated on or removed from a role, or added to or removed from a circle, newest first. A row carries `member_id` (the member the change is about), `actor_id` (the member who made it), `action` (`assigned` or `unassigned`), `occurred_at`, and either `role_id` and `role_name` or `circle_id` and `circle_name`. Both member ids are the `id` that `GET /v1/users` returns. `cause` says why when the actor did not make the change directly (`election`, `left_circle`, `left_source_role`, `member_suspended`, `invited_role_copy` or `other`; treat any other value as a future one), and `reason` is the actor's own text. Filter with `member`, `actor`, `role_id`, `circle_id` (which also returns the changes on that circle's roles and the membership changes of its direct sub-circles) and an inclusive `occurred_after` / `occurred_before` window; the filters combine. Walk the pages with the `cursor`, and resend the same `type` and window on every page. Do not confuse it with the activity log described above, which records connections, publications and comments.

The key reads what its account sees in the app's activity view, so a guest's key reads only the changes about that guest, and no administrator role is needed. Four limits matter before you rely on it:

- **The history is recent.** It starts on 5 November 2026, except elections, which are recorded back to 21 September 2026. Earlier changes, and assignments migrated from Holaspirit, have no row: for those, `assigned_at` on `GET /v1/roles/{role_id}?include=members` gives the date but not the author. An empty page therefore means "nothing recorded in this window", never "nothing happened".
- **`actor_id` can be `null`.** No person made the change: the platform did it on its own, for example when a suspended member is detached from their roles, or when an election is adopted automatically after its proposal expired. Such rows never match an `actor` filter: to read them, walk the collection without `actor` and keep the rows whose `actor_id` is `null` (sending the all-zero id is refused, see the error table).
- **A role row does not carry its circle.** Read it from `GET /v1/roles/{role_id}`.
- **Some exits are not recorded:** those caused by deleting a role or a circle, by erasing a member's data, and the circle membership that a role seat brings with it.

The rows of `GET /v1/goals/{goal_id}/key-results` carry two arrays, `task_ids` and `project_ids`: the tasks and the projects linked to that key result that the key's account can see, each id once, and `[]` when there is none. A linked item the account cannot see, and an archived one, is not listed, and the order of the ids means nothing. Reading them needs only `goals:read`; read an item itself with `GET /v1/tasks/{task_id}` (`tasks:read`) or `GET /v1/projects/{project_id}` (`projects:read`).

Four more exports work like the structure export: `/v1/goal-exports` (goals and key results, XLSX), `/v1/task-exports` (tasks and projects, XLSX), `/v1/user-exports` (members with their email addresses, CSV) and `/v1/checklist-metric-exports` (checklists and metrics, XLSX). Each produces the file of the matching administration screen. You start it with a `POST` that answers `202` and a `Location` header, poll `GET .../{export_id}` until `status` is `completed` or `failed`, then download `GET .../{export_id}/file` (a `302`) before `file_expires_at`. A run stays readable for 24 hours. The account behind the key must be an administrator of the organisation, and the Goals module must be on for the goal export and the Projects module for the task export; otherwise the start answers `403 FORBIDDEN_UPSTREAM`. The goal and task files hold private items only while the organisation's admin oversight is on, and the run says so in `includes_private_content`. In the checklists and metrics file, the Recurrence column holds one of eight preset words (`DAILY` to `YEARLY`) or, for an item on a custom schedule, `CUSTOM: ` followed by the rule in English words and its start date. Treat that text as a label, not a format to parse.

On a task's assignees (`?include=assignees` on `GET /v1/tasks` and `GET /v1/tasks/{task_id}`), four nullable fields, `via_role_id`, `via_role_name`, `via_role_circle_id` and `via_role_circle_name`, give the role the member was assigned to the task in, as recorded at that moment, and the circle that role is defined in. It can be a role the member no longer holds or one since removed: when a removed role's names can no longer be read, `via_role_id` stays set and the other three are `null`. All four are `null` on circle, role and group rows and for a member assigned without a role.

`GET /v1/meetings/{meeting_id}/agenda-items` returns a meeting's whole agenda, every item on it whoever added it, in the order the meeting runs it. An item placed on the agenda from a tension carries that tension's id in `source_tension_id`; an item typed directly into the meeting has none, and it is not a tension, so the tension endpoints never return it. `POST` on the same path adds an item at the end of the agenda; see the writes below.

A task carries its place in a sub-task tree and its text. Every task has `parent_task_id` (`null` for a top-level task) and `subtask_count`, the number of its sub-tasks that are not archived, private ones the key's account may not see left out; the `?parent_task_id=` list applies the full read rule, so it may hold fewer. `GET /v1/tasks` lists top-level tasks. Pass `?parent_task_id=` with a task's id to list that task's sub-tasks instead; an id that names no task the account can read lists nothing, and a value that is not a task id is refused with `400 INVALID_PARENT_TASK_ID`. A sub-task is read by its own id like any task. `GET /v1/tasks/{task_id}` and the answer of `POST /v1/tasks` always carry `description` and `description_format` (`blocknote_json` or `text`); on the list, ask for them with `?include=description`. `?include=attachments` lists the files uploaded to a task (`id`, `name`, `size`, `content_type`, `added_at`). It gives no download link, and links attached to a task are not listed.

Several lists also accept filters, for example the roles one member holds, the circles one member belongs to, the roles linked to one role template, the tasks or meetings one member is involved in, the sub-tasks of one task, or the tensions put on one meeting's agenda. The reference documentation lists every filter an endpoint accepts.

### Fields that need a word of explanation

Several fields carry more meaning than their name suggests.

- **`last_activity_at`, on a member.** `GET /v1/users`, `GET /v1/users/{user_id}` and the response of `PATCH /v1/users/{user_id}` publish the member's last recorded activity. It is an activity signal, not a sign-in: it is recorded when an authenticated member uses the product, and refreshed about once an hour rather than on every request, so read it as "active recently" and never as an authentication event. It is `null` when no activity was ever recorded, and for a member who has been anonymised. Calls you make with your own key record activity for the technical user behind the key, never for the members it reads or updates.
- **`avatar_url`, on a member.** `GET /v1/users`, `GET /v1/users/{user_id}` and the response of `PATCH /v1/users/{user_id}` publish the address of the member's current profile picture when Talkspirit hosts it. It is `null` when the member has no picture, and when the picture is a link to another website. Talkspirit adds no token and no signature to that address: anyone who holds it can download the image, and it changes when the member changes their picture, so do not keep it as a permanent link.
- **`assigned_at` and `updated_at`, on an assignment.** Every row of `GET /v1/roles/{role_id}/members`, `GET /v1/circles/{circle_id}/members`, `GET /v1/users/{user_id}/memberships` and `GET /v1/memberships`, and every member row returned by `GET /v1/roles` and `GET /v1/roles/{role_id}` with `?include=members`, carries both. The one exception is a representative row on `GET /v1/circles/{circle_id}/members`, described below: it stands for no assignment in that circle, so both are `null` there. `assigned_at` is when the assignment began: for an organisation migrated from Holaspirit, the date the assignment had there, not the date of the migration. Rows whose source carried no such date fall back to the instant of their import run, which is how you recognise them — they all share one value. `updated_at` is when the row was last written: its label, its decision-maker and administrator flags, a leave or a return. It does not move when an allocation changes, so it is not a feed of assignment changes, and neither field is an assignment history.
- **`expires_at` and `mandate_kind`, on an assignment.** They sit on the same rows as `assigned_at` and are always present, `null` or not. `expires_at` is the end date set on the assignment, a calendar day written `YYYY-MM-DD`, or `null` when it has none, which is the ordinary state. `mandate_kind` says why the assignment has an end date, when that was recorded: `ELECTED` for a holder elected to the role, `INTERIM` for a holder appointed without an election on a role that normally requires one, and `null` for an ordinary assignment. Treat any other value as a future one.
- **Representatives, on a circle's member list.** `GET /v1/circles/{circle_id}/members` lists the circle's own members first, then its representatives: everyone who holds, in a circle directly nested inside it, a role with the **Represents sub-circle** setting. They take part in the circle's decisions without being attached to it. They come after the members, ordered by `user_id`, in the same pages and under the same cursor, and a person who is both a member and a representative is listed once, as a member. A representative row names no role: `role_id`, `role_name`, `scope`, `assigned_at`, `updated_at`, `expires_at` and `mandate_kind` are `null`, `is_decision_maker` is `true` and `is_circle_admin` is `false`. A script that walks a circle's members therefore receives these rows too, and should not read a `null` `assigned_at` as an error.
- **`content_restricted_to_members` and `meeting_reports_restricted_to_members`, on a circle.** They are the circle's two privacy settings, read-only. The first is `true` when the circle keeps its content, meaning the documents of the circle and of its roles and its links, for its members only. The second is `true` when its meeting reports are visible to its members only. Both are `true` unless someone opened them up. They describe the circle and change nothing about what your key reads, which is always what its account may see. `null` means the setting could not be read, not that the circle is open.
- **`assignees`, on a project.** `GET /v1/projects` and `GET /v1/projects/{project_id}` accept `?include=assignees`. It lists the circles and roles the project is assigned to, each with `assignee_type` (`CIRCLE` or `ROLE`), `assignee_id`, `assignee_name`, `project_role` (`OWNER`, `EDITOR`, `CONTRIBUTOR` or `VIEWER`, the access that assignment gives on the project) and `assigned_at`. Individual members and groups assigned to the project are not listed, so this is not the list of everyone who can open the project.
- **`options`, on a member custom-field definition.** `GET /v1/custom-fields?entity_type=user` publishes the complete option catalogue of every single-select and multiple-select field, where it used to publish nothing: every configured option, including the ones no member holds yet, as a `{value, label}` pair. `value` is the option id that `PATCH /v1/users/{user_id}/custom-fields` accepts; `label` is what a member's value usually reads as, so match a member's value on `label` first and on `value` if that fails, and expect two options of the same field to be able to share a label. Options come ordered by label, up to 5,000 per field, and `options_truncated` on the same definition says whether that ceiling bit. A select field with no option configured yet reports an empty list; `null` still means the field's type has no option list at all. The values on `GET /v1/users?include=custom_fields` are unchanged.

- **`source_template_id`, on a role.** The role template the role is linked to, the id `GET /v1/role-templates` returns, or `null` when it is linked to none. A role starts linked to the template it was created from, but the link can change during the role's life, in the app through a proposal or the Architect mode: the value can go from `null` to an id, from one id to another, or back to `null`, and a link or unlink advances `updated_at`. Permanently deleting a role template clears the value on every role linked to it, without advancing their `updated_at`. `GET /v1/roles?source_template_id=` lists the roles linked to the template at the time of the call. A role template is a reusable role definition, such as "Secretary". An invited copy of a role reads `null`: its `source_role_id` leads to the role that carries the template. If your organisation was migrated from Holaspirit, template ids changed with the migration, so read them again from `GET /v1/role-templates`.
- **The personal fields of a member.** `email`, `phone`, `last_activity_at` and the custom-field values reach your key as they reach the technical user in the product. An administrator reads them all. A member reads them all except an email its owner chose to hide. A guest who shares no active group with that member reads none of them. A withheld field is `null`. The technical user behind a key is usually not an administrator, so expect `email` to be `null` for the members who hid it.
- **`priority`, on a tension.** It can be `NONE`, which means nobody has set one, and that is what a tension created without a priority now records. Treat a value you do not recognise as a future value rather than an error.

**Retyping a select field moves its values between two slots.** A field an administrator changes from single-select to multiple-select stops reading as `value`, a single value, and starts reading as `values`, a list — and a write has to use the same slot. Submitting the wrong one is refused with a `422 INVALID_CUSTOM_FIELD_VALUE` whose message names the slot to use; it is never quietly coerced.

### The seventeen writes

| Operation | Scope | What to know |
| --- | --- | --- |
| `POST /v1/tasks` | `tasks:write` | Creates a task on every call, so it is not safe to retry blindly. The optional `section_id` names the column of the project the task goes into; without it, Talkspirit picks the project's first section that is not for completed or blocked work. An `Idempotency-Key` header is refused with `400`. |
| `POST /v1/tensions` | `tensions:write` | Creates a tension. An omitted `priority` records `NONE`. With `created_by_id`, the tension is raised on behalf of a member, who becomes its creator: it is listed among that member's tensions and they may edit it. Your key's account is then no longer its creator, so `PATCH` and `DELETE` on it answer `404`. Sending `created_by_id` needs the `tensions:write_on_behalf` scope as well (`403 FORBIDDEN_SCOPE` without it). An id that names no active member who is not a guest is refused with `422 UNKNOWN_MEMBER`. Send an `Idempotency-Key` header to make a retry safe, as described below the table. |
| `PATCH /v1/tensions/{tension_id}` | `tensions:write` | Edits a tension. |
| `PATCH /v1/tensions/{tension_id}/status` | `tensions:write` | Moves a tension through its statuses. Closing or resolving a tension that a proposal still in progress carries is refused with `422 TENSION_CARRIED_BY_LIVE_PROPOSAL`: adopt, reject or withdraw the proposal in Talkspirit, then send the change again. |
| `DELETE /v1/tensions/{tension_id}` | `tensions:delete` | **A hard delete with no undo.** See below. |
| `POST /v1/tensions/{tension_id}/links` | `tensions:write` | Records what a tension became, by attaching an item to it. Not idempotent. See below. |
| `DELETE /v1/tensions/{tension_id}/links/{link_id}` | `tensions:delete` | Removes the tension's current outcome. **No undo.** See below. |
| `POST /v1/meetings/{meeting_id}/agenda-items` | `meetings:write` | Adds an item at the end of a meeting's agenda, optionally from an existing tension (`source_tension_id`). It creates an item on every call, so it is not safe to retry blindly: read the agenda before resending, which needs `meetings:read` as well. A tension can be on the agenda of only one meeting that has not ended. |
| `POST /v1/structure-exports` | `structure_export:read` | Starts a structure export, described above. It starts a new export on every call, so it is not safe to retry blindly, and an `Idempotency-Key` header is refused with `400`. It sits behind a `read` scope although it is a `POST`, because what the key is trusted with is reading the whole register. |
| `POST /v1/goal-exports` | `goal_export:read` | Starts a goal export, described above. Same rules as `POST /v1/structure-exports`: a new export on every call, and an `Idempotency-Key` header is refused with `400`. Your key's account can run one at a time (`429 EXPORT_ALREADY_RUNNING` otherwise). |
| `POST /v1/task-exports` | `task_export:read` | Starts a task export, described above. Same rules as `POST /v1/goal-exports`. |
| `POST /v1/user-exports` | `user_export:read` | Starts a member export, described above. Same rules as `POST /v1/goal-exports`. The file holds every member's email address. |
| `POST /v1/checklist-metric-exports` | `checklist_metric_export:read` | Starts a checklist and metric export, described above. A new export on every call, and an `Idempotency-Key` header is refused with `400`. |
| `PATCH /v1/users/{user_id}` | `users:write` | Edits a member. |
| `PATCH /v1/users/{user_id}/custom-fields` | `users:write` | Sets custom-field values on a member. |
| `PATCH /v1/circles/{circle_id}/custom-fields` | `circles:write` | Sets custom-field values on a circle. |
| `PATCH /v1/roles/{role_id}/custom-fields` | `roles:write` | Sets custom-field values on a role. |

**Deleting a tension is irreversible.** The tension and its links are gone, and no read returns them afterwards. It sits behind its own `tensions:delete` scope, which `tensions:write` deliberately does not grant, so the capability has to be given explicitly rather than inherited. A tension is also deletable by its creator only: a key can delete the tensions its own technical user created, and nothing else.

**Recording what a tension became.** `POST /v1/tensions/{tension_id}/links` attaches a proposal, task, project, agenda item or goal to a tension as its current outcome: send `linked_item_type`, `linked_item_id`, `linked_service` and an optional `note`, and receive `201` with the link as `GET /v1/tensions/{tension_id}?include=links` lists it. Linking another item replaces the current outcome, and linking a proposal moves the tension to `PROCESSING`. Only an `OPEN` or `PARKED` tension can be transformed (`422 BUSINESS_RULE_VIOLATION` otherwise), and an item can be linked to one tension only (`422 CONFLICT`). The item itself is not looked up: an id that names nothing is stored as given. Linking is not idempotent, so an `Idempotency-Key` header is refused with `400`; if a response is lost, read the tension with `?include=links` before sending again.

`DELETE /v1/tensions/{tension_id}/links/{link_id}` removes the tension's current outcome and answers `204`. It cannot be undone, and removing a proposal's link reopens a tension that was `PROCESSING`. A link of another tension, an earlier outcome or an unknown id answers `404 TENSION_LINK_NOT_FOUND` and removes nothing. Both operations follow the rule for closing a tension: the tension's creator may use them, and so may the people who run the open meeting of its circle while the tension is on it; any other tension answers `404`. Because the removal sits behind `tensions:delete`, a key holding it can remove the link of a tension its account did not create when that account runs such a meeting; `DELETE /v1/tensions/{tension_id}` itself stays creator-only.

**Tensions need the Holacracy add-on.** Every `/v1/tensions` route, reads and writes alike, answers `403` with `code: TENSIONS_NEED_HOLACRACY_ADDON` when the organisation does not have the Holacracy add-on; the scope check comes first, and keys already issued are not rewritten, they are refused when used. Adding an agenda item with a `source_tension_id` answers `422` with the same code in that state.

**Longer titles.** A `title` may hold up to 500 characters on `POST /v1/tasks`, `POST /v1/tensions`, `PATCH /v1/tensions/{tension_id}` and `POST /v1/meetings/{meeting_id}/agenda-items`; a longer one is still refused with `422`.

**Creating a tension can be retried safely.** Send an `Idempotency-Key` header with each new tension: 1 to 255 visible ASCII characters, with no spaces (a UUID is the usual choice). A repeat of the same request with the same key within 24 hours creates nothing: it answers the first `201` again, with the same body and the header `Idempotent-Replayed: true`. The key belongs to the API key that sent it, so another API key, even of the same organisation, never receives its answer. Creates on behalf of a member are covered too, and `created_by_id` is part of the request the key is bound to. Without the header nothing changes: two calls create two tensions.

- The same key with a different body is refused with `422`, entry `code: IDEMPOTENCY_KEY_REUSED`, `field: Idempotency-Key`. Use a new key for a new tension.
- A repeat while the first request is still running answers `409 IDEMPOTENCY_REQUEST_IN_PROGRESS`. Wait for the delay in `Retry-After`, then retry with the same key: you receive the first request's answer.
- If the first request failed after the tension may have been created, a repeat answers `409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN`. Read `GET /v1/tensions?sort=-created_at`, and if your tension is not there, send it again with a new key.
- A request refused before anything could be written, such as a `422` rejection or a `403`, frees its key.
- A value the API cannot honour (empty, longer than 255 characters, with spaces or with non-ASCII characters) is refused with `400 IDEMPOTENCY_KEY_INVALID`, and nothing is created.

Three limits remain. If the store that keeps the keys is briefly unavailable, a request carrying a key is created without this protection, as it was before contract 0.77.0. If the service is stopped while a create is still running, a retry made a few minutes later can create the tension again. If Talkspirit stored a long text field differently from how you sent it, a repeat answers `409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN` instead of the first `201`. The other writes that create, and `PATCH /v1/tensions/{tension_id}/status`, still refuse the header with `400 IDEMPOTENCY_KEY_NOT_SUPPORTED`.

## Scopes

An administrator picks scopes when the key is created. Twenty-four are defined:

- Ungated: `users:read`, `users:write`, `audit_log:read`, `user_export:read`
- Structure module: `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`
- Goals module: `goals:read`, `goal_export:read`
- Projects module: `projects:read`, `tasks:read`, `tasks:write`, `task_export:read`
- Meetings module: `meetings:read`, `meetings:write`

They do not all appear at once. A scope is only offered when the module it reads from is active on the organisation, so `tasks:read` is absent where Projects is off, and the whole Structure block is absent where Structure is off. Ask the administrator which modules the organisation runs before you design against a scope.

`audit_log:read` reads the activity log, `GET /v1/audit-logs`. It is not enough on its own: the account behind the key must also be an administrator of the organisation, otherwise the route answers `403 FORBIDDEN_UPSTREAM`.

`activity:read` reads the activity history, `GET /v1/activities`. It is off unless an administrator ticks **Read the activity history** in the Structure group of the key's scopes, and the read-only preset does not include it, because it names who seated or removed whom. No administrator role is needed on the account behind the key. A key issued before this scope existed does not carry it, and the scopes of an existing key cannot be edited, so an administrator mints a new key.

`structure_export:read` reads the structure export, `/v1/structure-exports`. Like `audit_log:read`, it is not enough on its own: the account behind the key must also be an administrator of the organisation, otherwise the start answers `403 FORBIDDEN_UPSTREAM`.

`goal_export:read`, `task_export:read`, `user_export:read` and `checklist_metric_export:read` read the goal, task, member and checklist and metric exports. Like `structure_export:read`, none is enough on its own: the account behind the key must also be an administrator of the organisation, otherwise the start answers `403 FORBIDDEN_UPSTREAM`. None is ticked by default.

`tensions:write_on_behalf` is needed only to send `created_by_id` when creating a tension. `tensions:write` does not grant it, and the scopes of an existing key cannot be edited, so an administrator mints a new key to add it.

`meetings:write` adds an agenda item, `POST /v1/meetings/{meeting_id}/agenda-items`. It does not include `meetings:read`: give a key both when it writes, because reading the agenda back is the only way to find out whether a write whose response was lost went through.

## Making your first request

`GET /v1/whoami` needs no scope and doubles as a credential check. It returns the partner name your key was issued under, the organisation it belongs to, the scopes it carries, `user_id`, the member your key acts as, and `created_by_user_id`, the administrator who created the key (`null` for an older key or one a Talkspirit operator created). When a call is refused or returns less than you expected, `user_id` is the account to look at.

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

A `200` means the key itself is valid and tells you what it carries. It does not prove the organisation still accepts the account behind it: `whoami` checks the key alone and never calls Talkspirit, so it keeps answering `200` while every endpoint that needs a scope answers `403`. Anything else is in the error table below.

## Conventions to build against

- **Versioning.** Everything sits under `/v1`. A breaking change ships under a new prefix instead of changing this one.
- **Pagination.** List endpoints take `?cursor=` and `?limit=` and answer with a `data` array plus a `pagination` object carrying `next_cursor` and `has_more`. The default `limit` is 50 everywhere. The maximum is 199, with two exceptions: 100 on `GET /v1/users` and 50 on `GET /v1/meetings`. The cursor is opaque: pass it back untouched. There is no `page`, `skip` or `offset` parameter in any spelling.
- **Field expansion.** Responses carry a minimal set of fields. Ask for more with `?include=`, a comma-separated list documented on each endpoint. A field you did not request is absent from the response rather than `null`, so an absent list means "not requested" and `[]` means "requested, and there are none".
- **Server to server only.** Cross-origin requests from a browser are not supported.
- **Retries.** Every `GET` is safe to retry. `POST /v1/tensions` can be retried safely when you send an `Idempotency-Key` header (see The eleven writes). The other creates are not idempotent: `POST /v1/tasks`, `POST /v1/meetings/{meeting_id}/agenda-items` and `POST /v1/structure-exports` create a record on every call, so deduplicate on your side rather than retrying blindly: on those, an `Idempotency-Key` header is refused with `400` rather than ignored.

### Rate limits

At present, each API key may send **100 requests in any rolling 60 seconds**. Reads and writes count the same, each key has its own allowance, and a refused request uses none of it. The window slides: a request frees its place 60 seconds after it was made, so the 101st request within a minute is refused and places come back one by one afterwards. Read the figure from the `X-RateLimit-Limit` header of your own responses rather than hard-coding it. It is a Talkspirit setting, not part of the contract, and it can change.

- **Exports have their own limit.** An organisation can start ten structure exports per rolling hour, those started from the **Export the organisation** screen included. That `429` carries `STRUCTURE_EXPORT_LIMIT_REACHED` and a `Retry-After` of one hour. The calls that start and follow an export also count against the key's 100 requests. The goal, task, member, and checklist and metric exports have limits of their own, also counted for the whole organisation and shared with the administration screens: past it, a `429` carries `EXPORT_LIMIT_REACHED` and a `Retry-After` of one hour. The goal, task and member exports also allow one run per account at a time: a second start answers `429 EXPORT_ALREADY_RUNNING` with a `Retry-After` of one minute.
- **On a `429`, wait.** Pause for the number of seconds in the `Retry-After` header, then repeat the request. This is safe even for a write, because the request is refused before anything runs. If refusals keep coming, slow down and add a small random delay to each retry. Larger pages, `?include=` instead of a follow-up call, and caching what rarely changes go further than retrying faster.
- **To ask for more,** contact your Talkspirit contact or Talkspirit support. Say what you need: your peak in requests per minute, your daily volume and the endpoints you call. The allowance is set for all of Talkspirit, not on your key, so an administrator of your organisation cannot raise it. A higher figure would apply to every integration, so each request is weighed and none is promised.

## What the errors mean

| Status and code | What happened |
| --- | --- |
| `401 AUTHENTICATION_REQUIRED` | No `Authorization` header on the request. |
| `401 AUTHENTICATION_INVALID` | The key is unknown or revoked, or the organisation does not have API access. The message tells the two apart. |
| `403 FORBIDDEN_SCOPE` | The key is valid but was not granted the scope this endpoint needs. |
| `403 FORBIDDEN_UPSTREAM` | The key has the scope, but the account behind it may not make this change to a member, or is not an administrator for the activity log or an export. An administrator has to grant it. |
| `403 TENSIONS_NEED_HOLACRACY_ADDON` | The organisation does not have the Holacracy add-on, so every tension route is refused (`422` with the same code when an agenda item names a `source_tension_id`). An administrator has to act. |
| `403 FORBIDDEN_SIGN_IN_DISABLED`, `FORBIDDEN_MODULE_DISABLED`, `FORBIDDEN_ACCOUNT_SUSPENDED`, `FORBIDDEN_ACCOUNT_UNKNOWN` or `FORBIDDEN_ACCESS_DENIED` | The scope is there, but the organisation refuses the account behind the key: its sign-in method has been switched off, the module this endpoint reads is off, the account is suspended, it no longer exists in the organisation, or it may not see what you asked for. Branch on the `code`. |
| `400 INVALID_CURSOR`, `INVALID_INCLUDE` or `INVALID_PARENT_TASK_ID` | The pagination token is malformed or past its ceiling, an `include` token is not one this endpoint accepts, or `parent_task_id` is not a task id or is repeated. |
| `400 INVALID_ACTIVITY_TYPE`, `INVALID_MEMBER`, `INVALID_ACTOR`, `INVALID_ROLE_ID`, `INVALID_CIRCLE_ID`, `INVALID_OCCURRED_AFTER`, `INVALID_OCCURRED_BEFORE`, `OCCURRED_AFTER_CURSOR_MISMATCH` or `OCCURRED_BEFORE_CURSOR_MISMATCH` | On `GET /v1/activities`: `type` is missing, unknown or repeated; a filter is repeated or is not a single id, or a single instant carrying a UTC offset; `occurred_before` is earlier than `occurred_after`; or a window differs from the one the `cursor` is pinned to. `actor` set to the all-zero id `00000000-0000-0000-0000-000000000000` is refused with `INVALID_ACTOR`. Resend the same values on every page of a walk. |
| `400 IDEMPOTENCY_KEY_NOT_SUPPORTED` | An `Idempotency-Key` header was sent to a write that does not deduplicate: `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` or `PATCH /v1/tensions/{tension_id}/status`. Remove the header. |
| `400 IDEMPOTENCY_KEY_INVALID` | The `Idempotency-Key` sent to `POST /v1/tensions` is not 1 to 255 visible ASCII characters. Nothing was created. |
| `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` or `IDEMPOTENCY_KEY_OUTCOME_UNKNOWN` | A `POST /v1/tensions` repeated with a key already used. `IDEMPOTENCY_REQUEST_IN_PROGRESS`: the first request is still running, so retry with the same key after `Retry-After`. `IDEMPOTENCY_KEY_OUTCOME_UNKNOWN`: the first request failed after the tension may have been created, so read `GET /v1/tensions?sort=-created_at` and resend with a new key only if it is not there. |
| `409 ACTIVITY_LOG_DISABLED` | The organisation has never switched its activity log on. An administrator changes that setting; retrying does not help. |
| `429 RATE_LIMIT_EXCEEDED`, `UPSTREAM_RATE_LIMITED` or `STRUCTURE_EXPORT_LIMIT_REACHED` | `RATE_LIMIT_EXCEEDED`: your key sent more than its 100 requests in 60 seconds (see Rate limits above). `UPSTREAM_RATE_LIMITED`: Talkspirit's own services behind the API are temporarily limiting requests, often because of many parallel calls. Your allowance is untouched and there is no figure to raise: wait and retry. `STRUCTURE_EXPORT_LIMIT_REACHED`: the organisation has started its ten structure exports for the hour. Wait the number of seconds in the `Retry-After` header. |
| `404 STRUCTURE_EXPORT_NOT_FOUND`, `409 STRUCTURE_EXPORT_NOT_READY` or `STRUCTURE_EXPORT_FAILED`, `410 STRUCTURE_EXPORT_FILE_EXPIRED` | `404`: the export does not exist for this key, or it ended more than 24 hours ago. `409`: the export is still running, so poll again, or it failed, so start a new one. `410`: the file address has expired, so start a new one. |
| `404 EXPORT_NOT_FOUND`, `409 EXPORT_NOT_READY` or `EXPORT_FAILED`, `410 EXPORT_FILE_EXPIRED` | The same as the structure export above, for the goal, task, member and checklist and metric exports. A run of another kind answers `404` too. |
| `429 EXPORT_LIMIT_REACHED` or `EXPORT_ALREADY_RUNNING` | `EXPORT_LIMIT_REACHED`: the organisation has started its exports of that kind for the hour. `EXPORT_ALREADY_RUNNING`: your account already has a goal, task or member export in progress. Wait the number of seconds in the `Retry-After` header. |
| `404 TENSION_LINK_NOT_FOUND` | The link is not the current outcome of that tension, or the key's account may not remove it. Nothing was removed. |
| `502 UPSTREAM_ERROR` or `UPSTREAM_AUTH_ERROR` | A service this endpoint depends on failed or answered unexpectedly. Nothing changed, so retry with backoff. |
| `504` | The request passed the server's time limit and was abandoned. Whether a write took effect is undefined, so repeat it only if repeating it is safe. |

A refusal by the organisation, the five `403` codes in the table, is final: neither retrying nor minting a new key clears it. An administrator of the organisation has to act. `FORBIDDEN_ACCESS_DENIED` also answers when the organisation is being deleted or no longer exists: no administrator can help then, so contact Talkspirit support. Until contract 0.49.0 those refusals, and Talkspirit's own rate limiting, both arrived as a `502`, which reads as temporary. An integration written against that behaviour retries a refusal for ever and ignores `Retry-After` on a throttle, so check yours against the table above.

Error bodies never say whether a key exists or whether it was the scope that failed, so do not try to infer state from them.

## What's next?

- [Managing API tokens as an admin](/en/integrations/manage-api-tokens-as-an-admin)
- [How do I add or remove an integration?](/en/integrations/enable-a-cloud-file-picker)
