COLLECTIVE API

Programmatic management of collectives — membership, settings, tokens, and published extensions. Every endpoint lives under /api/v1/collectives.

A machine-readable description of this whole surface is served at /api/v1/openapi.json (OpenAPI 3.1, public, no credential required). It covers every endpoint on this page, and a test fails the build if the two ever disagree in either direction.

Authentication

Both credential types from API key authentication work, but they are not interchangeable.

Every endpoint requires a credential. Anonymous requests are 401.

Endpoints

Reads

/invitations is gated one rung higher on both credential types because its response carries email addresses, which appear on no public page. A collective:read token is deliberately not enough — read is the scope you grant for a low-trust credential, and it must not out-rank a member's session on the same data.

Writes

What this API does not do

Two capabilities are absent by decision rather than by oversight, and both are stated in the OpenAPI document as well.

Membership writes accept a session only. Invite, remove, and role changes authorize through the underlying membership guards, which resolve the acting user from a session cookie. A bearer credential — personal key or collective token — presents no cookie, so it cannot drive them. Everything else on this page works with either credential.

There is no audit or activity-log endpoint. No audit store exists behind collectives to serve one from, so rather than return something partial the endpoint is not offered.

Updating settings

PATCH /api/v1/collectives/{slug} takes any subset of four fields. Omitting a field leaves it alone.

curl -X PATCH https://swamp-club.com/api/v1/collectives/acme \
  -H "Authorization: Bearer $SWAMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "We make things", "private": true}'

An empty body is 400 rather than a silent success. A personal collective is 400 — personal collectives cannot be updated.

The interactive privacy setting has a fifth option, applyToExisting, which retroactively hides members' existing issues. It is not accepted here: it is a one-way bulk rewrite, and an irreversible bulk action does not belong on an endpoint built to be scripted. Use the collective's settings page for that.

Status codes

A private collective is deliberately indistinguishable from one that does not exist. Both answer 404, so the status code never confirms a slug to someone guessing.