Publication membership and capabilities

Manage collaborators in a publication's Management membership. Membership is separate from public author profiles and from service-wide admission.

Authentication

Every route requires a bearer token and active publication membership for the effective Personal or organization principal. Use current context and member action flags before offering an edit. Owner/Admin roles grant protected management actions, while optional actions come from current role defaults or a custom capability selection. Organization grants restrict both sets of actions.

Routes

Paths below include the /v1 API prefix. Write routes use publication_id; list routes also accept publication_slug.

Route	Capability	Required fields	Optional fields / result
`GET` or `POST /v1/member/list`	`member.list`	Publication selector	`limit` (1–100, default 50), `offset` (0–1,000,000, default 0); returns `members`, `total_count`, `next_offset`, group, roles, and active Owner count.
`POST /v1/member/get`	`member.list`, or self with `publication.get`	One publication selector; `member_id` or `principal_id`	See member detail.
`POST /v1/member/save`	`member.save`; role changes additionally require `member.assign_roles`	`publication_id`, `principal_id`	`member_id` for an existing membership; `role`, `status`; returns `saved`, `member`, and nullable updated `context`.
`POST /v1/member/remove`	`member.remove`	`publication_id`, `principal_id`, exact `member_id`	Returns `removed`, member identifiers, and nullable updated `context`.
`POST /v1/member/leave`	`member.leave`	`publication_id`	Removes the current workspace's membership; returns `left`. Target principal, member, role, and status fields are rejected.
`GET` or `POST /v1/member/capabilities/list`	`member.list`	Publication selector	Returns read-only `tags` and `roles`.
`POST /v1/member/capabilities/save`	`member.save`	`publication_id`, `principal_id`, exact `member_id`, `mode`, `tag_ids`	Returns `saved` and updated `context`.

Membership writes use local Blog roster UUIDs, not native user or organization IDs. Targets must be active admitted roster principals. Owner can manage all membership levels; Admin can manage ordinary Members. Accepted roles are owner, admin, and member; editable statuses are active and disabled. For an existing membership, omitted role/status retain current values. A new direct membership defaults to active Member. An existing membership must be identified exactly before lifecycle changes; do not use creation as reactivation.

{
  "publication_id": "PUBLICATION_UUID",
  "principal_id": "COLLABORATOR_PRINCIPAL_UUID",
  "member_id": "MEMBERSHIP_UUID",
  "status": "disabled"
}

The final active Owner cannot be disabled, demoted, removed, or leave. Operations recheck authority while applying the change. A successful self-change can return context: null when the caller loses access; stop using the old context. Inviting or applying uses a separate recipient-consent workflow; see invitations and applications.

Select optional capabilities

Load the catalogue for the publication. Each tag has tag_id, capability, name, and description; use tag_id in the save request. roles describes current defaults and permitted selections. These are read-only definitions.

{
  "publication_id": "PUBLICATION_UUID",
  "principal_id": "COLLABORATOR_PRINCIPAL_UUID",
  "member_id": "MEMBERSHIP_UUID",
  "mode": "custom",
  "tag_ids": ["CAPABILITY_TAG_UUID"]
}

mode is defaults or custom. Send tag_ids: [] for defaults; for custom, an empty list deliberately selects no optional grants. IDs must be unique and allowed for the target's current role. Changing a role clears its old custom selection. Protected management rights and the last-owner rule are independent of optional selections. Member results include capabilities_mode, selected capability_tag_ids, can_update, can_remove, can_leave, can_edit_capabilities, allowed_roles, and allowed_statuses.

Public capability discovery

GET /v1/capabilities.json returns the current read-only service capability catalogue without authentication. It is a raw JSON document, outside the usual response envelope, with schema_version, service, catalogue_version, families, capabilities, presets, and role_defaults. Use capability id values to understand action names and profile expansions. Catalogue definitions do not grant the caller those actions; the selected resource context remains the access decision. Blog also accepts HEAD. Optional positive integer catalogue_version selects a retained catalogue revision; malformed values return 400. An unavailable catalogue returns 503.

Errors and recovery

Malformed input or invalid/duplicate capability selections return 400; missing active membership or permission returns 403; missing target membership returns 404; conflicting lifecycle or last-owner changes return 409. Capability catalogue unavailability fails closed.

Remove and Leave coordinate with the relationship for the selected publication when one exists. A remote failure does not report success or delete the local membership. Retry the same action after recovery; a lost successful remote reply can be completed without duplicating the removal event. Direct memberships with no relationship still support local removal. See the relationship recovery contract.