Mastodon-Compatible Groups & Topics API

Draft extension of the standard Mastodon REST API for Bonfire groups and topics.

All new endpoints live under /api/v1-bonfire/ to distinguish them from the standard Mastodon v1/v2 API.

Design Principles

• Groups are Accounts. A Bonfire Category with type: :group or type: :topic is an ActivityPub actor and is served as a standard Mastodon Account object. This means groups can appear as the account (creator/subject) on a Status or any other activity without special-casing on the client. Account.display_name maps to Category.name; Account.note maps to Category.summary.
• group is an extension field. Just as Event extends Status by adding an event field, Group extends Account by adding a group field. The group field only contains fields that don't already exist on Account.
• IDs are shared. The group's Account.id is the same ULID as the underlying Category. Bonfire resolves IDs through our pointer table, so the same ID routes correctly to the category schema without any prefix.
• Depth is opt-in. Full nested sub_groups and parent_group objects are not included by default. Callers request them via depth params. A flat parent_group_id is always present.
• Follow and membership are partially decoupled. Following a group subscribes to its feed in the home timeline. Membership grants access rights (posting, private content). Joining automatically follows, and leaving automatically unfollows, but each can be adjusted independently afterwards.
• Group timeline = account statuses. Since a group is an account with the same ID, use the standard GET /api/v1/accounts/:id/statuses to fetch its feed. No duplicate endpoint needed.

The group Extension Object

Attached to any Account that represents a group or topic as account.group. Fields already present on Account are not duplicated here (name → display_name, summary → note, canonical_url → url, username → username).

{
  "type": "group",
  "join_mode": "free",
  "members_count": 0,
  "is_disabled": false,
  "extra_info": null,
  "parent_group_id": null,
  "parent_group": null,
  "sub_groups": []
}

Example — full Account with group extension

{
  "id": "01JPXYZ...",
  "username": "cooking",
  "acct": "cooking@social.example",
  "display_name": "Cooking",
  "note": "<p>All things food and drink.</p>",
  "url": "https://social.example/@cooking",
  "uri": "https://social.example/groups/cooking",
  "avatar": "https://social.example/media/cooking-avatar.jpg",
  "avatar_static": "https://social.example/media/cooking-avatar.jpg",
  "header": "https://social.example/media/cooking-header.jpg",
  "header_static": "https://social.example/media/cooking-header.jpg",
  "locked": false,
  "created_at": "2024-01-15T10:00:00.000Z",
  "followers_count": 128,
  "following_count": 0,
  "statuses_count": 342,
  "emojis": [],
  "fields": [],
  "group": {
    "type": "group",
    "join_mode": "free",
    "is_disabled": false,
    "extra_info": null,
    "parent_group_id": null,
    "parent_group": null,
    "sub_groups": [
      {
        "id": "01JPXYZ...",
        "username": "baking",
        "acct": "baking@social.example",
        "display_name": "Baking",
        "note": "<p>Bread, pastry, and everything baked.</p>",
        "url": "https://social.example/@baking",
        "locked": false,
        "group": {
          "type": "topic",
          "join_mode": "free",
          "is_disabled": false,
          "extra_info": null,
          "parent_group_id": "01JPXYZ...",
          "parent_group": null,
          "sub_groups": []
        }
      }
    ]
  }
}

Endpoints

GET /api/v1-bonfire/groups

List groups (and optionally topics/labels).

Authentication: optional (public groups visible to all; private groups only to members)

Query parameters:

Response: 200 OK — Array<Account> (each with group field) Includes Link header for pagination (same RFC 5988 format as Mastodon timelines).

GET /api/v1-bonfire/groups/:id

Get a single group or topic by ID (ULID) or username.

Authentication: optional

Query parameters:

Response:

• 200 OK — Account with group field
• 404 Not Found — not found or not readable by current user

GET /api/v1-bonfire/groups/:id/members

List members of a group.

Authentication: optional (may require membership for private groups)

Query parameters:

Response: 200 OK — Array<{ account: Account, relationship: Relationship }>. Each entry pairs the standard Account object with its Relationship so relationship.group.role is consistent with every other endpoint that returns Relationships.

[
  {
    "account": {
      "id": "01JPXYZ...",
      "username": "alice",
      "acct": "alice@social.example",
      "display_name": "Alice"
    },
    "relationship": {
      "id": "01JPXYZ...",
      "following": true,
      "group": {
        "member": true,
        "role": "admin"
      }
    }
  }
]

Includes Link header for pagination.

GET /api/v1-bonfire/accounts/:id/groups

List groups that an account is a member of.

Authentication: optional

Query parameters:

Response: 200 OK — Array<Account> (each with group field) Includes Link header for pagination.

Extended Relationship Object

When GET /api/v1/accounts/relationships?id[]=:group_id is called for an account that is a group, the standard Mastodon Relationship object gains an extra group field. following retains its standard meaning (subscribed to the group's posts in home feed) and is independent from group.member.

{
  "id": "01JPXYZ...",
  "following": true,
  "showing_reblogs": true,
  "notifying": false,
  "followed_by": false,
  "blocking": false,
  "muting": false,
  "requested": false,
  "note": "",
  "group": {
    "member": true,
    "role": "member"
  }
}

No new endpoint needed — this is purely an extension of the existing relationships response.

POST /api/v1-bonfire/groups/:id/join

Join a group, or request to join if join_mode is "request".

Authentication: required

Response: 200 OK — updated Relationship

If join_mode is "free":

{
  "id": "01JPXYZ...",
  "following": true,
  "requested": false,
  ...
  "group": {
    "member": true,
    "role": "member"
  }
}

If join_mode is "request" (pending approval):

{
  "id": "01JPXYZ...",
  "following": false,
  "requested": true,
  ...
  "group": {
    "member": false,
    "role": null
  }
}

Note: Joining with join_mode: "free" also automatically sets following: true. The user can later unfollow the group feed without leaving by calling POST /api/v1/accounts/:id/unfollow.

Error responses:

• 404 Not Found — group does not exist or is not visible to current user

POST /api/v1-bonfire/groups/:id/leave

Leave a group, or cancel a pending join request.

Authentication: required

Response: 200 OK — updated Relationship

{
  "id": "01JPXYZ...",
  "following": false,
  "requested": false,
  ...
  "group": {
    "member": false,
    "role": null
  }
}

Note: Leaving also automatically sets following: false. The user can later re-follow the group feed without rejoining (if posts are visible to non-members) by calling POST /api/v1/accounts/:id/follow.

Error responses:

• 404 Not Found — group does not exist or is not visible to current user

Posting a Status — Extension Parameters

The standard POST /api/v1/statuses accepts the following additional parameters.

Context

Visibility

visibility works exactly as Mastodon defines it (i.e. sets the visibility of the posted status to public, unlisted, private, or direct), but Bonfire provides extra visibility options, and the defaults can also be extended by each user or group, so you can use GET /api/v1-bonfire/boundaries to get options available for the authenticated user (eg. for a new post).

In a later version: You can also use GET /api/v1-bonfire/boundaries?context=<post|user|instance|group> to get possible options for different contexts.

When posting a status with context_id being a group, it is recommended to omit visibility so it will use the group's configured default.

In a later version: If provided along with context_id, it must be a value permitted by the group — use GET /api/v1-bonfire/boundaries?context=<group_id> to discover what is allowed for that group before composing.

Interaction policies

Modeled after Mastodon's quote_approval_policy field and QuoteApproval entity. Each interaction has policy fields controlling automatic approval, manual approval (request where supported), and explicit denial. When context_id is a group, omit all policy fields to use the group's configured defaults. Ignored when visibility is direct.

The available policies and their permitted values depend on the context — use GET /api/v1-bonfire/boundaries?context=... to discover what applies before composing. The params listed below are the known set; not all are supported in every context:

All field types accept the same value format: one or more keywords or account IDs. Available keywords are provided by GET /api/v1-bonfire/boundaries as they can be extended by the server or group. In a future version, circle IDs will also be supported.

The Status object — extension fields

Extension fields present on Status responses when applicable. The *_approval objects follow the same shape as Mastodon's QuoteApproval entity, extended to all interaction types.

{
  "context_id": "01JPXYZ...",
  "context_type": "group",
  "quote_approval": {
    "automatic": ["followers"],
    "manual": ["public"],
    "current_user": "automatic"
  },
  "reply_approval": {
    "automatic": ["followers", "mentioned"],
    "manual": ["public"],
    "current_user": "denied"
  },
  "announce_approval": {
    "automatic": ["followers"],
    "manual": [],
    "current_user": "manual"
  },
  "like_approval": {
    "automatic": ["public"],
    "current_user": "automatic"
  }
}

current_user on each approval object is one of "automatic", "manual", "denied", or "unknown".

Boundaries Discovery

GET /api/v1-bonfire/boundaries

Returns the visibility presets and available interaction policy options for the given context. Clients use this to build a compose UI with the correct visibility picker and policy selectors.

Authentication: required

Query parameters:

Examples:

• GET /api/v1-bonfire/boundaries — options for a regular post
• GET /api/v1-bonfire/boundaries?context=instance — instance-level policies (TODO in a later version)
• GET /api/v1-bonfire/boundaries?context=01JPXYZ... — options permitted when posting into that group or topic (TODO in a later version)

Response: 200 OK

{
  "context": "01JPXYZ...",
  "visibility": ["public", "unlisted", "private"],
  "visibility_labels": {
    "public":   {"label": "Public",      "icon": "globe",    "description": "Visible to everyone"},
    "unlisted": {"label": "Local only",  "icon": "home",     "description": "Visible to users on this instance"},
    "private":  {"label": "Followers",   "icon": "lock",     "description": "Visible to your followers only"},
    "direct":   {"label": "Direct",      "icon": "envelope", "description": "Visible to mentioned users only"}
  },
  "policies": {
    "reply_approval_policy":        ["public", "followers", "members", "mentioned", "nobody"],
    "reply_denied_policy":          ["public", "followers", "members", "mentioned", "nobody"],
    "announce_approval_policy":     ["public", "followers", "members", "nobody"],
    "announce_denied_policy":       ["public", "followers", "members", "nobody"],
    "like_approval_policy":         ["public", "followers", "members", "nobody"],
    "like_denied_policy":           ["public", "followers", "members", "nobody"],
    "quote_approval_policy":        ["public", "followers", "nobody"],
    "quote_manual_approval_policy": ["public", "followers", "members", "nobody"],
    "quote_denied_policy":          ["public", "followers", "members", "nobody"]
  },
  "policy_labels": {
    "public":    {"label": "Anyone",         "icon": "globe",    "description": "Anyone can interact"},
    "followers": {"label": "Followers",      "icon": "lock",     "description": "Only your followers"},
    "members":   {"label": "Group members",  "icon": "people",   "description": "Only members of this group"},
    "mentioned": {"label": "Mentioned only", "icon": "at",       "description": "Only accounts you mention"},
    "nobody":    {"label": "Nobody",         "icon": "block",    "description": "Disabled"}
  }
}

Dedicate endpoints NOT needed (use standard Mastodon API)

Notes on Depth Parameters

sub_depth=N and parent_depth=N control recursive nesting. parent_group_id is always present regardless.

• 0 — full object omitted (sub_groups: [], parent_group: null)
• 1 — one level: direct children / immediate parent
• 2 — two levels: children of children / parent and grandparent
• etc.

List endpoints (GET /groups) default both to 0 to keep responses lean. Single-item endpoints (GET /groups/:id) default both to 1.