Profiles

Groups

actor-service

Made by somebody signed in, looked after by its admins, and followed by people (groups.md): its rules, agreed to before following it, and the events it hosts.

Groups

GET/groups/

Those the viewer may see. Each a full profile, or, for one the viewer may only ask to follow, what a stranger is shown of it (restricted).

Who: Anyone, signed in or not

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
qstringin query
Words the name, the handle or the description holds. At most 100 characters.
orderingstringin query
What they are ordered by. At most 15 characters. One of created_at, updated_at, enabled. updated_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
disabledbooleanin query
Disabled ones as well, for whoever may see them.
featuredbooleanin query
Only the actors the installation features — what onboarding offers a new member to follow. Ordered most recently featured first unless the caller asks for an ordering; see the browse handlers.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be
403
the viewer may not list groups

Request

curl "https://api.example.org/groups/"

const response = await fetch('https://api.example.org/groups/', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/groups/",
)
answer = response.json()

Answer · 200

{
  "data": [
    null
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Make a group

POST/groups/

Whoever makes it is its first administrator. Left without access, only its administrators can see it until they open it.

Who: Somebody signed in

Body application/x-www-form-urlencoded or multipart/form-data

accessstring
Who can see it. Left out, only its administrators, until they open it from its settings. One of public, registered, followers, admins.
bodystring
What it says of itself. At most 500 characters.
enabledboolean
Whether it is enabled. true unless given.
namestringrequired
Its name. At most 64 characters.
website_urlstring (uri)
One link on the profile. A bare example.com is taken as https. At most 255 characters.

Answers

201
Created
actor.GroupNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
422
access_not_allowed: public, where nothing new may be, with the levels it may have
AudienceRefusal application/json

Request

curl -X POST "https://api.example.org/groups/" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "access=public" \
  --data-urlencode "body=string" \
  --data-urlencode "enabled=true" \
  --data-urlencode "name=string" \
  --data-urlencode "website_url=https://example.org/"

const form = new URLSearchParams();
form.append('access', "public");
form.append('body', "string");
form.append('enabled', "true");
form.append('name', "string");
form.append('website_url', "https://example.org/");
const response = await fetch('https://api.example.org/groups/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/groups/",
    headers={"Authorization": f"Bearer {token}"},
    data={"access": "public", "body": "string", "enabled": "true", "name": "string", "website_url": "https://example.org/"},
)
answer = response.json()

Answer · 201

{
  "access": "string",
  "administrators": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string"
    }
  ],
  "alias": "string",
  "allow_download": false,
  "allow_follow_request": false,
  "archived_at": "2026-10-27T09:30:00Z",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "featured_at": "2026-10-27T09:30:00Z",
  "features": [
    {
      "add_permissions": [
        null
      ],
      "composers": [
        null
      ],
      "enabled": false,
      "node_types": [
        null
      ],
      "optional": false,
      "ordering": 1,
      "service": "string"
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_invited": false,
  "is_leading_viewer": false,
  "leader_count": 1,
  "name": "string",
  "origin_domain": "string",
  "permissions": {
    "key": "string"
  },
  "show_reposts_on_profile": false,
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "verified": false,
  "website_url": "https://example.org/"
}

One group

GET/groups/{id}

To somebody it is not open to, but who may ask to follow it, what a stranger is shown of it.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The profile's id.

Answers

200
it, or what a stranger is shown of it (LimitedActor)
actor.GroupNode application/json
400
the request is not well formed, or a value in it is not one it may be
403
the viewer may not see it
404
there is no such group

Request

curl "https://api.example.org/groups/<id>"

const response = await fetch('https://api.example.org/groups/<id>', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/groups/<id>",
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "administrators": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string"
    }
  ],
  "alias": "string",
  "allow_download": false,
  "allow_follow_request": false,
  "archived_at": "2026-10-27T09:30:00Z",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "featured_at": "2026-10-27T09:30:00Z",
  "features": [
    {
      "add_permissions": [
        null
      ],
      "composers": [
        null
      ],
      "enabled": false,
      "node_types": [
        null
      ],
      "optional": false,
      "ordering": 1,
      "service": "string"
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_invited": false,
  "is_leading_viewer": false,
  "leader_count": 1,
  "name": "string",
  "origin_domain": "string",
  "permissions": {
    "key": "string"
  },
  "show_reposts_on_profile": false,
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "verified": false,
  "website_url": "https://example.org/"
}

Change a group

PATCH/groups/{id}

Who: Somebody signed in

Parameters

idintegerrequiredin path
The profile's id.

Body application/x-www-form-urlencoded or multipart/form-data

bodystring
What it says of itself. At most 500 characters.
enabledboolean
Whether it is enabled.
namestringrequired
Its name. At most 64 characters.
website_urlstring (uri)
One link on the profile. A bare example.com is taken as https. At most 255 characters.

Answers

200
OK
actor.GroupNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such group

Request

curl -X PATCH "https://api.example.org/groups/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "body=string" \
  --data-urlencode "enabled=false" \
  --data-urlencode "name=string" \
  --data-urlencode "website_url=https://example.org/"

const form = new URLSearchParams();
form.append('body', "string");
form.append('enabled', "false");
form.append('name', "string");
form.append('website_url', "https://example.org/");
const response = await fetch('https://api.example.org/groups/<id>', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/groups/<id>",
    headers={"Authorization": f"Bearer {token}"},
    data={"body": "string", "enabled": "false", "name": "string", "website_url": "https://example.org/"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "administrators": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string"
    }
  ],
  "alias": "string",
  "allow_download": false,
  "allow_follow_request": false,
  "archived_at": "2026-10-27T09:30:00Z",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "featured_at": "2026-10-27T09:30:00Z",
  "features": [
    {
      "add_permissions": [
        null
      ],
      "composers": [
        null
      ],
      "enabled": false,
      "node_types": [
        null
      ],
      "optional": false,
      "ordering": 1,
      "service": "string"
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_invited": false,
  "is_leading_viewer": false,
  "leader_count": 1,
  "name": "string",
  "origin_domain": "string",
  "permissions": {
    "key": "string"
  },
  "show_reposts_on_profile": false,
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "verified": false,
  "website_url": "https://example.org/"
}

The events a group hosts

GET/groups/{id}/events/

Those the viewer may see. Each an event, or what is shown of one the viewer may only answer as a follower of the group.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The group.
filterstringin query
upcoming or past. Upcoming when left out. One of upcoming, past.
startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send: up to 100. At least 0. At most 100. 20 unless given.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be
403
the viewer may not see the group
404
there is no such group

Request

curl "https://api.example.org/groups/<id>/events/"

const response = await fetch('https://api.example.org/groups/<id>/events/', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/groups/<id>/events/",
)
answer = response.json()

Answer · 200

{
  "data": [
    null
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

The rules of a group

GET/groups/{id}/rules

What somebody agrees to, each ticked, before following it or answering it: at most ten, in order, with the version they are at and the version the viewer last agreed to. For whoever may see it, and for whoever it would let ask to follow.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The profile's id.

Answers

200
OK
actor.Rules application/json
400
the request is not well formed, or a value in it is not one it may be
403
the viewer may not see it
404
there is no such group

Request

curl "https://api.example.org/groups/<id>/rules"

const response = await fetch('https://api.example.org/groups/<id>/rules', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/groups/<id>/rules",
)
answer = response.json()

Answer · 200

{
  "agreed_version": 1,
  "items": [
    {
      "body": "string",
      "title": "string"
    }
  ],
  "updated_at": "2026-10-27T09:30:00Z",
  "version": 1
}

Set the rules of a group

PUT/groups/{id}/rules

The rules as they are to be from now on, in order, at most ten; an empty list takes them away. Every change raises the version, so that whoever agreed before is asked again. For whoever may change it.

Who: Somebody signed in

Parameters

idintegerrequiredin path

Body application/json

itemslist of actor.Rule
At most 10 of them.

Answers

200
OK
actor.Rules application/json
400
rules_invalid: more than ten, or one too long
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such group

Request

curl -X PUT "https://api.example.org/groups/<id>/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "body": "string",
        "title": "string"
      }
    ]
  }'

const response = await fetch('https://api.example.org/groups/<id>/rules', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "items": [
      {
        "body": "string",
        "title": "string"
      }
    ]
  }),
});
const answer = await response.json();

import requests

response = requests.put(
    "https://api.example.org/groups/<id>/rules",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "items": [
        {
          "body": "string",
          "title": "string"
        }
      ]
    },
)
answer = response.json()

Answer · 200

{
  "agreed_version": 1,
  "items": [
    {
      "body": "string",
      "title": "string"
    }
  ],
  "updated_at": "2026-10-27T09:30:00Z",
  "version": 1
}

Agree to the rules of a group

POST/groups/{id}/rules/agree

The viewer agreeing, each rule ticked, to the version they were shown.

Who: Somebody signed in

Parameters

idintegerrequiredin path

Body application/json

versionintegerrequired

Answers

204
No Content
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
404
there is no such group
409
rules_not_current: the rules changed since; read them again
Refusal application/json

Request

curl -X POST "https://api.example.org/groups/<id>/rules/agree" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1
  }'

const response = await fetch('https://api.example.org/groups/<id>/rules/agree', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "version": 1
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/groups/<id>/rules/agree",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "version": 1
    },
)
answer = response.json()

Remove a group as spam

POST/groups/{id}/spam

A moderator's decision (roadmap row 102): everything of it destroyed at once, with no thirty days, and recorded as removed-as-spam with who decided. Administrators and super administrators; never an administrator's or a super administrator's account, nor one's own. Queued, and done by the sweeper.

Who: An administrator

Parameters

idintegerrequiredin path
The profile's id.

Answers

200
purged or queued already
PurgeQueued application/json
202
queued
PurgeQueued application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer is not an administrator
409
it cannot be removed (administrator, yourself, not_found, wrong_type); nothing was queued
PurgeRefused application/json

Request

curl -X POST "https://api.example.org/groups/<id>/spam" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/<id>/spam', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/groups/<id>/spam",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "batch_id": "string",
  "queued": 1,
  "skipped": 1
}

Destroy many groups for good

POST/groups/purge-batch

As purging one, for up to 500 at once.

Who: A super administrator, who has just proved who they are again

Body application/json

confirmstringrequired
PURGE and how many there are (PURGE 12), typed, to say it is meant. At most 20 characters.
idslist of integerrequired
The profiles: up to 500. At least 1 of them. At most 500 of them.

Answers

200
purged or queued already
PurgeQueued application/json
202
queued
PurgeQueued application/json
400
confirmation_mismatch: confirm does not name how many there are; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
step_up_required: the viewer must prove who they are again first; or the viewer may not, without a body
Refusal application/json
409
some cannot be purged; nothing was queued
PurgeRefused application/json

Request

curl -X POST "https://api.example.org/groups/purge-batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": "string",
    "ids": [
      1
    ]
  }'

const response = await fetch('https://api.example.org/groups/purge-batch', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "confirm": "string",
    "ids": [
      1
    ]
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/groups/purge-batch",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "confirm": "string",
      "ids": [
        1
      ]
    },
)
answer = response.json()

Answer · 200

{
  "batch_id": "string",
  "queued": 1,
  "skipped": 1
}

How far a purge has got

GET/groups/purge-batch/{batch_id}

Asked every few seconds. Changes nothing, and needs no proof.

Who: A super administrator

Parameters

batch_idstring (uuid)requiredin path
What the purge request answered as batch_id.

Answers

200
OK
PurgeProgress application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer is not a super administrator
404
there is no such purge

Request

curl "https://api.example.org/groups/purge-batch/<batch_id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/purge-batch/<batch_id>', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/groups/purge-batch/<batch_id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "batch_id": "string",
  "done": 1,
  "failed": 1,
  "items": [
    {
      "alias": "string",
      "error": "string",
      "id": 42,
      "status": "string"
    }
  ],
  "queued": 1,
  "total": 1
}

As every profile

The same on every kind, at this kind’s address. What each does is under Profiles.

Delete a group

DELETE/groups/{id}

It is out of sight at once and destroyed after thirty days, unless it is restored before then.

Who: Somebody signed in, who has just proved who they are again

Parameters

idintegerrequiredin path
The profile's id.

Answers

200
it will be deleted
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
step_up_required: the viewer must prove who they are again first; or the viewer may not, without a body
Refusal application/json
404
there is no such profile

Request

curl -X DELETE "https://api.example.org/groups/<id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/<id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/groups/<id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Change who may see it

PATCH/groups/{id}/access

And whether people it is not open to may ask to follow it.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The profile's id.

Body application/x-www-form-urlencoded or multipart/form-data

accessstringrequired
Who may see it: public, registered, followers or admins. One of public, registered, followers, admins. public unless given.
allow_follow_requestboolean
Whether people it is not open to may ask to follow it.

Answers

200
OK
actor.GroupNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such profile

Request

curl -X PATCH "https://api.example.org/groups/<id>/access" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "access=public" \
  --data-urlencode "allow_follow_request=false"

const form = new URLSearchParams();
form.append('access', "public");
form.append('allow_follow_request', "false");
const response = await fetch('https://api.example.org/groups/<id>/access', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/groups/<id>/access",
    headers={"Authorization": f"Bearer {token}"},
    data={"access": "public", "allow_follow_request": "false"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "administrators": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string"
    }
  ],
  "alias": "string",
  "allow_download": false,
  "allow_follow_request": false,
  "archived_at": "2026-10-27T09:30:00Z",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "featured_at": "2026-10-27T09:30:00Z",
  "features": [
    {
      "add_permissions": [
        null
      ],
      "composers": [
        null
      ],
      "enabled": false,
      "node_types": [
        null
      ],
      "optional": false,
      "ordering": 1,
      "service": "string"
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_invited": false,
  "is_leading_viewer": false,
  "leader_count": 1,
  "name": "string",
  "origin_domain": "string",
  "permissions": {
    "key": "string"
  },
  "show_reposts_on_profile": false,
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "verified": false,
  "website_url": "https://example.org/"
}

A group's admins

GET/groups/{id}/admins/

Who: Somebody signed in

Parameters

idintegerrequiredin path
The group's or the event's id.
startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. asc unless given.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not see them
404
there is no such group

Request

curl "https://api.example.org/groups/<id>/admins/" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/<id>/admins/', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/groups/<id>/admins/",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "allow_download": false,
      "allow_follow_request": false,
      "archived_at": "2026-10-27T09:30:00Z",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "avatar_urls": {
        "key": null
      },
      "body": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted_at": "2026-10-27T09:30:00Z",
      "enabled": false,
      "event": {
        "address": null,
        "cancelled_at": null,
        "capacity": null,
        "ends_at": null,
        "going_count": null,
        "has_address": null,
        "has_online_url": null,
        "host": null,
        "is_full": null,
        "maybe_count": null,
        "online_url": null,
        "open_to_host_followers": null,
        "starts_at": null,
        "state": null,
        "timezone_name": null,
        "viewer_rsvp": null
      },
      "featured_at": "2026-10-27T09:30:00Z",
      "follower_count": 1,
      "id": 42,
      "is_admined_by_viewer": false,
      "is_blocked_by_viewer": false,
      "is_following_viewer": false,
      "is_invited": false,
      "is_leading_viewer": false,
      "leader_count": 1,
      "name": "string",
      "origin_domain": "string",
      "quote_policy": "string",
      "show_reposts_on_profile": false,
      "type": "string",
      "uri": "https://example.org/",
      "verified": false,
      "website_url": "https://example.org/"
    }
  ]
}

Make somebody an admin of a group

POST/groups/{id}/admins/

By one of its admins. Answers with them.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The group's or the event's id.

Body application/x-www-form-urlencoded or multipart/form-data

admin_idintegerrequired
The person to make an administrator.

Answers

201
Created
ActorNodeItem application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not
404
there is no such group or person

Request

curl -X POST "https://api.example.org/groups/<id>/admins/" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "admin_id=42"

const form = new URLSearchParams();
form.append('admin_id', "42");
const response = await fetch('https://api.example.org/groups/<id>/admins/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/groups/<id>/admins/",
    headers={"Authorization": f"Bearer {token}"},
    data={"admin_id": "42"},
)
answer = response.json()

Answer · 201

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "allow_follow_request": false,
  "archived_at": "2026-10-27T09:30:00Z",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted_at": "2026-10-27T09:30:00Z",
  "enabled": false,
  "event": {
    "address": {
      "city": null,
      "country": null,
      "latitude": null,
      "longitude": null,
      "postal_code": null,
      "state_province": null,
      "street": null
    },
    "cancelled_at": "2026-10-27T09:30:00Z",
    "capacity": 1,
    "ends_at": "2026-10-27T09:30:00Z",
    "going_count": 1,
    "has_address": false,
    "has_online_url": false,
    "host": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null,
      "verified": null
    },
    "is_full": false,
    "maybe_count": 1,
    "online_url": "https://example.org/",
    "open_to_host_followers": false,
    "starts_at": "2026-10-27T09:30:00Z",
    "state": "string",
    "timezone_name": "string",
    "viewer_rsvp": "string"
  },
  "featured_at": "2026-10-27T09:30:00Z",
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_invited": false,
  "is_leading_viewer": false,
  "leader_count": 1,
  "name": "string",
  "origin_domain": "string",
  "quote_policy": "string",
  "show_reposts_on_profile": false,
  "type": "string",
  "uri": "https://example.org/",
  "verified": false,
  "website_url": "https://example.org/"
}

Remove an admin of a group

DELETE/groups/{id}/admins/{admin_id}

Who: Somebody signed in

Parameters

idintegerrequiredin path
The group's or the event's id.
admin_idintegerrequiredin path
The administrator to remove.

Answers

204
removed
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not
404
there is no such group or admin

Request

curl -X DELETE "https://api.example.org/groups/<id>/admins/<admin_id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/<id>/admins/<admin_id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/groups/<id>/admins/<admin_id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Archive a group

POST/groups/{id}/archive

For good, and nothing is destroyed (account-lifecycle.md).

Who: Somebody signed in, who has just proved who they are again

Parameters

idintegerrequiredin path
The profile's id.

Answers

200
archived
204
archived already, or being deleted
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
step_up_required: the viewer must prove who they are again first; or the viewer may not, without a body
Refusal application/json
404
there is no such profile

Request

curl -X POST "https://api.example.org/groups/<id>/archive" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/<id>/archive', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/groups/<id>/archive",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

What deleting a group would take with it

GET/groups/{id}/deletion-counts

For the Danger zone, for whoever may delete it.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The profile's id.

Answers

200
OK
actor.GroupDeletionCounts application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not delete it
404
there is no such profile

Request

curl "https://api.example.org/groups/<id>/deletion-counts" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/<id>/deletion-counts', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/groups/<id>/deletion-counts",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "admins": 1,
  "followers": 1,
  "member_since": "string",
  "posts": 1,
  "replies": 1
}

Change whether new photos and videos may be downloaded

PATCH/groups/{id}/download-default

What a post starts with; each post can say otherwise.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The profile's id.

Body application/json or application/x-www-form-urlencoded or multipart/form-data

allowboolean
Whether its new photos and videos start out downloadable.

Answers

200
OK
actor.GroupNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such profile

Request

curl -X PATCH "https://api.example.org/groups/<id>/download-default" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow": false
  }'

const response = await fetch('https://api.example.org/groups/<id>/download-default', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "allow": false
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/groups/<id>/download-default",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "allow": False
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "administrators": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string"
    }
  ],
  "alias": "string",
  "allow_download": false,
  "allow_follow_request": false,
  "archived_at": "2026-10-27T09:30:00Z",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "featured_at": "2026-10-27T09:30:00Z",
  "features": [
    {
      "add_permissions": [
        null
      ],
      "composers": [
        null
      ],
      "enabled": false,
      "node_types": [
        null
      ],
      "optional": false,
      "ordering": 1,
      "service": "string"
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_invited": false,
  "is_leading_viewer": false,
  "leader_count": 1,
  "name": "string",
  "origin_domain": "string",
  "permissions": {
    "key": "string"
  },
  "show_reposts_on_profile": false,
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "verified": false,
  "website_url": "https://example.org/"
}

Turn a profile on or off

PATCH/groups/{id}/enabled

Reversible, site administrators only. Off, it is out of sight and may not act; nothing is deleted.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The profile's id.

Body application/json

enabledbooleanrequired
Whether it is shown and may act. Off, it is out of sight until it is turned on again; nothing is deleted.

Answers

200
done
204
it was so already
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not
404
there is no such profile

Request

curl -X PATCH "https://api.example.org/groups/<id>/enabled" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

const response = await fetch('https://api.example.org/groups/<id>/enabled', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "enabled": false
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/groups/<id>/enabled",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "enabled": False
    },
)
answer = response.json()

Feature a profile, or stop

PATCH/groups/{id}/featured

What onboarding offers new members to follow. Super administrators only.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The profile's id.

Body application/json

featuredbooleanrequired
Whether onboarding offers it to follow.

Answers

200
done
204
it was so already
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not
404
there is no such profile
409
not_featurable: it is disabled, archived or deleted
Refusal application/json

Request

curl -X PATCH "https://api.example.org/groups/<id>/featured" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "featured": false
  }'

const response = await fetch('https://api.example.org/groups/<id>/featured', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "featured": false
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/groups/<id>/featured",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "featured": False
    },
)
answer = response.json()

Change what may be posted on it

PATCH/groups/{id}/features

Each kind of post, on or off, and who may add it (permissions.md).

Who: Somebody signed in

Parameters

idintegerrequiredin path
The profile's id.

Body application/json

featureslist of ActorFeatureRequestrequired
Each feature as it is to be. An empty list goes back to the installation's defaults.

Answers

200
OK
actor.GroupNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such profile

Request

curl -X PATCH "https://api.example.org/groups/<id>/features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "features": [
      {
        "add_permissions": [
          null
        ],
        "composers": [
          "string"
        ],
        "enabled": false,
        "node_types": [
          "string"
        ],
        "optional": false,
        "ordering": 1,
        "service": "string"
      }
    ]
  }'

const response = await fetch('https://api.example.org/groups/<id>/features', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "features": [
      {
        "add_permissions": [
          null
        ],
        "composers": [
          "string"
        ],
        "enabled": false,
        "node_types": [
          "string"
        ],
        "optional": false,
        "ordering": 1,
        "service": "string"
      }
    ]
  }),
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/groups/<id>/features",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "features": [
        {
          "add_permissions": [
            None
          ],
          "composers": [
            "string"
          ],
          "enabled": False,
          "node_types": [
            "string"
          ],
          "optional": False,
          "ordering": 1,
          "service": "string"
        }
      ]
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "administrators": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string"
    }
  ],
  "alias": "string",
  "allow_download": false,
  "allow_follow_request": false,
  "archived_at": "2026-10-27T09:30:00Z",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "featured_at": "2026-10-27T09:30:00Z",
  "features": [
    {
      "add_permissions": [
        null
      ],
      "composers": [
        null
      ],
      "enabled": false,
      "node_types": [
        null
      ],
      "optional": false,
      "ordering": 1,
      "service": "string"
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_invited": false,
  "is_leading_viewer": false,
  "leader_count": 1,
  "name": "string",
  "origin_domain": "string",
  "permissions": {
    "key": "string"
  },
  "show_reposts_on_profile": false,
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "verified": false,
  "website_url": "https://example.org/"
}

Destroy a group for good

DELETE/groups/{id}/purge

Everything of it, at once and with no thirty days. Super administrators only, never on their own profile. Queued, and done by the sweeper.

Who: A super administrator, who has just proved who they are again

Parameters

idintegerrequiredin path
The profile's id.

Answers

200
purged or queued already
PurgeQueued application/json
202
queued
PurgeQueued application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
step_up_required: the viewer must prove who they are again first; or the viewer may not, without a body
Refusal application/json
409
it cannot be purged; nothing was queued
PurgeRefused application/json

Request

curl -X DELETE "https://api.example.org/groups/<id>/purge" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/<id>/purge', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/groups/<id>/purge",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "batch_id": "string",
  "queued": 1,
  "skipped": 1
}

Restore a deleted group

POST/groups/{id}/restore

Within the thirty days. Answers with it.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The profile's id.

Answers

200
OK
actor.GroupNode application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not
404
there is no such profile to restore

Request

curl -X POST "https://api.example.org/groups/<id>/restore" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/groups/<id>/restore', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/groups/<id>/restore",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "administrators": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string"
    }
  ],
  "alias": "string",
  "allow_download": false,
  "allow_follow_request": false,
  "archived_at": "2026-10-27T09:30:00Z",
  "author": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted_at": "2026-10-27T09:30:00Z",
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "featured_at": "2026-10-27T09:30:00Z",
  "features": [
    {
      "add_permissions": [
        null
      ],
      "composers": [
        null
      ],
      "enabled": false,
      "node_types": [
        null
      ],
      "optional": false,
      "ordering": 1,
      "service": "string"
    }
  ],
  "follower_count": 1,
  "id": 42,
  "is_admined_by_viewer": false,
  "is_blocked_by_viewer": false,
  "is_following_viewer": false,
  "is_invited": false,
  "is_leading_viewer": false,
  "leader_count": 1,
  "name": "string",
  "origin_domain": "string",
  "permissions": {
    "key": "string"
  },
  "show_reposts_on_profile": false,
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "verified": false,
  "website_url": "https://example.org/"
}

Written by Claude, reviewed by Rastin Mehr · About this