Posts

Notes, articles and topics

text-service

Posts of words: notes (short, and every reply), articles and topics; threads of replies; quotes; and the posts a person saves.

One article

GET/articles/{id}

A reply is read by whoever may read the post at the top of its thread.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 post
410
a reply that was removed

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change a article's words

PATCH/articles/{id}

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

contentstringrequired
Its words, as Markdown. At most 8000 characters.
languagestring
The language it is written in, as a BCP 47 tag: "en", "fr-CA". Chosen by the author; left out, the post has none. See package language. At most 12 characters.
titlestringrequired
Its title. At most 100 characters.

Answers

200
OK
MediumNode application/json
400
language_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post

Request

curl -X PATCH "https://api.example.org/articles/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "content=string" \
  --data-urlencode "language=en" \
  --data-urlencode "title=string"

const form = new URLSearchParams();
form.append('content', "string");
form.append('language', "en");
form.append('title', "string");
const response = await fetch('https://api.example.org/articles/<id>', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/articles/<id>",
    headers={"Authorization": f"Bearer {token}"},
    data={"content": "string", "language": "en", "title": "string"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Delete a article

DELETE/articles/{id}

A reply that others have answered is emptied and kept, so the thread holds together.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
it is gone
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 post

Request

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

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

import requests

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

Change who may see it

PATCH/articles/{id}/access

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

accessstring
Who may see it: public, registered, followers, leaders, mutuals, admins or myself (permissions.md). The widest an installation allows when left out. One of public, registered, followers, leaders, mutuals, admins, myself. public unless given.

Answers

200
OK
MediumNode 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 post
422
access_not_allowed, with the audiences it may have; or reply_follows_its_thread: a reply has no setting of its own; its thread decides, without them
AudienceRefusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Open or close replies

PATCH/articles/{id}/comment-status

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

statusboolean
Whether it takes replies.

Answers

200
OK
MediumNode 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 post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/articles/<id>/comment-status" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "status=false"

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

import requests

response = requests.patch(
    "https://api.example.org/articles/<id>/comment-status",
    headers={"Authorization": f"Bearer {token}"},
    data={"status": "false"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Pin it to the profile it is on

PUT/articles/{id}/pin

A profile has one pin: pinning another post moves it. For the profile and its administrators, and site administrators (permissions.md). Answers with the post.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 pin it
404
there is no such post
422
reply_cannot_be_pinned
Refusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Take its pin off

DELETE/articles/{id}/pin

A profile has one pin: pinning another post moves it. For the profile and its administrators, and site administrators (permissions.md). Answers with the post.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 pin it
404
there is no such post
422
reply_cannot_be_pinned
Refusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Publish a draft

POST/articles/{id}/publish

An article or a topic begun as a draft (draft when it was made) becomes a post from now: dated now, seen by whoever its audience says, and announced as a post made now. Its author's alone. access sets its audience; left out, the one it was saved with.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The draft's id.

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

accessstring
Who may see it once it is published. Left out, the audience it was saved with. One of public, registered, followers, leaders, mutuals, admins, myself.

Answers

200
OK
MediumNode 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 publish it
404
no such draft of theirs
409
it is published already

Request

curl -X POST "https://api.example.org/articles/<id>/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access": "public"
  }'

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change who may quote it

PATCH/articles/{id}/quote-policy

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

quote_policystringrequired
Who may quote it: anyone, followers or nobody. At most 16 characters.

Answers

200
OK
MediumNode application/json
400
quote_policy_invalid, or not well formed
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/articles/<id>/quote-policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_policy": "string"
  }'

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

import requests

response = requests.patch(
    "https://api.example.org/articles/<id>/quote-policy",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "quote_policy": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change who may reply

PATCH/articles/{id}/reply-access

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

reply_accessstringrequired
Who may reply: anyone, nobody, or any of followers, following and mentioned joined by commas. At most 64 characters.

Answers

200
OK
MediumNode application/json
400
reply_access_invalid, or not well formed
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/articles/<id>/reply-access" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reply_access": "string"
  }'

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

import requests

response = requests.patch(
    "https://api.example.org/articles/<id>/reply-access",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "reply_access": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

A profile's articles

GET/articles/{owner_id}/

Those the viewer may see.

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 updated_at, created_at, enabled. created_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
disabledbooleanin query
Disabled posts as well, for whoever may see them.
owner_idintegerrequiredin path
The profile whose posts are listed. At least 1.
librarybooleanin query
The viewer's own media library instead: all their photo or video posts on their own profile, with those they put up from inside the article editor, which no other list holds. The owner is then the viewer, whatever the path says.
draftsbooleanin query
The viewer's own drafts on this profile instead, articles or topics still being written, which no other list holds.

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 profile

Request

curl "https://api.example.org/articles/<owner_id>/"

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

import requests

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

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "comment_count": 1,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "link_previews": [
        null
      ],
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent_id": 42,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "repost_count": 1,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "uri": "https://example.org/",
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Post a article

POST/articles/{owner_id}/

Who: Somebody signed in, with media:write

Parameters

owner_idintegerrequiredin path
The profile it is posted on.

Body application/json

draftboolean
Begun as a draft: an article or a topic, seen by its author alone until it is published (POST ///publish). Not read of anything else.
location_idslist of integer
The locations its author chose for it, tied to it as it is made, so that it goes to other servers with them: the first as its location, all as Places in its tag (roadmap row 82, part 3b). Up to five; what is not a location is passed over. At most 5 of them.
quote_policystring
Who may quote it: "anyone", "followers" or "nobody". Left out, the author's own setting applies. See constants.EffectiveQuotePolicy. At most 16 characters.
reply_accessstring
Who may reply: "anyone", "nobody", or any of "followers", "following" and "mentioned" joined by commas. Left out, anyone the profile lets. See constants.NormalizeReplyAccess. At most 64 characters.

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

accessstring
Who may see it, as for changing it. The widest the installation allows when left out. One of public, registered, followers, leaders, mutuals, admins, myself. public unless given.
contentstringrequired
Its words, as Markdown. At most 8000 characters.
draftboolean
Begun as a draft: an article or a topic, seen by its author alone until it is published (POST ///publish). Not read of anything else.
languagestring
The language it is written in, as a BCP 47 tag: "en", "fr-CA". Chosen by the author; left out, the post has none. See package language. At most 12 characters.
location_idslist of integer
The locations its author chose for it, tied to it as it is made, so that it goes to other servers with them: the first as its location, all as Places in its tag (roadmap row 82, part 3b). Up to five; what is not a location is passed over. At most 5 of them.
quote_policystring
Who may quote it: "anyone", "followers" or "nobody". Left out, the author's own setting applies. See constants.EffectiveQuotePolicy. At most 16 characters.
reply_accessstring
Who may reply: "anyone", "nobody", or any of "followers", "following" and "mentioned" joined by commas. Left out, anyone the profile lets. See constants.NormalizeReplyAccess. At most 64 characters.
titlestringrequired
Its title. At most 100 characters.

Answers

201
Created
MediumNode application/json
400
language_invalid, reply_access_invalid or quote_policy_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not post here
404
there is no such profile
422
access_not_allowed, with the audiences it may have
AudienceRefusal application/json

Request

curl -X POST "https://api.example.org/articles/<owner_id>/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "draft": false,
    "location_ids": [
      1
    ],
    "quote_policy": "string",
    "reply_access": "string"
  }'

const response = await fetch('https://api.example.org/articles/<owner_id>/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "draft": false,
    "location_ids": [
      1
    ],
    "quote_policy": "string",
    "reply_access": "string"
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/articles/<owner_id>/",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "draft": False,
      "location_ids": [
        1
      ],
      "quote_policy": "string",
      "reply_access": "string"
    },
)
answer = response.json()

Answer · 201

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

The viewer's saved posts

GET/bookmarks/

Of any kind, the most lately saved first.

Who: Somebody signed in

Parameters

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
401
no token, or one that has expired

Request

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

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

import requests

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

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "comment_count": 1,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "link_previews": [
        null
      ],
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent_id": 42,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "repost_count": 1,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "uri": "https://example.org/",
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Save a post

PUT/bookmarks/{id}

A post of any kind. Saving is the viewer's own: nobody is told.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
text.SavedAnswer 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
404
there is no such post that the viewer may see

Request

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

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

import requests

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

Answer · 200

{
  "id": 42,
  "is_saved_by_viewer": false
}

Unsave a post

DELETE/bookmarks/{id}

A post of any kind. Saving is the viewer's own: nobody is told.

Who: Somebody signed in

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
text.SavedAnswer 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
404
there is no such post that the viewer may see

Request

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

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

import requests

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

Answer · 200

{
  "id": 42,
  "is_saved_by_viewer": false
}

One note

GET/notes/{id}

A reply is read by whoever may read the post at the top of its thread.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 post
410
a reply that was removed

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change a note's words

PATCH/notes/{id}

A reply is changed by its author alone.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The note's id.

Body application/json

link_preview_removeboolean
The writer took the card off: the note is saved without one, though its link is still there.
link_preview_urlstring
As on NoteAddRequest. Left out, the note keeps the preview it has for as long as that link is still in it. At most 2000 characters.

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

contentstringrequired
Its words, as Markdown. At most 8000 characters.
languagestring
The language it is written in, as a BCP 47 tag: "en", "fr-CA". Chosen by the author; left out, the post has none. See package language. At most 12 characters.
link_preview_removeboolean
The writer took the card off: the note is saved without one, though its link is still there.
link_preview_urlstring
As on NoteAddRequest. Left out, the note keeps the preview it has for as long as that link is still in it. At most 2000 characters.

Answers

200
OK
MediumNode application/json
400
language_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
410
a reply that was removed

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Delete a note

DELETE/notes/{id}

A reply that others have answered is emptied and kept, so the thread holds together.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
it is gone
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 post

Request

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

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

import requests

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

Change who may see it

PATCH/notes/{id}/access

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

accessstring
Who may see it: public, registered, followers, leaders, mutuals, admins or myself (permissions.md). The widest an installation allows when left out. One of public, registered, followers, leaders, mutuals, admins, myself. public unless given.

Answers

200
OK
MediumNode 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 post
422
access_not_allowed, with the audiences it may have; or reply_follows_its_thread: a reply has no setting of its own; its thread decides, without them
AudienceRefusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

The posts that cite a post

GET/notes/{id}/cited_by

Newest first, those the viewer may see. Its author's own are listed too, though they are not counted in its citation_count.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post cited, of any kind.
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
401
the installation is in preview and the viewer is not signed in
404
there is no such post that the viewer may see

Request

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

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

import requests

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

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "comment_count": 1,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "link_previews": [
        null
      ],
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent_id": 42,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "repost_count": 1,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "uri": "https://example.org/",
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Open or close replies

PATCH/notes/{id}/comment-status

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

statusboolean
Whether it takes replies.

Answers

200
OK
MediumNode 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 post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/notes/<id>/comment-status" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "status=false"

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

import requests

response = requests.patch(
    "https://api.example.org/notes/<id>/comment-status",
    headers={"Authorization": f"Bearer {token}"},
    data={"status": "false"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Hide a reply, or show it again

PATCH/notes/{id}/hidden

From everybody but its writer and whoever looks after the thread, with everything said under it. It is not deleted, and its writer is not told. A reply from Bluesky is hidden there too, when the post went there (federation.md).

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The reply's id. Read by the handler from the path itself.

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

hiddenboolean
Hide it, or show it again.

Answers

200
OK
text.HiddenAnswer 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 thread
404
there is no such reply

Request

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

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

import requests

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

Answer · 200

{
  "hidden": false,
  "id": 42
}

Pin it to the profile it is on

PUT/notes/{id}/pin

A profile has one pin: pinning another post moves it. For the profile and its administrators, and site administrators (permissions.md). Answers with the post.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 pin it
404
there is no such post
422
reply_cannot_be_pinned
Refusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Take its pin off

DELETE/notes/{id}/pin

A profile has one pin: pinning another post moves it. For the profile and its administrators, and site administrators (permissions.md). Answers with the post.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 pin it
404
there is no such post
422
reply_cannot_be_pinned
Refusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Take one's post out of a quote

DELETE/notes/{id}/quote

For the author of the quoted post. The note stays, saying the post was removed by its author. It cannot be undone.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 the quoted post's author
404
there is no such note the viewer may see
422
not_a_quote
Refusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change who may quote it

PATCH/notes/{id}/quote-policy

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

quote_policystringrequired
Who may quote it: anyone, followers or nobody. At most 16 characters.

Answers

200
OK
MediumNode application/json
400
quote_policy_invalid, or not well formed
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/notes/<id>/quote-policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_policy": "string"
  }'

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

import requests

response = requests.patch(
    "https://api.example.org/notes/<id>/quote-policy",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "quote_policy": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

The notes that quote a post

GET/notes/{id}/quotes

Those the viewer may see.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post'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
404
there is no such post that the viewer may see

Request

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

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

import requests

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

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "allow_download": false,
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "citation_count": 1,
      "comment_count": 1,
      "comment_status": false,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "draft": false,
      "editor": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "enabled": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "library_only": false,
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "link_previews": [
        null
      ],
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent_id": 42,
      "pinned": false,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "quote_policy": "string",
      "reply_access": "string",
      "repost_count": 1,
      "root": {
        "access": null,
        "alias": null,
        "author": null,
        "authorized": null,
        "body": null,
        "content": null,
        "cover_urls": null,
        "created_at": null,
        "files": null,
        "id": null,
        "is_liked_by_viewer": null,
        "is_reposted_by_viewer": null,
        "is_saved_by_viewer": null,
        "link_preview": null,
        "name": null,
        "owner": null,
        "portrait_urls": null,
        "title": null,
        "type": null,
        "video": null
      },
      "root_id": 42,
      "title": "string",
      "type": "string",
      "updated_at": "2026-10-27T09:30:00Z",
      "uri": "https://example.org/",
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      },
      "view_count": 1
    }
  ]
}

Reply

POST/notes/{id}/replies

A note in the thread of the post or the reply id, owned by whoever writes it, seen by whoever may see the post at the top of the thread. Who may reply is that post's to say.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The id of the post or the reply it answers. Read by the handler from the path itself.

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

contentstringrequired
Its words, as Markdown. At most 8000 characters.
languagestring
The language it is written in, as a BCP 47 tag. At most 12 characters.
link_preview_urlstring
The link in it to show a card for, as on a note. See NoteAddRequest. At most 2000 characters.

Answers

201
Created
MediumNode application/json
400
language_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not reply here
404
there is no such post the viewer may see
410
it answers a reply that was removed

Request

curl -X POST "https://api.example.org/notes/<id>/replies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "string",
    "language": "en",
    "link_preview_url": "https://example.org/"
  }'

const response = await fetch('https://api.example.org/notes/<id>/replies', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "content": "string",
    "language": "en",
    "link_preview_url": "https://example.org/"
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/notes/<id>/replies",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "content": "string",
      "language": "en",
      "link_preview_url": "https://example.org/"
    },
)
answer = response.json()

Answer · 201

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Reply with a thread

POST/notes/{id}/replies/thread

Up to ten notes, made together in order, all or none: the first a reply to the post or the reply id, and each after it a reply to the one before. Each is checked as a reply is. They go to other networks in order, and whoever is told of the thread is told of its first note.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The id of the post or the reply it answers. Read by the handler from the path itself.

Body application/json

partslist of text.ThreadPartrequired
The notes of the thread, first to last: up to ten. At least 1 of them. At most 10 of them.

Answers

201
Created
text.ThreadAdded application/json
400
language_invalid; or not well formed, or more than ten notes, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not reply here
404
there is no such post the viewer may see
410
it answers a reply that was removed

Request

curl -X POST "https://api.example.org/notes/<id>/replies/thread" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {
        "content": "string",
        "language": "en",
        "link_preview_url": "https://example.org/"
      }
    ]
  }'

const response = await fetch('https://api.example.org/notes/<id>/replies/thread', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "parts": [
      {
        "content": "string",
        "language": "en",
        "link_preview_url": "https://example.org/"
      }
    ]
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/notes/<id>/replies/thread",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "parts": [
        {
          "content": "string",
          "language": "en",
          "link_preview_url": "https://example.org/"
        }
      ]
    },
)
answer = response.json()

Answer · 201

{
  "parts": [
    {
      "access": "string",
      "alias": "string",
      "allow_download": false,
      "author": null,
      "authorized": null,
      "citation_count": 1,
      "comment_count": 1,
      "comment_status": false,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "draft": false,
      "editor": null,
      "enabled": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "library_only": false,
      "likes_count": 1,
      "link_preview": null,
      "link_previews": [
        null
      ],
      "media_removed": null,
      "mimetype": "string",
      "origin_domain": "string",
      "owner": null,
      "parent_id": 42,
      "pinned": false,
      "portrait_urls": {
        "key": null
      },
      "quote": null,
      "quote_count": 1,
      "quote_id": 42,
      "quote_policy": "string",
      "reply_access": "string",
      "repost_count": 1,
      "root": null,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "updated_at": "2026-10-27T09:30:00Z",
      "uri": "https://example.org/",
      "video": null,
      "view_count": 1
    }
  ]
}

Change who may reply

PATCH/notes/{id}/reply-access

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

reply_accessstringrequired
Who may reply: anyone, nobody, or any of followers, following and mentioned joined by commas. At most 64 characters.

Answers

200
OK
MediumNode application/json
400
reply_access_invalid, or not well formed
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/notes/<id>/reply-access" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reply_access": "string"
  }'

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

import requests

response = requests.patch(
    "https://api.example.org/notes/<id>/reply-access",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "reply_access": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

The replies under a post

GET/notes/{id}/thread

Of a post of any kind, as the viewer may see them, with whether they may reply. On an installation in preview, only for somebody signed in.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
text.Thread 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 the post
404
there is no such post
409
it is a reply: its thread is the one of root_id
text.NotARoot application/json

Request

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

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

import requests

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

Answer · 200

{
  "can_reply": false,
  "data": [
    {
      "access": "string",
      "alias": "string",
      "allow_download": false,
      "author": null,
      "authorized": null,
      "citation_count": 1,
      "comment_count": 1,
      "comment_status": false,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "draft": false,
      "editor": null,
      "enabled": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "library_only": false,
      "likes_count": 1,
      "link_preview": null,
      "link_previews": [
        null
      ],
      "media_removed": null,
      "mimetype": "string",
      "origin_domain": "string",
      "owner": null,
      "parent_id": 42,
      "pinned": false,
      "portrait_urls": {
        "key": null
      },
      "quote": null,
      "quote_count": 1,
      "quote_id": 42,
      "quote_policy": "string",
      "reply_access": "string",
      "repost_count": 1,
      "root": null,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "updated_at": "2026-10-27T09:30:00Z",
      "uri": "https://example.org/",
      "video": null,
      "view_count": 1
    }
  ],
  "hidden_count": 1,
  "reply_access": "string",
  "truncated": false
}

Post a thread

POST/notes/{id}/thread

Up to ten notes, made together in order, all or none: the first a post on the profile owner_id, with what a post takes, and each after it a reply to the one before, written by the viewer. Each is checked as a note is. They go to other networks in order, and whoever is told of the thread is told of its first note.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
Here, the owner_id. The profile it is posted on.

Body application/json

accessstring
As on NoteAddRequest, for the first part: the rest are replies, seen by whoever may see it. One of public, registered, followers, leaders, mutuals, admins, myself.
location_idslist of integer
At most 5 of them.
partslist of text.ThreadPartrequired
The notes of the thread, first to last: up to ten. At least 1 of them. At most 10 of them.
quote_idinteger
quote_policystring
At most 16 characters.
reply_accessstring
At most 64 characters.

Answers

201
Created
text.ThreadAdded application/json
400
language_invalid, reply_access_invalid, quote_policy_invalid; or not well formed, or more than ten notes, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not post here
404
there is no such profile
422
access_not_allowed, with the audiences it may have
AudienceRefusal application/json

Request

curl -X POST "https://api.example.org/notes/<id>/thread" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access": "public",
    "location_ids": [
      1
    ],
    "parts": [
      {
        "content": "string",
        "language": "en",
        "link_preview_url": "https://example.org/"
      }
    ],
    "quote_id": 42,
    "quote_policy": "string",
    "reply_access": "string"
  }'

const response = await fetch('https://api.example.org/notes/<id>/thread', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "access": "public",
    "location_ids": [
      1
    ],
    "parts": [
      {
        "content": "string",
        "language": "en",
        "link_preview_url": "https://example.org/"
      }
    ],
    "quote_id": 42,
    "quote_policy": "string",
    "reply_access": "string"
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/notes/<id>/thread",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "access": "public",
      "location_ids": [
        1
      ],
      "parts": [
        {
          "content": "string",
          "language": "en",
          "link_preview_url": "https://example.org/"
        }
      ],
      "quote_id": 42,
      "quote_policy": "string",
      "reply_access": "string"
    },
)
answer = response.json()

Answer · 201

{
  "parts": [
    {
      "access": "string",
      "alias": "string",
      "allow_download": false,
      "author": null,
      "authorized": null,
      "citation_count": 1,
      "comment_count": 1,
      "comment_status": false,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "draft": false,
      "editor": null,
      "enabled": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "library_only": false,
      "likes_count": 1,
      "link_preview": null,
      "link_previews": [
        null
      ],
      "media_removed": null,
      "mimetype": "string",
      "origin_domain": "string",
      "owner": null,
      "parent_id": 42,
      "pinned": false,
      "portrait_urls": {
        "key": null
      },
      "quote": null,
      "quote_count": 1,
      "quote_id": 42,
      "quote_policy": "string",
      "reply_access": "string",
      "repost_count": 1,
      "root": null,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "updated_at": "2026-10-27T09:30:00Z",
      "uri": "https://example.org/",
      "video": null,
      "view_count": 1
    }
  ]
}

A profile's notes

GET/notes/{owner_id}/

Those the viewer may see.

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 updated_at, created_at, enabled. created_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
disabledbooleanin query
Disabled posts as well, for whoever may see them.
owner_idintegerrequiredin path
The profile whose posts are listed. At least 1.
librarybooleanin query
The viewer's own media library instead: all their photo or video posts on their own profile, with those they put up from inside the article editor, which no other list holds. The owner is then the viewer, whatever the path says.
draftsbooleanin query
The viewer's own drafts on this profile instead, articles or topics still being written, which no other list holds.

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 profile

Request

curl "https://api.example.org/notes/<owner_id>/"

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

import requests

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

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "comment_count": 1,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "link_previews": [
        null
      ],
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent_id": 42,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "repost_count": 1,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "uri": "https://example.org/",
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Post a note

POST/notes/{owner_id}/

With quote_id, a quote: the post is carried under the note's words, as its author's quote policy lets. With link_preview_url, the card of a link the writer was shown; what the card says is what this installation read, never what is sent.

Who: Somebody signed in, with media:write

Parameters

owner_idintegerrequiredin path
The profile it is posted on.

Body application/json

link_preview_urlstring
The link whose preview the note carries: one its writer was shown a preview of while writing. Only the address is taken. What the card says is what this installation read off the page, and never what is sent here. At most 2000 characters.
location_idslist of integer
The locations its author chose for it, tied to it as it is made, so that it goes to other servers with them: the first as its location, all as Places in its tag (roadmap row 82, part 3b). Up to five; what is not a location is passed over. At most 5 of them.
quote_idinteger
The post this note quotes: it is carried under the note's own words. Checked against that post's policy. See permissions.CanQuote.
quote_policystring
As on requests.MediumAddRequest. At most 16 characters.
reply_accessstring
As on requests.MediumAddRequest. At most 64 characters.

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

accessstring
Who may see it (permissions.md). The widest the installation allows when left out. One of public, registered, followers, leaders, mutuals, admins, myself. public unless given.
contentstringrequired
Its words, as Markdown. At most 8000 characters.
languagestring
The language it is written in, as a BCP 47 tag: "en", "fr-CA". Chosen by the author; left out, the post has none. See package language. At most 12 characters.
link_preview_urlstring
The link whose preview the note carries: one its writer was shown a preview of while writing. Only the address is taken. What the card says is what this installation read off the page, and never what is sent here. At most 2000 characters.
location_idslist of integer
The locations its author chose for it, tied to it as it is made, so that it goes to other servers with them: the first as its location, all as Places in its tag (roadmap row 82, part 3b). Up to five; what is not a location is passed over. At most 5 of them.
quote_idinteger
The post this note quotes: it is carried under the note's own words. Checked against that post's policy. See permissions.CanQuote.
quote_policystring
As on requests.MediumAddRequest. At most 16 characters.
reply_accessstring
As on requests.MediumAddRequest. At most 64 characters.

Answers

201
Created
MediumNode application/json
400
language_invalid, reply_access_invalid or quote_policy_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
quote_not_allowed, with reason: the post may not be quoted by the viewer; or, without a body: the viewer may not post here
Refusal application/json
404
there is no such profile
422
access_not_allowed, with the audiences it may have
AudienceRefusal application/json

Request

curl -X POST "https://api.example.org/notes/<owner_id>/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "link_preview_url": "https://example.org/",
    "location_ids": [
      1
    ],
    "quote_id": 42,
    "quote_policy": "string",
    "reply_access": "string"
  }'

const response = await fetch('https://api.example.org/notes/<owner_id>/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "link_preview_url": "https://example.org/",
    "location_ids": [
      1
    ],
    "quote_id": 42,
    "quote_policy": "string",
    "reply_access": "string"
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/notes/<owner_id>/",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "link_preview_url": "https://example.org/",
      "location_ids": [
        1
      ],
      "quote_id": 42,
      "quote_policy": "string",
      "reply_access": "string"
    },
)
answer = response.json()

Answer · 201

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

One topic

GET/topics/{id}

A reply is read by whoever may read the post at the top of its thread.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 post
410
a reply that was removed

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change a topic's words

PATCH/topics/{id}

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

contentstringrequired
Its words, as Markdown. At most 8000 characters.
languagestring
The language it is written in, as a BCP 47 tag: "en", "fr-CA". Chosen by the author; left out, the post has none. See package language. At most 12 characters.
titlestringrequired
Its title. At most 100 characters.

Answers

200
OK
MediumNode application/json
400
language_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post

Request

curl -X PATCH "https://api.example.org/topics/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "content=string" \
  --data-urlencode "language=en" \
  --data-urlencode "title=string"

const form = new URLSearchParams();
form.append('content', "string");
form.append('language', "en");
form.append('title', "string");
const response = await fetch('https://api.example.org/topics/<id>', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/topics/<id>",
    headers={"Authorization": f"Bearer {token}"},
    data={"content": "string", "language": "en", "title": "string"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Delete a topic

DELETE/topics/{id}

A reply that others have answered is emptied and kept, so the thread holds together.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
it is gone
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 post

Request

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

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

import requests

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

Change who may see it

PATCH/topics/{id}/access

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

accessstring
Who may see it: public, registered, followers, leaders, mutuals, admins or myself (permissions.md). The widest an installation allows when left out. One of public, registered, followers, leaders, mutuals, admins, myself. public unless given.

Answers

200
OK
MediumNode 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 post
422
access_not_allowed, with the audiences it may have; or reply_follows_its_thread: a reply has no setting of its own; its thread decides, without them
AudienceRefusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Open or close replies

PATCH/topics/{id}/comment-status

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

statusboolean
Whether it takes replies.

Answers

200
OK
MediumNode 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 post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/topics/<id>/comment-status" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "status=false"

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

import requests

response = requests.patch(
    "https://api.example.org/topics/<id>/comment-status",
    headers={"Authorization": f"Bearer {token}"},
    data={"status": "false"},
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Pin it to the profile it is on

PUT/topics/{id}/pin

A profile has one pin: pinning another post moves it. For the profile and its administrators, and site administrators (permissions.md). Answers with the post.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 pin it
404
there is no such post
422
reply_cannot_be_pinned
Refusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Take its pin off

DELETE/topics/{id}/pin

A profile has one pin: pinning another post moves it. For the profile and its administrators, and site administrators (permissions.md). Answers with the post.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

Answers

200
OK
MediumNode 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 pin it
404
there is no such post
422
reply_cannot_be_pinned
Refusal application/json

Request

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

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Publish a draft

POST/topics/{id}/publish

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The draft's id.

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

accessstring
Who may see it once it is published. Left out, the audience it was saved with. One of public, registered, followers, leaders, mutuals, admins, myself.

Answers

200
OK
MediumNode 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 publish it
404
no such draft of theirs
409
it is published already

Request

curl -X POST "https://api.example.org/topics/<id>/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access": "public"
  }'

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

import requests

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

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change who may quote it

PATCH/topics/{id}/quote-policy

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

quote_policystringrequired
Who may quote it: anyone, followers or nobody. At most 16 characters.

Answers

200
OK
MediumNode application/json
400
quote_policy_invalid, or not well formed
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/topics/<id>/quote-policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_policy": "string"
  }'

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

import requests

response = requests.patch(
    "https://api.example.org/topics/<id>/quote-policy",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "quote_policy": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Change who may reply

PATCH/topics/{id}/reply-access

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The post's id.

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

reply_accessstringrequired
Who may reply: anyone, nobody, or any of followers, following and mentioned joined by commas. At most 64 characters.

Answers

200
OK
MediumNode application/json
400
reply_access_invalid, or not well formed
Refusal application/json
401
no token, or one that has expired
403
the viewer may not change it
404
there is no such post
422
reply_follows_its_thread: a reply has no setting of its own; its thread decides
Refusal application/json

Request

curl -X PATCH "https://api.example.org/topics/<id>/reply-access" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reply_access": "string"
  }'

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

import requests

response = requests.patch(
    "https://api.example.org/topics/<id>/reply-access",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "reply_access": "string"
    },
)
answer = response.json()

Answer · 200

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

A profile's topics

GET/topics/{owner_id}/

Those the viewer may see.

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 updated_at, created_at, enabled. created_at unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
disabledbooleanin query
Disabled posts as well, for whoever may see them.
owner_idintegerrequiredin path
The profile whose posts are listed. At least 1.
librarybooleanin query
The viewer's own media library instead: all their photo or video posts on their own profile, with those they put up from inside the article editor, which no other list holds. The owner is then the viewer, whatever the path says.
draftsbooleanin query
The viewer's own drafts on this profile instead, articles or topics still being written, which no other list holds.

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 profile

Request

curl "https://api.example.org/topics/<owner_id>/"

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

import requests

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

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "comment_count": 1,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "deleted": false,
      "files": [
        null
      ],
      "hidden": false,
      "id": 42,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "link_previews": [
        null
      ],
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent_id": 42,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "repost_count": 1,
      "root_id": 42,
      "title": "string",
      "type": "string",
      "uri": "https://example.org/",
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Post a topic

POST/topics/{owner_id}/

Who: Somebody signed in, with media:write

Parameters

owner_idintegerrequiredin path
The profile it is posted on.

Body application/json

draftboolean
Begun as a draft: an article or a topic, seen by its author alone until it is published (POST ///publish). Not read of anything else.
location_idslist of integer
The locations its author chose for it, tied to it as it is made, so that it goes to other servers with them: the first as its location, all as Places in its tag (roadmap row 82, part 3b). Up to five; what is not a location is passed over. At most 5 of them.
quote_policystring
Who may quote it: "anyone", "followers" or "nobody". Left out, the author's own setting applies. See constants.EffectiveQuotePolicy. At most 16 characters.
reply_accessstring
Who may reply: "anyone", "nobody", or any of "followers", "following" and "mentioned" joined by commas. Left out, anyone the profile lets. See constants.NormalizeReplyAccess. At most 64 characters.

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

accessstring
Who may see it, as for changing it. The widest the installation allows when left out. One of public, registered, followers, leaders, mutuals, admins, myself. public unless given.
contentstringrequired
Its words, as Markdown. At most 8000 characters.
draftboolean
Begun as a draft: an article or a topic, seen by its author alone until it is published (POST ///publish). Not read of anything else.
languagestring
The language it is written in, as a BCP 47 tag: "en", "fr-CA". Chosen by the author; left out, the post has none. See package language. At most 12 characters.
location_idslist of integer
The locations its author chose for it, tied to it as it is made, so that it goes to other servers with them: the first as its location, all as Places in its tag (roadmap row 82, part 3b). Up to five; what is not a location is passed over. At most 5 of them.
quote_policystring
Who may quote it: "anyone", "followers" or "nobody". Left out, the author's own setting applies. See constants.EffectiveQuotePolicy. At most 16 characters.
reply_accessstring
Who may reply: "anyone", "nobody", or any of "followers", "following" and "mentioned" joined by commas. Left out, anyone the profile lets. See constants.NormalizeReplyAccess. At most 64 characters.
titlestringrequired
Its title. At most 100 characters.

Answers

201
Created
MediumNode application/json
400
language_invalid, reply_access_invalid or quote_policy_invalid; or not well formed, without a body
Refusal application/json
401
no token, or one that has expired
403
the viewer may not post here
404
there is no such profile
422
access_not_allowed, with the audiences it may have
AudienceRefusal application/json

Request

curl -X POST "https://api.example.org/topics/<owner_id>/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "draft": false,
    "location_ids": [
      1
    ],
    "quote_policy": "string",
    "reply_access": "string"
  }'

const response = await fetch('https://api.example.org/topics/<owner_id>/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "draft": false,
    "location_ids": [
      1
    ],
    "quote_policy": "string",
    "reply_access": "string"
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/topics/<owner_id>/",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "draft": False,
      "location_ids": [
        1
      ],
      "quote_policy": "string",
      "reply_access": "string"
    },
)
answer = response.json()

Answer · 201

{
  "access": "string",
  "alias": "string",
  "allow_download": false,
  "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
  },
  "citation_count": 1,
  "comment_count": 1,
  "comment_status": false,
  "content": "string",
  "cover_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "created_at": "2026-10-27T09:30:00Z",
  "deleted": false,
  "draft": false,
  "editor": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "id": 42,
    "name": "string",
    "type": "string"
  },
  "enabled": false,
  "files": [
    {
      "alt_text": "string",
      "height": 1,
      "id": "string",
      "position": 1,
      "urls": {
        "key": null
      },
      "width": 1
    }
  ],
  "hidden": false,
  "id": 42,
  "is_liked_by_viewer": false,
  "is_reposted_by_viewer": false,
  "is_saved_by_viewer": false,
  "is_subscribed_by_viewer": false,
  "language": "en",
  "library_only": false,
  "likes_count": 1,
  "link_preview": {
    "description": "string",
    "image": "string",
    "site_name": "string",
    "title": "string",
    "url": "https://example.org/"
  },
  "link_previews": [
    {
      "description": "string",
      "image": "string",
      "site_name": "string",
      "title": "string",
      "url": "https://example.org/"
    }
  ],
  "media_removed": {
    "alts": [
      "string"
    ],
    "count": 1,
    "gone": false
  },
  "mimetype": "string",
  "origin_domain": "string",
  "owner": {
    "alias": "string",
    "avatar_urls": {
      "key": null
    },
    "body": "string",
    "id": 42,
    "is_following_viewer": false,
    "is_leading_viewer": false,
    "name": "string",
    "type": "string"
  },
  "parent_id": 42,
  "pinned": false,
  "portrait_urls": {
    "key": {
      "size": null,
      "url": "https://example.org/"
    }
  },
  "quote": {
    "post": {
      "access": null,
      "alias": null,
      "author": null,
      "authorized": null,
      "body": null,
      "content": null,
      "cover_urls": null,
      "created_at": null,
      "files": null,
      "id": null,
      "is_liked_by_viewer": null,
      "is_reposted_by_viewer": null,
      "is_saved_by_viewer": null,
      "link_preview": null,
      "name": null,
      "owner": null,
      "portrait_urls": null,
      "title": null,
      "type": null,
      "video": null
    },
    "state": "string"
  },
  "quote_count": 1,
  "quote_id": 42,
  "quote_policy": "string",
  "reply_access": "string",
  "repost_count": 1,
  "root": {
    "access": "string",
    "alias": "string",
    "author": {
      "alias": null,
      "avatar_urls": null,
      "id": null,
      "name": null,
      "type": null
    },
    "authorized": {
      "add_follower": null,
      "administration": null,
      "audiences": null,
      "block_from_owner": null,
      "comment": null,
      "composers": null,
      "delete": null,
      "download": null,
      "edit": null,
      "hide": null,
      "invite": null,
      "like": null,
      "pin": null,
      "quote": null
    },
    "body": "string",
    "content": "string",
    "cover_urls": {
      "key": null
    },
    "created_at": "2026-10-27T09:30:00Z",
    "files": [
      null
    ],
    "id": 42,
    "is_liked_by_viewer": false,
    "is_reposted_by_viewer": false,
    "is_saved_by_viewer": false,
    "link_preview": {
      "description": null,
      "image": null,
      "site_name": null,
      "title": null,
      "url": null
    },
    "name": "string",
    "owner": {
      "alias": null,
      "avatar_urls": null,
      "body": null,
      "id": null,
      "is_following_viewer": null,
      "is_leading_viewer": null,
      "name": null,
      "type": null
    },
    "portrait_urls": {
      "key": null
    },
    "title": "string",
    "type": "string",
    "video": {
      "duration": null,
      "files": null,
      "height": null,
      "loop": null,
      "poster": null,
      "width": null
    }
  },
  "root_id": 42,
  "title": "string",
  "type": "string",
  "updated_at": "2026-10-27T09:30:00Z",
  "uri": "https://example.org/",
  "video": {
    "duration": 1.5,
    "files": [
      null
    ],
    "height": 1,
    "loop": false,
    "poster": "string",
    "width": 1
  },
  "view_count": 1
}

Written by Claude, reviewed by Rastin Mehr · About this