People

Following and blocking

socialgraph-service

Who follows whom, asking to follow a profile that is not open to all, invitations to follow a group or an event, and blocks (permissions.md).

Whom a profile has blocked

GET/socialgraph/{actor_id}/blocks/

A person's own, for them; a group's or an event's, for whoever looks after it, and site administrators.

Who: Somebody signed in

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
orderingstringin query
What they are ordered by. At most 15 characters. One of created_at, updated_at. updated_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
qstringin query
Only those whose name has these words. At most 100 characters.
actor_idintegerrequiredin path
The profile's id.

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 profile

Request

curl "https://api.example.org/socialgraph/<actor_id>/blocks/" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

response = requests.get(
    "https://api.example.org/socialgraph/<actor_id>/blocks/",
    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/"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Who asks to follow a profile

GET/socialgraph/{actor_id}/follow-requests/

For whoever looks after it.

Who: Somebody signed in

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
orderingstringin query
What they are ordered by. At most 15 characters. One of created_at, updated_at. updated_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
qstringin query
Only those whose name has these words. At most 100 characters.
actor_idintegerrequiredin path
The profile's id.

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 does not look after it
404
there is no such profile

Request

curl "https://api.example.org/socialgraph/<actor_id>/follow-requests/" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

response = requests.get(
    "https://api.example.org/socialgraph/<actor_id>/follow-requests/",
    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/"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Who follows a profile

GET/socialgraph/{actor_id}/followers/

Those the viewer may see, each saying how they stand with the viewer. On an installation in preview, only for somebody signed in.

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.
orderingstringin query
What they are ordered by. At most 15 characters. One of created_at, updated_at. updated_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
qstringin query
Only those whose name has these words. At most 100 characters.
actor_idintegerrequiredin path
The profile's id.

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
the installation is in preview and the viewer is not signed in
403
the viewer may not see who follows it
404
there is no such profile

Request

curl "https://api.example.org/socialgraph/<actor_id>/followers/"

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

import requests

response = requests.get(
    "https://api.example.org/socialgraph/<actor_id>/followers/",
)
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/"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Invite people to follow a group or an event

POST/socialgraph/{actor_id}/invites

People who follow the viewer. Each is told, and chooses. Answers with what became of each, in the order they were named: somebody who cannot be invited does not stop the others.

Who: Somebody signed in

Parameters

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

Body application/json

person_idslist of integerrequired
Who to invite: people who follow the viewer. At least 1 of them.

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 invite people to it
429
too many invitations lately

Request

curl -X POST "https://api.example.org/socialgraph/<actor_id>/invites" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_ids": [
      1
    ]
  }'

const response = await fetch('https://api.example.org/socialgraph/<actor_id>/invites', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "person_ids": [
      1
    ]
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/socialgraph/<actor_id>/invites",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "person_ids": [
        1
      ]
    },
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "person_id": 42,
      "result": "string"
    }
  ]
}

Who is invited to follow a group or an event

GET/socialgraph/{actor_id}/invites/

For whoever looks after it.

Who: Somebody signed in

Parameters

actor_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. 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
401
no token, or one that has expired
403
the viewer does not look after it

Request

curl "https://api.example.org/socialgraph/<actor_id>/invites/" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

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

Answer · 200

{
  "data": [
    {
      "actor": null,
      "created_at": "2026-10-27T09:30:00Z",
      "ends_at": "2026-10-27T09:30:00Z",
      "inviter": null,
      "person": null
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Take an invitation back

DELETE/socialgraph/{actor_id}/invites/{person_id}

Who: Somebody signed in

Parameters

actor_idintegerrequiredin path
The group's or the event's id.
person_idintegerrequiredin path
The person invited.

Answers

204
taken back
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 does not look after it
404
there is no such invitation

Request

curl -X DELETE "https://api.example.org/socialgraph/<actor_id>/invites/<person_id>" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

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

Accept an invitation

POST/socialgraph/{actor_id}/invites/accept

The viewer follows it from now on.

Who: Somebody signed in

Parameters

actor_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. At most 100.

Answers

200
OK
socialgraph.InviteAnswer 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 follow it
404
the viewer has no invitation to it
409
rules_not_agreed: it is a group or an event with rules the viewer has not agreed to; tick each and agree (POST /groups|events/:id/rules/agree), then ask again
Refusal application/json

Request

curl -X POST "https://api.example.org/socialgraph/<actor_id>/invites/accept" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

response = requests.post(
    "https://api.example.org/socialgraph/<actor_id>/invites/accept",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "accepted": false
}

Turn an invitation down

POST/socialgraph/{actor_id}/invites/decline

Who: Somebody signed in

Parameters

actor_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. At most 100.

Answers

200
OK
socialgraph.InviteAnswer 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
the viewer has no invitation to it

Request

curl -X POST "https://api.example.org/socialgraph/<actor_id>/invites/decline" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

response = requests.post(
    "https://api.example.org/socialgraph/<actor_id>/invites/decline",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "accepted": false
}

Whom a profile follows

GET/socialgraph/{actor_id}/leaders/

As who follows it.

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.
orderingstringin query
What they are ordered by. At most 15 characters. One of created_at, updated_at. updated_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
qstringin query
Only those whose name has these words. At most 100 characters.
actor_idintegerrequiredin path
The profile's id.

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
the installation is in preview and the viewer is not signed in
403
the viewer may not see whom it follows
404
there is no such profile

Request

curl "https://api.example.org/socialgraph/<actor_id>/leaders/"

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

import requests

response = requests.get(
    "https://api.example.org/socialgraph/<actor_id>/leaders/",
)
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/"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Followers in common

GET/socialgraph/{actor_id}/mutuals/

The people the viewer follows who also follow the profile.

Who: Somebody signed in

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
orderingstringin query
What they are ordered by. At most 15 characters. One of created_at, updated_at. updated_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
qstringin query
Only those whose name has these words. At most 100 characters.
actor_idintegerrequiredin path
The profile's id.

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 its followers
404
there is no such profile

Request

curl "https://api.example.org/socialgraph/<actor_id>/mutuals/" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

response = requests.get(
    "https://api.example.org/socialgraph/<actor_id>/mutuals/",
    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/"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Block somebody

POST/socialgraph/{target_id}/blocks/{source_id}

source_id blocks target_id: the viewer, or a group or an event they look after (permissions.md, what a block hides). Answers with whoever is blocked.

Who: Somebody signed in

Parameters

target_idintegerrequiredin path
The id of the profile followed, asked or blocked.
source_idintegerrequiredin path
The id of whoever follows, asks or blocks: the viewer, or a group they run.

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 make this block, or there is one either way already
404
there is no such profile

Request

curl -X POST "https://api.example.org/socialgraph/<target_id>/blocks/<source_id>" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

response = requests.post(
    "https://api.example.org/socialgraph/<target_id>/blocks/<source_id>",
    headers={"Authorization": f"Bearer {token}"},
)
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/"
}

Unblock somebody

DELETE/socialgraph/{target_id}/blocks/{source_id}

Answers with whoever was blocked.

Who: Somebody signed in

Parameters

target_idintegerrequiredin path
The id of the profile followed, asked or blocked.
source_idintegerrequiredin path
The id of whoever follows, asks or blocks: the viewer, or a group they run.

Answers

200
OK
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 lift this block
404
there is no such profile

Request

curl -X DELETE "https://api.example.org/socialgraph/<target_id>/blocks/<source_id>" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

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

Answer · 200

{
  "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/"
}

Ask to follow a profile

POST/socialgraph/{target_id}/follow-requests/{source_id}

For a profile that lets people ask. Answers with what a stranger is shown of it.

Who: Somebody signed in

Parameters

target_idintegerrequiredin path
The id of the profile followed, asked or blocked.
source_idintegerrequiredin path
The id of whoever follows, asks or blocks: the viewer, or a group they run.

Answers

201
Created
LimitedActor 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 ask: the profile does not let people ask, or has blocked them
404
there is no such profile
409
rules_not_agreed: it is a group or an event with rules the viewer has not agreed to; tick each and agree (POST /groups|events/:id/rules/agree), then ask again
Refusal application/json

Request

curl -X POST "https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 201

{
  "alias": "string",
  "allow_follow_request": false,
  "avatar_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "body": "string",
  "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"
  },
  "id": 42,
  "is_follow_requested_by_viewer": false,
  "is_invited": false,
  "name": "string",
  "restricted": false,
  "type": "string",
  "verified": false,
  "via_host": false
}

Let somebody who asked follow

PATCH/socialgraph/{target_id}/follow-requests/{source_id}

The request becomes a follow. Answers with the profile followed.

Who: Somebody signed in

Parameters

target_idintegerrequiredin path
The id of the profile followed, asked or blocked.
source_idintegerrequiredin path
The id of whoever follows, asks or blocks: the viewer, or a group they run.

Answers

200
OK
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 does not look after the profile
404
there is no such profile or request

Request

curl -X PATCH "https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "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/"
}

Withdraw a request, or turn one down

DELETE/socialgraph/{target_id}/follow-requests/{source_id}

By whoever asked, who is answered with what a stranger is shown of the profile; or by whoever looks after the profile, answered with it.

Who: Somebody signed in

Parameters

target_idintegerrequiredin path
The id of the profile followed, asked or blocked.
source_idintegerrequiredin path
The id of whoever follows, asks or blocks: the viewer, or a group they run.

Answers

200
OK
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 profile or request

Request

curl -X DELETE "https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/socialgraph/<target_id>/follow-requests/<source_id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "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/"
}

Follow a profile

POST/socialgraph/{target_id}/followers/{source_id}

source_id follows target_id: the viewer, or a follower a profile's administrator adds. Answers with the profile followed. To a profile that is not open to the viewer, ask instead (POST .../follow-requests/...).

Who: Somebody signed in

Parameters

target_idintegerrequiredin path
The id of the profile followed, asked or blocked.
source_idintegerrequiredin path
The id of whoever follows, asks or blocks: the viewer, or a group they run.

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 make this follow
404
there is no such profile
409
rules_not_agreed: it is a group or an event with rules the viewer has not agreed to; tick each and agree (POST /groups|events/:id/rules/agree), then ask again
Refusal application/json

Request

curl -X POST "https://api.example.org/socialgraph/<target_id>/followers/<source_id>" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

response = requests.post(
    "https://api.example.org/socialgraph/<target_id>/followers/<source_id>",
    headers={"Authorization": f"Bearer {token}"},
)
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/"
}

Stop following, or remove a follower

DELETE/socialgraph/{target_id}/followers/{source_id}

By the follower, or by whoever looks after the profile followed. Answers with the profile.

Who: Somebody signed in

Parameters

target_idintegerrequiredin path
The id of the profile followed, asked or blocked.
source_idintegerrequiredin path
The id of whoever follows, asks or blocks: the viewer, or a group they run.

Answers

200
OK
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 end this follow
404
there is no such profile

Request

curl -X DELETE "https://api.example.org/socialgraph/<target_id>/followers/<source_id>" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

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

Answer · 200

{
  "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/"
}

The viewer's invitations

GET/socialgraph/invites/

To follow a group or an event.

Who: Somebody signed in

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. 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
401
no token, or one that has expired

Request

curl "https://api.example.org/socialgraph/invites/" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

response = requests.get(
    "https://api.example.org/socialgraph/invites/",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "actor": null,
      "created_at": "2026-10-27T09:30:00Z",
      "ends_at": "2026-10-27T09:30:00Z",
      "inviter": null,
      "person": null
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Written by Claude, reviewed by Rastin Mehr · About this