Developers¶

Rhizome has an HTTP API. You can use it to read and write data from outside the application: topics, posts, proposals, decisions, tasks, documents and groups.

It is available at /api/v1. The complete, up-to-date interface description is available as an OpenAPI document at /api/v1/openapi.json.

First of all: enable the API¶

Access is disabled for each organisation until someone enables it – under Settings → Integrations → API. Only those authorised to manage integrations may do this.

Creating a key¶

As long as the API is enabled, each person generates their own keys – also under Settings → Integrations:

• Name – what the key is for, e.g. My App
• Permission – Read only or Read and write
• Expiry date – optional

The key is displayed exactly once. After that, it cannot be viewed again; it can only be deleted and recreated. The table below shows when each key was last used.

Log in¶

A key is included in the standard header:

GET /api/v1/topics/ HTTP/1.1
Authorization: Bearer rhi_…

A key acts as the person who created it. It sees exactly what that person sees and is permitted to do exactly what that person is permitted to do – there is no separate system of permissions. Anyone building an integration that is intended to see more requires the permissions of a person who sees more.

'Read-only' means read-only. A read key is rejected for every POST, PUT, PATCH and DELETE, regardless of what it points to. The rule applies to the HTTP method, not to individual routes.

What’s on offer¶

Reading lists¶

Each list takes the same two parameters: limit (default 50, maximum 200) and offset. The response indicates with has_more whether to continue – press offset += limit to scroll until it shows false.

There is deliberately no total figure: calculating it would require a second query from each page.

The detailed view of a topic is equally limited. It explains what the topic is about and, for lists that can grow indefinitely, simply states the number – the items can be viewed individually.

Errors¶

The API returns the standard status codes: 400 for incorrect details, 401 if there is no valid key, 403 if authorisation is lacking – including when a read key is used for a write call – 404 if the item does not exist, 409 in the event of a conflict.

Unrecognised fields in a call are rejected rather than silently ignored. This means that a typing error in a field name is spotted straight away, rather than later when it appears as a missing entry.