From 3628b6d43413369069690d88ab7455fc82793d8f Mon Sep 17 00:00:00 2001 From: trwnh Date: Sun, 20 Nov 2022 00:34:38 -0600 Subject: [PATCH] Update content for 4.0 (part 1) (#991) * add rules * join date on profiles * deprecate follow scope * deprecate identity proofs * familiar followers * use definition lists instead of tables for defining activitypub properties * reformat notifications page into markdown * fix broken links to publicKey header * Application website is now nullable * update environment variables added and removed * fix typo * fix heading level * min_id and max_id can be used at the same time (3.3) * fix typo * new tootctl options * reformat tootctl page to use definition lists for params * add rules and configuration to Instance * fix typo * refactor instance api page * 3.3.0 duration on mutes * 3.3.0 mute_expires_at * improve section headings * 3.4.0 resend email confirmation api * 3.4.0 policy on push subscriptions * 3.4.0 add details to account registration error * refactor accounts api page and start adding relrefs to entity pages * 3.4.0 accounts/lookup api * add see also to accounts methods * add more see-also links * 3.5.0 appeal mod decisions * 3.5.0 reformat reports and add category/rule_ids params * document report entity and missing responses * fix typos * fix relrefs and url schema, add aliases to old urls * add archetypes for new methods/entities * update archetypes with see-also stubs * clearer presentation of rate limits * announcements api methods * refactor apps methods * refactor bookmarks methods + some anchors * refactor conversations methods * custom_emojis methods refactor * anchors * refactor directory methods * refactor domain_blocks methods * add see also to emails methods * fix page relref shortcodes to specific methods + refactor endorsements methods * min_id max_id * refactor favourites methods * refactor featured_tags methods * refactor filters methods, make path params consistent, i18n required shortcode * follow_requests methods * lists methods * markers methods * forgot to add entity links * media methods, also fix formatting of some json errors * mutes methods, add more see-also links * oembed methods * preferences methods * proofs methods * push methods * suggestions methods * 3.5.0 add new trend types, fix formatting * refactor streaming methods * refactor oauth methods * note that streaming api casts payload to string * refactor search methods * refactor polls methods * remove unnecessary link * reformat scheduled_statuses methods * reformat timelines methods * reformat statuses methods * 3.5.0 editing statuses * consistent use of array brackets in form data parameters * update dev setup guide, add vagrant and clean up text * add admin/accounts methods * 3.6 role entity * admin/accounts methods v2 * minor fix * stub admin/reports methods * document admin reports * add 403 example to methods archetype * cleanup entities for admin reports and add new attrs * 3.6.0 domain allows methods + normalize admin entity namespace * fix search-and-replace error * add aliases for admin entities * 3.6.0 canonical email blocks entity * 3.5.0 admin/retention api * 3.5.0 add admin::ip doc * 3.5.0 admin/reports * 3.6.0 admin/domain_allows * 3.5.0 admin/dimensions * 3.6.0 permissions and roles * minor formatting fix * add anchor link to headings * checkpoint * add update commands to dev env setup guide * change mentions of v3.6 to v4.0 * tootctl now uses custom roles * fix formatting * v2 instance api * update frontmatter, add better titles to pages * minor wording change * consistency * add more aliases * add placeholders and WIP notices * explain link pagination and stub out todos * switch baseURL to https * 422 on reports with rules but category!=violation * document bug fixes * fix typo * remove duplicate API method definition * s/tootsuite/mastodon for github links * remove unnecessary escaping * s/tootsuite/mastodon in Entity archetype * add missing nullable shortcode * clarify oauth scope when requesting a user token * api/v2/media now synchronous for images * DISALLOW_UNAUTHENTICATED_API_ACCESS * add undocumented env variables * add instance domain blocks and extended description api * add SMTP_ENABLE_STARTTLS * add description to SMTP_ENABLE_STARTTLS * take suggestions from open PRs * normalize links and flavour language * Fully document streaming API based on source code * Add mention of MIME types * bump to ruby 3.0.4 * clarify how to check on async media processing * validation of replies_policy * remove TODOs on admin account action * EmailDomainBlocks * IpBlocks * Admin::DomainBlock * remove TODOs * following hashtags * followed_tags * remove reference to unused parameter * add new oauth scopes for admin blocks and allows * fix command signature for i18n-tasks normalize * reformat code structure page * document fixes for following tags (assume 4.0.3) * Add warning about pre-4.0 hardcoded roles * add note about case sensitivity * remove use of 'simply' from docs * remove reference to silencing * add reference to IDN normalization for verified links * add lang parameter --- .gitignore | 1 + archetypes/entities.md | 27 + archetypes/methods.md | 123 + assets/style.scss | 31 + config.toml | 7 +- content/en/_index.md | 14 +- content/en/admin/config.md | 766 +++--- content/en/admin/install.md | 12 +- content/en/admin/migrating.md | 22 +- content/en/admin/moderation.md | 18 +- content/en/admin/optional/elasticsearch.md | 2 +- content/en/admin/optional/sso.md | 2 + content/en/admin/prerequisites.md | 2 +- content/en/admin/scaling.md | 24 +- content/en/admin/setup.md | 6 +- content/en/admin/tootctl.md | 726 +++-- content/en/admin/troubleshooting.md | 2 +- .../admin/troubleshooting/index-corruption.md | 2 +- content/en/admin/upgrading.md | 4 +- content/en/api/guidelines.md | 134 + content/en/api/oauth-scopes.md | 68 +- content/en/api/rate-limits.md | 52 +- content/en/client/authorized.md | 70 +- content/en/client/guidelines.md | 54 - content/en/client/intro.md | 14 +- content/en/client/libraries.md | 10 +- content/en/client/public.md | 44 +- content/en/client/token.md | 16 +- content/en/dev/code.md | 73 +- content/en/dev/routes.md | 190 +- content/en/dev/setup.md | 96 +- content/en/entities/Account.md | 442 ++++ content/en/entities/Admin_Account.md | 213 ++ .../en/entities/Admin_CanonicalEmailBlock.md | 48 + content/en/entities/Admin_Cohort.md | 135 + content/en/entities/Admin_Dimension.md | 306 +++ content/en/entities/Admin_DomainAllow.md | 56 + content/en/entities/Admin_DomainBlock.md | 111 + content/en/entities/Admin_EmailDomainBlock.md | 121 + content/en/entities/Admin_Ip.md | 48 + content/en/entities/Admin_IpBlock.md | 83 + content/en/entities/Admin_Measure.md | 787 ++++++ content/en/entities/Admin_Report.md | 176 ++ content/en/entities/Announcement.md | 211 ++ content/en/entities/Application.md | 69 + .../en/entities/{context.md => Context.md} | 40 +- content/en/entities/Conversation.md | 78 + content/en/entities/CustomEmoji.md | 81 + content/en/entities/DomainBlock.md | 62 + content/en/entities/EncryptedMessage.md | 90 + content/en/entities/Error.md | 125 + content/en/entities/ExtendedDescription.md | 44 + content/en/entities/FamiliarFollowers.md | 64 + content/en/entities/FeaturedTag.md | 73 + content/en/entities/Filter.md | 108 + content/en/entities/FilterKeyword.md | 54 + content/en/entities/FilterResult.md | 66 + content/en/entities/FilterStatus.md | 46 + .../{identityproof.md => IdentityProof.md} | 55 +- content/en/entities/Instance.md | 493 ++++ content/en/entities/{list.md => List.md} | 26 +- content/en/entities/Marker.md | 53 + .../{attachment.md => MediaAttachment.md} | 102 +- .../{notification.md => Notification.md} | 158 +- content/en/entities/Poll.md | 142 + content/en/entities/Preferences.md | 78 + .../en/entities/{card.md => PreviewCard.md} | 82 +- content/en/entities/Reaction.md | 79 + .../{relationship.md => Relationship.md} | 116 +- content/en/entities/Report.md | 140 + content/en/entities/Role.md | 154 ++ content/en/entities/Rule.md | 50 + content/en/entities/ScheduledStatus.md | 108 + content/en/entities/{results.md => Search.md} | 64 +- content/en/entities/{status.md => Status.md} | 270 +- content/en/entities/StatusEdit.md | 111 + content/en/entities/StatusSource.md | 52 + content/en/entities/Suggestion.md | 57 + content/en/entities/Tag.md | 132 + content/en/entities/{token.md => Token.md} | 31 +- content/en/entities/V1_Filter.md | 92 + content/en/entities/V1_Instance.md | 422 +++ content/en/entities/WebPushSubscription.md | 148 ++ content/en/entities/account.md | 265 -- content/en/entities/activity.md | 55 - content/en/entities/admin-account.md | 130 - content/en/entities/admin-report.md | 84 - content/en/entities/announcement.md | 135 - content/en/entities/announcementReaction.md | 62 - content/en/entities/application.md | 67 - content/en/entities/conversation.md | 70 - content/en/entities/emoji.md | 68 - content/en/entities/error.md | 87 - content/en/entities/featuredtag.md | 61 - content/en/entities/field.md | 70 - content/en/entities/filter.md | 90 - content/en/entities/history.md | 48 - content/en/entities/instance.md | 179 -- content/en/entities/marker.md | 67 - content/en/entities/mention.md | 66 - content/en/entities/poll.md | 121 - content/en/entities/preferences.md | 71 - content/en/entities/pushsubscription.md | 79 - content/en/entities/report.md | 28 - content/en/entities/scheduledstatus.md | 102 - content/en/entities/source.md | 98 - content/en/entities/tag.md | 89 - content/en/methods/accounts.md | 2345 +++++++++-------- content/en/methods/accounts/blocks.md | 112 - content/en/methods/accounts/bookmarks.md | 53 - content/en/methods/accounts/domain_blocks.md | 229 -- content/en/methods/accounts/favourites.md | 223 -- content/en/methods/accounts/featured_tags.md | 295 --- content/en/methods/accounts/filters.md | 435 --- .../en/methods/accounts/follow_requests.md | 222 -- content/en/methods/accounts/mutes.md | 137 - content/en/methods/accounts/preferences.md | 62 - content/en/methods/accounts/reports.md | 60 - content/en/methods/accounts/suggestions.md | 211 -- content/en/methods/admin.md | 598 ----- content/en/methods/admin/_index.md | 10 + content/en/methods/admin/accounts.md | 1035 ++++++++ .../methods/admin/canonical_email_blocks.md | 238 ++ content/en/methods/admin/dimensions.md | 258 ++ content/en/methods/admin/domain_allows.md | 255 ++ content/en/methods/admin/domain_blocks.md | 368 +++ .../en/methods/admin/email_domain_blocks.md | 370 +++ content/en/methods/admin/ip_blocks.md | 338 +++ content/en/methods/admin/measures.md | 298 +++ content/en/methods/admin/reports.md | 532 ++++ content/en/methods/admin/retention.md | 173 ++ content/en/methods/admin/trends.md | 137 + content/en/methods/announcements.md | 310 ++- content/en/methods/apps.md | 131 +- content/en/methods/apps/oauth.md | 191 -- content/en/methods/blocks.md | 102 + content/en/methods/bookmarks.md | 108 + content/en/methods/conversations.md | 246 ++ .../methods/{instance => }/custom_emojis.md | 42 +- content/en/methods/directory.md | 78 + content/en/methods/domain_blocks.md | 213 ++ content/en/methods/emails.md | 67 + .../en/methods/{accounts => }/endorsements.md | 104 +- content/en/methods/favourites.md | 141 + content/en/methods/featured_tags.md | 312 +++ content/en/methods/filters.md | 540 ++++ content/en/methods/follow_requests.md | 232 ++ content/en/methods/followed_tags.md | 126 + content/en/methods/instance.md | 627 ++++- content/en/methods/instance/directory.md | 69 - content/en/methods/instance/trends.md | 81 - content/en/methods/lists.md | 580 ++++ content/en/methods/markers.md | 145 + content/en/methods/media.md | 496 ++++ content/en/methods/mutes.md | 103 + content/en/methods/notifications.md | 401 +-- content/en/methods/notifications/push.md | 257 -- content/en/methods/oauth.md | 203 ++ content/en/methods/oembed.md | 72 +- content/en/methods/polls.md | 228 ++ content/en/methods/preferences.md | 68 + content/en/methods/proofs.md | 72 +- content/en/methods/push.md | 331 +++ content/en/methods/reports.md | 155 ++ content/en/methods/scheduled_statuses.md | 296 +++ content/en/methods/search.md | 261 +- content/en/methods/statuses.md | 1700 +++++++----- content/en/methods/statuses/media.md | 397 --- content/en/methods/statuses/polls.md | 229 -- .../en/methods/statuses/scheduled_statuses.md | 307 --- content/en/methods/streaming.md | 716 +++++ content/en/methods/suggestions.md | 201 ++ content/en/methods/tags.md | 281 ++ content/en/methods/timelines.md | 500 ++-- content/en/methods/timelines/conversations.md | 248 -- content/en/methods/timelines/lists.md | 587 ----- content/en/methods/timelines/markers.md | 144 - content/en/methods/timelines/streaming.md | 91 - content/en/methods/trends.md | 218 ++ content/en/spec/activitypub.md | 266 +- content/en/spec/bearcaps.md | 4 +- content/en/spec/microformats.md | 14 +- content/en/spec/oauth.md | 14 +- content/en/spec/security.md | 14 +- content/en/spec/webfinger.md | 8 +- content/en/user/discoverability.md | 8 +- content/en/user/moderating.md | 4 +- content/en/user/moving.md | 4 +- content/en/user/network.md | 12 +- content/en/user/posting.md | 14 +- content/en/user/preferences.md | 2 +- content/en/user/profile.md | 19 +- content/en/user/run-your-own.md | 4 +- content/en/user/signup.md | 2 +- content/ja/_index.md | 8 +- content/ja/user/posting.md | 2 +- content/ja/user/run-your-own.md | 2 +- content/pl/_index.md | 12 +- content/pl/user/discoverability.md | 2 +- content/pl/user/moderating.md | 4 +- content/pl/user/posting.md | 12 +- content/pl/user/preferences.md | 2 +- content/pl/user/run-your-own.md | 2 +- content/zh-cn/_index.md | 10 +- content/zh-cn/admin/install.md | 4 +- content/zh-cn/admin/migrating.md | 2 +- content/zh-cn/admin/scaling.md | 8 +- content/zh-cn/admin/tootctl.md | 22 +- content/zh-cn/admin/upgrading.md | 4 +- content/zh-cn/user/network.md | 2 +- content/zh-cn/user/posting.md | 14 +- content/zh-cn/user/run-your-own.md | 2 +- i18n/en.toml | 3 + i18n/ja.toml | 3 + i18n/pl.toml | 3 + i18n/zh-cn.toml | 3 + layouts/_default/_markup/render-heading.html | 19 + layouts/_default/single.html | 2 +- layouts/index.html | 2 +- layouts/partials/footer.html | 2 +- layouts/shortcodes/nullable.html | 1 + layouts/shortcodes/optional.html | 1 + layouts/shortcodes/page-relref.html | 4 + layouts/shortcodes/required.html | 1 + .../shortcodes/translation-status-zh-cn.html | 2 +- 225 files changed, 22675 insertions(+), 11631 deletions(-) create mode 100644 archetypes/entities.md create mode 100644 archetypes/methods.md create mode 100644 content/en/api/guidelines.md delete mode 100644 content/en/client/guidelines.md create mode 100644 content/en/entities/Account.md create mode 100644 content/en/entities/Admin_Account.md create mode 100644 content/en/entities/Admin_CanonicalEmailBlock.md create mode 100644 content/en/entities/Admin_Cohort.md create mode 100644 content/en/entities/Admin_Dimension.md create mode 100644 content/en/entities/Admin_DomainAllow.md create mode 100644 content/en/entities/Admin_DomainBlock.md create mode 100644 content/en/entities/Admin_EmailDomainBlock.md create mode 100644 content/en/entities/Admin_Ip.md create mode 100644 content/en/entities/Admin_IpBlock.md create mode 100644 content/en/entities/Admin_Measure.md create mode 100644 content/en/entities/Admin_Report.md create mode 100644 content/en/entities/Announcement.md create mode 100644 content/en/entities/Application.md rename content/en/entities/{context.md => Context.md} (58%) create mode 100644 content/en/entities/Conversation.md create mode 100644 content/en/entities/CustomEmoji.md create mode 100644 content/en/entities/DomainBlock.md create mode 100644 content/en/entities/EncryptedMessage.md create mode 100644 content/en/entities/Error.md create mode 100644 content/en/entities/ExtendedDescription.md create mode 100644 content/en/entities/FamiliarFollowers.md create mode 100644 content/en/entities/FeaturedTag.md create mode 100644 content/en/entities/Filter.md create mode 100644 content/en/entities/FilterKeyword.md create mode 100644 content/en/entities/FilterResult.md create mode 100644 content/en/entities/FilterStatus.md rename content/en/entities/{identityproof.md => IdentityProof.md} (53%) create mode 100644 content/en/entities/Instance.md rename content/en/entities/{list.md => List.md} (52%) create mode 100644 content/en/entities/Marker.md rename content/en/entities/{attachment.md => MediaAttachment.md} (74%) rename content/en/entities/{notification.md => Notification.md} (55%) create mode 100644 content/en/entities/Poll.md create mode 100644 content/en/entities/Preferences.md rename content/en/entities/{card.md => PreviewCard.md} (78%) create mode 100644 content/en/entities/Reaction.md rename content/en/entities/{relationship.md => Relationship.md} (68%) create mode 100644 content/en/entities/Report.md create mode 100644 content/en/entities/Role.md create mode 100644 content/en/entities/Rule.md create mode 100644 content/en/entities/ScheduledStatus.md rename content/en/entities/{results.md => Search.md} (63%) rename content/en/entities/{status.md => Status.md} (52%) create mode 100644 content/en/entities/StatusEdit.md create mode 100644 content/en/entities/StatusSource.md create mode 100644 content/en/entities/Suggestion.md create mode 100644 content/en/entities/Tag.md rename content/en/entities/{token.md => Token.md} (61%) create mode 100644 content/en/entities/V1_Filter.md create mode 100644 content/en/entities/V1_Instance.md create mode 100644 content/en/entities/WebPushSubscription.md delete mode 100644 content/en/entities/account.md delete mode 100644 content/en/entities/activity.md delete mode 100644 content/en/entities/admin-account.md delete mode 100644 content/en/entities/admin-report.md delete mode 100644 content/en/entities/announcement.md delete mode 100644 content/en/entities/announcementReaction.md delete mode 100644 content/en/entities/application.md delete mode 100644 content/en/entities/conversation.md delete mode 100644 content/en/entities/emoji.md delete mode 100644 content/en/entities/error.md delete mode 100644 content/en/entities/featuredtag.md delete mode 100644 content/en/entities/field.md delete mode 100644 content/en/entities/filter.md delete mode 100644 content/en/entities/history.md delete mode 100644 content/en/entities/instance.md delete mode 100644 content/en/entities/marker.md delete mode 100644 content/en/entities/mention.md delete mode 100644 content/en/entities/poll.md delete mode 100644 content/en/entities/preferences.md delete mode 100644 content/en/entities/pushsubscription.md delete mode 100644 content/en/entities/report.md delete mode 100644 content/en/entities/scheduledstatus.md delete mode 100644 content/en/entities/source.md delete mode 100644 content/en/entities/tag.md delete mode 100644 content/en/methods/accounts/blocks.md delete mode 100644 content/en/methods/accounts/bookmarks.md delete mode 100644 content/en/methods/accounts/domain_blocks.md delete mode 100644 content/en/methods/accounts/favourites.md delete mode 100644 content/en/methods/accounts/featured_tags.md delete mode 100644 content/en/methods/accounts/filters.md delete mode 100644 content/en/methods/accounts/follow_requests.md delete mode 100644 content/en/methods/accounts/mutes.md delete mode 100644 content/en/methods/accounts/preferences.md delete mode 100644 content/en/methods/accounts/reports.md delete mode 100644 content/en/methods/accounts/suggestions.md delete mode 100644 content/en/methods/admin.md create mode 100644 content/en/methods/admin/_index.md create mode 100644 content/en/methods/admin/accounts.md create mode 100644 content/en/methods/admin/canonical_email_blocks.md create mode 100644 content/en/methods/admin/dimensions.md create mode 100644 content/en/methods/admin/domain_allows.md create mode 100644 content/en/methods/admin/domain_blocks.md create mode 100644 content/en/methods/admin/email_domain_blocks.md create mode 100644 content/en/methods/admin/ip_blocks.md create mode 100644 content/en/methods/admin/measures.md create mode 100644 content/en/methods/admin/reports.md create mode 100644 content/en/methods/admin/retention.md create mode 100644 content/en/methods/admin/trends.md delete mode 100644 content/en/methods/apps/oauth.md create mode 100644 content/en/methods/blocks.md create mode 100644 content/en/methods/bookmarks.md create mode 100644 content/en/methods/conversations.md rename content/en/methods/{instance => }/custom_emojis.md (72%) create mode 100644 content/en/methods/directory.md create mode 100644 content/en/methods/domain_blocks.md create mode 100644 content/en/methods/emails.md rename content/en/methods/{accounts => }/endorsements.md (58%) create mode 100644 content/en/methods/favourites.md create mode 100644 content/en/methods/featured_tags.md create mode 100644 content/en/methods/filters.md create mode 100644 content/en/methods/follow_requests.md create mode 100644 content/en/methods/followed_tags.md delete mode 100644 content/en/methods/instance/directory.md delete mode 100644 content/en/methods/instance/trends.md create mode 100644 content/en/methods/lists.md create mode 100644 content/en/methods/markers.md create mode 100644 content/en/methods/media.md create mode 100644 content/en/methods/mutes.md delete mode 100644 content/en/methods/notifications/push.md create mode 100644 content/en/methods/oauth.md create mode 100644 content/en/methods/polls.md create mode 100644 content/en/methods/preferences.md create mode 100644 content/en/methods/push.md create mode 100644 content/en/methods/reports.md create mode 100644 content/en/methods/scheduled_statuses.md delete mode 100644 content/en/methods/statuses/media.md delete mode 100644 content/en/methods/statuses/polls.md delete mode 100644 content/en/methods/statuses/scheduled_statuses.md create mode 100644 content/en/methods/streaming.md create mode 100644 content/en/methods/suggestions.md create mode 100644 content/en/methods/tags.md delete mode 100644 content/en/methods/timelines/conversations.md delete mode 100644 content/en/methods/timelines/lists.md delete mode 100644 content/en/methods/timelines/markers.md delete mode 100644 content/en/methods/timelines/streaming.md create mode 100644 content/en/methods/trends.md create mode 100644 layouts/_default/_markup/render-heading.html create mode 100644 layouts/shortcodes/nullable.html create mode 100644 layouts/shortcodes/optional.html create mode 100644 layouts/shortcodes/page-relref.html create mode 100644 layouts/shortcodes/required.html diff --git a/.gitignore b/.gitignore index 0d556621..b768be32 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ public/ static/.sass-cache resources/ +.hugo_build.lock diff --git a/archetypes/entities.md b/archetypes/entities.md new file mode 100644 index 00000000..f8774130 --- /dev/null +++ b/archetypes/entities.md @@ -0,0 +1,27 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +description: +menu: + docs: + parent: entities +--- + +## Example + +```json +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the SOMETHING in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +x.x.x - added + +## See also + +{{< page-relref ref="methods/SOMETHING#anchor" caption="POST /api/v1/something/" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/SOMETHING_serializer.rb" caption="app/serializers/rest/SOMETHING_serializer.rb" >}} \ No newline at end of file diff --git a/archetypes/methods.md b/archetypes/methods.md new file mode 100644 index 00000000..4fe161c4 --- /dev/null +++ b/archetypes/methods.md @@ -0,0 +1,123 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +description: +menu: + docs: + parent: methods +--- + +## What the method does {#anchor} + +```http +GET https://mastodon.example/api/v1/example HTTP/1.1 +``` + +**Returns:** [SOMETHING]({{< relref "entities/SOMETHING" >}})\ +**OAuth:** User token + `oauth:scope`\ +**Permissions:** Manage ???\ +**Version history:**\ +x.x.x - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the SOMETHING in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +**Internal parameter.** Use HTTP `Link` header for pagination. + +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 20. Max 40. + +##### Form data parameters + +#### Response +##### 200: OK + +```json +``` + +Because SOMETHING IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +SOMETHING is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 410: Gone + +##### 422: Unprocessable entity + +##### 429: Rate limited + +```json +{ + "error": "Too many requests" +} +``` + +##### 503: Service unavailable + +```json +{ + "error": "There was a temporary problem serving your request, please try again" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/SOMETHING#anchor" caption="POST /api/v1/something/" >}} + +{{< page-ref page="client/authorized" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/SOMETHING_controller.rb" caption="app/controllers/api/v1/SOMETHING_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/SOMETHING" caption="app/controllers/api/v1/SOMETHING/" >}} \ No newline at end of file diff --git a/assets/style.scss b/assets/style.scss index 4d3b98fc..460744ac 100644 --- a/assets/style.scss +++ b/assets/style.scss @@ -445,6 +445,26 @@ main { padding: 0; } + dl { + color: $lightest; + font-size: 16px; + line-height: 28px; + font-weight: normal; + margin-bottom: 26px; + hyphens: auto; + dt { + font-weight: 700; + background: lighten($darkest, 8%); + padding: 2px 16px; + max-width: max-content; + margin-bottom: 4px; + } + dd { + margin-left: 16px; + margin-bottom: 16px; + } + } + .mastodon-embed, iframe { width: 100%; @@ -810,3 +830,14 @@ main { padding: 20px; } } + +.heading { + display: flex; + align-items: center; + + &__anchor-link { + display: inline-flex; + align-content: center; + margin-left: 0.25em; + } +} \ No newline at end of file diff --git a/config.toml b/config.toml index a3487173..63150176 100644 --- a/config.toml +++ b/config.toml @@ -1,4 +1,4 @@ -baseURL = "http://docs.joinmastodon.org/" +baseURL = "https://docs.joinmastodon.org/" languageCode = "en-us" defaultContentLanguage = "en" title = "Mastodon documentation" @@ -7,12 +7,15 @@ pygmentsStyle = "dracula" metaDataFormat = "yaml" paginate = 100 enableGitInfo = true +disablePathToLower = true [markup] [markup.tableOfContents] - endLevel = 2 + endLevel = 3 ordered = false startLevel = 1 + [markup.goldmark.renderer] + unsafe = true [languages.en.menu] [[languages.en.menu.docs]] diff --git a/content/en/_index.md b/content/en/_index.md index 7491ae23..f91a5847 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -30,7 +30,7 @@ A Mastodon website can operate alone. Just like a traditional website, people si Mastodon uses a standardized, open protocol to implement federation. It is called **ActivityPub**. Any software that likewise implements federation via ActivityPub can seamlessly communicate with Mastodon, just like Mastodon websites communicate with one another. -The **fediverse** \(“federated universe”\) is the name for all websites that can communicate with each other over ActivityPub and the World Wide Web. That includes all Mastodon servers, but also other implementations: +The **fediverse** (“federated universe”) is the name for all websites that can communicate with each other over ActivityPub and the World Wide Web. That includes all Mastodon servers, but also other implementations: * Pleroma, a modular microblogging engine, * Pixelfed, federated image sharing platform, which lets you share and consume media posts, @@ -45,13 +45,13 @@ The fediverse does not have its own brand, so you might more often hear “follo ### Choice of service provider and policy {#choice} -Because Mastodon is simply software that can be used to power any website, potential users of Mastodon have the option of choosing a service provider from already-existing Mastodon websites, or to create their own Mastodon website if they wish. The Mastodon project maintains a list of recommended service providers at [joinmastodon.org](https://joinmastodon.org), sortable by category and/or language. Some websites may have moderation policies that go beyond this, such as requiring the use of certain tags on potentially sensitive content, and some websites may have more relaxed moderation policies, but websites listed in the picker all agree to adopt the [Mastodon Server Covenant](https://joinmastodon.org/covenant), meaning that they pledge to actively moderate against hate speech, to take daily backups, to have at least one emergency admin, and to provide at least 3 months advance notice in case of shutdown. +Because Mastodon is just software that can be used to power any website, potential users of Mastodon have the option of choosing a service provider from already-existing Mastodon websites, or to create their own Mastodon website if they wish. The Mastodon project maintains a list of recommended service providers at [joinmastodon.org](https://joinmastodon.org), sortable by category and/or language. Some websites may have moderation policies that go beyond this, such as requiring the use of certain tags on potentially sensitive content, and some websites may have more relaxed moderation policies, but websites listed in the picker all agree to adopt the [Mastodon Server Covenant](https://joinmastodon.org/covenant), meaning that they pledge to actively moderate against hate speech, to take daily backups, to have at least one emergency admin, and to provide at least 3 months advance notice in case of shutdown. > Maintaining communities that feel safe for all of its members is not easy. Mastodon provides a lot of foundational framework and tools for doing it, and shifts the power to effect change from one commercial entity to the communities themselves. > > -- Eugen Rochko, Jul 6 2018, ["Cage the Mastodon"](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/) -> A centralized social media platform has a hierarchical structure where rules and their enforcement, as well as the development and direction of the platform, are decided by the CEO \[...\] A decentralized network deliberately relinquishes control of the platform owner, by essentially not having one. +> A centralized social media platform has a hierarchical structure where rules and their enforcement, as well as the development and direction of the platform, are decided by the CEO [...] A decentralized network deliberately relinquishes control of the platform owner, by essentially not having one. > > -- Eugen Rochko, Dec 30 2018, ["Why does decentralization matter?"](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/) @@ -91,19 +91,19 @@ Unlike proprietary services, **anyone has the complete freedom to run, examine, Learn how to use Mastodon: -{{< page-ref page="user/signup.md" >}} +{{< page-ref page="user/signup" >}} Learn how to install Mastodon: -{{< page-ref page="admin/prerequisites.md" >}} +{{< page-ref page="admin/prerequisites" >}} Learn how to write an app for Mastodon: -{{< page-ref page="client/intro.md" >}} +{{< page-ref page="client/intro" >}} Learn about the Mastodon backend and how to contribute: -{{< page-ref page="dev/overview.md" >}} +{{< page-ref page="dev/overview" >}} diff --git a/content/en/admin/config.md b/content/en/admin/config.md index 7a61ef39..0d0463b4 100644 --- a/content/en/admin/config.md +++ b/content/en/admin/config.md @@ -13,7 +13,7 @@ For convenience, it can read them from a flat file called `.env.production` in t ## Basic {#basic} -### Federation {#federation} +### Federation and display {#federation} #### `LOCAL_DOMAIN` @@ -37,13 +37,17 @@ location /.well-known/webfinger { If you have multiple domains pointed at your Mastodon server, this setting will allow Mastodon to recognize itself when users are addressed using those other domains. Separate the domains by commas, e.g. `foo.com,bar.com` -#### `AUTHORIZED_FETCH` {#authorized_fetch} +#### `ALLOWED_PRIVATE_ADDRESSES` + +Comma-separated specific addresses/subnets allowed in outgoing HTTP queries. + +#### `AUTHORIZED_FETCH` Also called "secure mode". When set to `true`, the following changes occur: - Mastodon will stop generating linked-data signatures for public posts, which prevents them from being re-distributed efficiently but without precise control. Since a linked-data object with a signature is entirely self-contained, it can be passed around without making extra requests to the server where it originates. - Mastodon will require HTTP signature authentication on ActivityPub representations of public posts and profiles, which are normally available without any authentication. Profiles will only return barebones technical information when no authentication is supplied. -- Mastodon will require any REST/streaming API access to have a user context (i.e. having gone through an OAuth authorization screen with an active user), when normally some API endpoints are available without any authentication. +- Prior to v4.0.0: Mastodon will require any REST/streaming API access to have a user context (i.e. having gone through an OAuth authorization screen with an active user), when normally some API endpoints are available without any authentication. As a result, through the authentication mechanism and avoiding re-distribution mechanisms that do not have your server in the loop, it becomes possible to enforce who can and cannot retrieve even public content from your server, e.g. servers whose domains you have blocked. @@ -55,7 +59,7 @@ Unfortunately, secure mode is not without its drawbacks, which is why it is not Secure mode does not hide HTML representations of public posts and profiles. HTML is a more lossy format compared to first-class ActivityPub representations or the REST API but it is still a potential vector for scraping content. {{}} -#### `LIMITED_FEDERATION_MODE` {#limited_federation_mode} +#### `LIMITED_FEDERATION_MODE` When set to `true`, Mastodon will restrict federation to servers you have manually approved only, as well as disable all public pages and some REST APIs. Limited federation mode is based on secure mode (`AUTHORIZED_FETCH`). @@ -73,232 +77,14 @@ This mode is intended for private use only, such as in academic instituations or This setting was known as `WHITELIST_MODE` prior to 3.1.5. {{}} -### Secrets {#secrets} +#### `DISALLOW_UNAUTHENTICATED_API_ACCESS` -#### `SECRET_KEY_BASE` - -Generate with `rake secret`. Changing it will break all active browser sessions. - -#### `OTP_SECRET` - -Generate with `rake secret`. Changing it will break two-factor authentication. - -#### `VAPID_PRIVATE_KEY` - -Generate with `rake mastodon:webpush:generate_vapid_key`. Changing it will break push notifications. - -#### `VAPID_PUBLIC_KEY` - -Generate with `rake mastodon:webpush:generate_vapid_key`. Changing it will break push notifications. - -### Deployment {#deployment} - -#### `RAILS_ENV` - -Environment. Can be `production`, `development`, or `test`. If you are running Mastodon on your personal computer for development purposes, use `development`. That is also the default. If you are running Mastodon online, use `production`. Mastodon will load different configuration defaults based on the environment. - -{{< hint style="warning" >}} -This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. -{{}} - -#### `RAILS_SERVE_STATIC_FILES` - -If set to true, Mastodon will answer requests for files in its `public` directory. This may be necessary if the reverse proxy (e.g. nginx) has no file system access to the `public` directory itself, such as in a containerized environment. It is a suboptimal setting because serving static files directly from the file system will always be much faster than serving them through the Ruby on Rails process. - -#### `RAILS_LOG_LEVEL` - -Determines the amount of logs generated by Mastodon. Defaults to `info`, which generates a log entry about every request served by Mastodon and every background job processed by Mastodon. This can be useful but can get quite noisy and strain the I/O of your machine if there is a lot of traffic/activity. In that case, `warn` is recommended, which will only output information about things that are going wrong, and otherwise stay quiet. Possible values are `debug`, `info`, `warn`, `error`, `fatal` and `unknown`. - -#### `TRUSTED_PROXY_IP` - -If your Mastodon web process is on the same machine as your reverse proxy (e.g. nginx), then you don't need this setting. Otherwise, you need to set it to the IP from which your reverse proxy sends requests to Mastodon's web process, otherwise Mastodon will record the reverse proxy's own IP as the IP of all requests, which would be bad because IP addresses are used for important rate limits and security functions. - -#### `SOCKET` - -Instead of binding to an IP address like `127.0.0.1`, you may bind to a Unix socket. This variable is process-specific, e.g. you need different values for every process, and it works for both web (Puma) processes and streaming API (Node.js) processes. - -{{< hint style="warning" >}} -This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. -{{}} - -#### `PORT` - -If you are not using Unix sockets, this defines which port the process will listen on. This variable is process-specific, e.g. you need different values for every process, and it works for both web (Puma) processes and streaming API (Node.js) processes. By default, web listens on `3000` and streaming API on `4000`. - -{{< hint style="warning" >}} -This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. -{{}} - -#### `NODE_ENV` - -Equivalent to `RAILS_ENV`, but for the streaming API (Node.js). - -{{< hint style="warning" >}} -This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. -{{}} - -#### `BIND` - -If you are not using Unix sockets, this defines the IP to which the process will bind. Multiple processes can bind to the same IP as long as they listen on different ports. Defaults to `127.0.0.1`. - -{{< hint style="warning" >}} -This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. -{{}} - -### Scaling options {#scaling} - -{{< page-ref page="admin/scaling.md" >}} - -#### `WEB_CONCURRENCY` - -Specific to Puma, this variable determines how many different processes Puma forks into. Defaults to `2`. - -#### `MAX_THREADS` - -Specific to Puma, this variable determines how many threads each Puma process maintains. Defaults to `5`. - -#### `PREPARED_STATEMENTS` - -By default, Mastodon uses the prepared statements feature of PostgreSQL, which offers some performance advantages. This feature is not available if you are using a connection pool where connections are shared between transactions and must thus be set to `false`. When you are scaling up, the advantages of having a transaction-based connection pool outweigh those provided by prepared statements. - -#### `STREAMING_API_BASE_URL` - -The streaming API can be deployed to a different domain/subdomain. This may improve the performance of the streaming API as in the default configuration long-lived streaming API requests are proxied through nginx, while serving the streaming API from a different domain/subdomain would allow one to skip nginx entirely. - -Example value: `wss://streaming.example.com` - -#### `STREAMING_CLUSTER_NUM` - -Specific to the streaming API, this variable determines how many different processes the streaming API forks into. Defaults to the number of CPU cores minus one. - -## Database connections {#connections} - -### PostgreSQL {#postgresql} - -#### `DB_HOST` - -Defaults to `localhost`. - -#### `DB_USER` - -Defaults to `mastodon`. - -#### `DB_NAME` - -Defaults to `mastodon_production`. - -#### `DB_PASS` - -No default. - -#### `DB_PORT` - -Defaults to `5432`. - -#### `DB_POOL` - -How many database connections to pool in the process. This value should cover every thread in the process, for this reason, it defaults to the value of `MAX_THREADS`. - -#### `DB_SSLMODE` - -Postgres's [SSL mode](https://www.postgresql.org/docs/10/libpq-ssl.html). Defaults to `prefer`. - -#### `DATABASE_URL` - -If provided, takes precedence over `DB_HOST`, `DB_USER`, `DB_NAME`, `DB_PASS` and `DB_PORT`. - -Example value: `postgresql://user:password@localhost:5432` - -### Redis {#redis} - -{{< hint style="info" >}} -It is possible to use a separate Redis server for volatile cache. You may wish to do so if your Redis server starts getting overwhelmed. -{{}} - -#### `REDIS_HOST` - -Defaults to `localhost`. - -#### `REDIS_PORT` - -Defaults to `6379`. - -#### `REDIS_URL` - -If provided, takes precedence over `REDIS_HOST` and `REDIS_PORT`. - -Example value: `redis://user:password@localhost:6379` - -#### `REDIS_NAMESPACE` - -If provided, namespaces all Redis keys. This allows sharing the same Redis database between different projects or Mastodon servers. - -#### `CACHE_REDIS_HOST` - -Defaults to value of `REDIS_HOST`. - -#### `CACHE_REDIS_PORT` - -Defaults to value of `REDIS_PORT`. - -#### `CACHE_REDIS_URL` - -If provided, takes precedence over `CACHE_REDIS_HOST` and `CACHE_REDIS_PORT`. Defaults to value of `REDIS_URL`. - -#### `CACHE_REDIS_NAMESPACE` - -Defaults to value of `REDIS_NAMESPACE`. - -### ElasticSearch {#elasticsearch} - -{{< page-ref page="admin/optional/elasticsearch.md" >}} - -#### `ES_ENABLED` - -If set to `true`, Mastodon will use ElasticSearch for its search functions. - -#### `ES_HOST` - -Host of the ElasticSearch server. Defaults to `localhost` - -#### `ES_PORT` - -Port of the ElasticSearch server. Defaults to `9200` - -#### `ES_PREFIX` - -Useful if the ElasticSearch server is shared between multiple projects or different Mastodon servers. Defaults to value of `REDIS_NAMESPACE`. - -### StatsD {#statsd} - -#### `STATSD_ADDR` - -If set, Mastodon will log some events and metrics into a StatsD instance identified by its hostname and port. - -Example value: `localhost:8125` - -#### `STATSD_NAMESPACE` - -If set, all StatsD keys will be prefixed with this. Defaults to `Mastodon.production` when `RAILS_ENV` is `production`, `Mastodon.development` when it's `development`, etc. - -## Limits {#limits} +As of Mastodon v4.0.0, the web app is now used to render all requests, even for logged-out viewers. In order to make these views work, the web app makes public API requests in order to fetch accounts and statuses. If you would like to disallow this, then set this variable to `true`. Note that disallowing unauthenticated API access will cause profile and post permalinks to return an error to logged-out users, essentially making it so that the only ways to view content is to either log in locally or fetch it via ActivityPub. #### `SINGLE_USER_MODE` If set to `true`, the frontpage of your Mastodon server will always redirect to the first profile in the database and registrations will be disabled. -#### `EMAIL_DOMAIN_ALLOWLIST` - -If set, registrations will not be possible with any e-mails **except** those from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com` - -#### `EMAIL_DOMAIN_DENYLIST` - -If set, registrations will not be possible with any e-mails from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com` - -{{< hint style="warning" >}} -This option is deprecated. You can dynamically block e-mail domains from the admin interface or from the `tootctl` command-line interface. -{{}} - #### `DEFAULT_LOCALE` By default, Mastodon will automatically detect the visitor's language from browser headers and display the Mastodon interface in that language (if it's supported). If you are running a language-specific or regional server, that behaviour may mislead visitors who do not speak your language into signing up on your server. For this reason, you may want to set this variable to a specific language. @@ -377,41 +163,254 @@ Supported languages: - `zh-HK` - `zh-TW` -#### `MAX_SESSION_ACTIVATIONS` +### Secrets {#secrets} -How many browser sessions are allowed per-user. Defaults to `10`. If a new browser session is created, then the oldest session is deleted, e.g. user in that browser is logged out. +#### `SECRET_KEY_BASE` -#### `USER_ACTIVE_DAYS` +Generate with `rake secret`. Changing it will break all active browser sessions. -Mastodon stores home feeds in RAM (specifically, in the Redis database). This makes them very fast to access and update, but it also means that you don't want to keep them there if they're not used, and you don't want to spend resources on inserting new items into home feeds that will not be accessed. For this reason, Mastodon periodically clears out home feeds of users who haven't been online in a while, and if they re-appear, it regenerates those home feeds from database data. By default, users are considered active if they have been online in the past `7` days. +#### `OTP_SECRET` -Regeneration of home feeds is computationally expensive, if your Sidekiq is constantly doing it because your users come online every 3 days but your `USER_ACTIVE_DAYS` is set to 2, then consider adjusting it up. +Generate with `rake secret`. Changing it will break two-factor authentication. -{{< hint style="info" >}} -This setting has no relation to which users are considered active for the purposes of statistics, such as the Monthly Active Users number. +#### `VAPID_PRIVATE_KEY` + +Generate with `rake mastodon:webpush:generate_vapid_key`. Changing it will break push notifications. + +#### `VAPID_PUBLIC_KEY` + +Generate with `rake mastodon:webpush:generate_vapid_key`. Changing it will break push notifications. + +### Deployment {#deployment} + +#### `RAILS_ENV` + +Environment. Can be `production`, `development`, or `test`. If you are running Mastodon on your personal computer for development purposes, use `development`. That is also the default. If you are running Mastodon online, use `production`. Mastodon will load different configuration defaults based on the environment. + +{{< hint style="warning" >}} +This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. {{}} -#### `ALLOWED_PRIVATE_ADDRESSES` +#### `RAILS_SERVE_STATIC_FILES` -Comma-separated specific addresses/subnets allowed in outgoing HTTP queries. +If set to true, Mastodon will answer requests for files in its `public` directory. This may be necessary if the reverse proxy (e.g. nginx) has no file system access to the `public` directory itself, such as in a containerized environment. It is a suboptimal setting because serving static files directly from the file system will always be much faster than serving them through the Ruby on Rails process. -## E-mail {#email} +#### `RAILS_LOG_LEVEL` -* `SMTP_SERVER` -* `SMTP_PORT` -* `SMTP_LOGIN` -* `SMTP_PASSWORD` -* `SMTP_FROM_ADDRESS` -* `SMTP_DOMAIN` -* `SMTP_DELIVERY_METHOD` -* `SMTP_AUTH_METHOD` -* `SMTP_CA_FILE` -* `SMTP_OPENSSL_VERIFY_MODE` -* `SMTP_ENABLE_STARTTLS_AUTO` -* `SMTP_TLS` -* `SMTP_SSL` +Determines the amount of logs generated by Mastodon. Defaults to `info`, which generates a log entry about every request served by Mastodon and every background job processed by Mastodon. This can be useful but can get quite noisy and strain the I/O of your machine if there is a lot of traffic/activity. In that case, `warn` is recommended, which will only output information about things that are going wrong, and otherwise stay quiet. Possible values are `debug`, `info`, `warn`, `error`, `fatal` and `unknown`. -## File storage {#cdn} +#### `TRUSTED_PROXY_IP` + +If your Mastodon web process is on the same machine as your reverse proxy (e.g. nginx), then you don't need this setting. Otherwise, you need to set it to the IP from which your reverse proxy sends requests to Mastodon's web process, otherwise Mastodon will record the reverse proxy's own IP as the IP of all requests, which would be bad because IP addresses are used for important rate limits and security functions. + +#### `SOCKET` + +Instead of binding to an IP address like `127.0.0.1`, you may bind to a Unix socket. This variable is process-specific, e.g. you need different values for every process, and it works for both web (Puma) processes and streaming API (Node.js) processes. + +{{< hint style="warning" >}} +This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. +{{}} + +#### `PORT` + +If you are not using Unix sockets, this defines which port the process will listen on. This variable is process-specific, e.g. you need different values for every process, and it works for both web (Puma) processes and streaming API (Node.js) processes. By default, web listens on `3000` and streaming API on `4000`. + +{{< hint style="warning" >}} +This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. +{{}} + +#### `NODE_ENV` + +Equivalent to `RAILS_ENV`, but for the streaming API (Node.js). + +{{< hint style="warning" >}} +This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. +{{}} + +#### `BIND` + +If you are not using Unix sockets, this defines the IP to which the process will bind. Multiple processes can bind to the same IP as long as they listen on different ports. Defaults to `127.0.0.1`. + +{{< hint style="warning" >}} +This variable cannot be defined in dotenv (`.env`) files as it's used before they are loaded. +{{}} + +### Scaling options {#scaling} + +{{< page-ref page="admin/scaling" >}} + +#### `WEB_CONCURRENCY` + +Specific to Puma, this variable determines how many different processes Puma forks into. Defaults to `2`. + +#### `MAX_THREADS` + +Specific to Puma, this variable determines how many threads each Puma process maintains. Defaults to `5`. + +#### `PERSISTENT_TIMEOUT` + +Specific to Puma, this variable determines how long Puma should wait before closing a connection. Defaults to `20`. + +#### `PREPARED_STATEMENTS` + +By default, Mastodon uses the prepared statements feature of PostgreSQL, which offers some performance advantages. This feature is not available if you are using a connection pool where connections are shared between transactions and must thus be set to `false`. When you are scaling up, the advantages of having a transaction-based connection pool outweigh those provided by prepared statements. + +#### `STREAMING_API_BASE_URL` + +The streaming API can be deployed to a different domain/subdomain. This may improve the performance of the streaming API as in the default configuration long-lived streaming API requests are proxied through nginx, while serving the streaming API from a different domain/subdomain would allow one to skip nginx entirely. + +Example value: `wss://streaming.example.com` + +#### `STREAMING_CLUSTER_NUM` + +Specific to the streaming API, this variable determines how many different processes the streaming API forks into. Defaults to the number of CPU cores minus one. + +## Backend {#backend} + +### PostgreSQL {#postgresql} + +#### `DB_HOST` + +Defaults to `localhost`. + +#### `DB_USER` + +Defaults to `mastodon`. + +#### `DB_NAME` + +Defaults to `mastodon_production`. + +#### `DB_PASS` + +No default. + +#### `DB_PORT` + +Defaults to `5432`. + +#### `DB_POOL` + +How many database connections to pool in the process. This value should cover every thread in the process, for this reason, it defaults to the value of `MAX_THREADS`. + +#### `DB_SSLMODE` + +Postgres's [SSL mode](https://www.postgresql.org/docs/10/libpq-ssl.html). Defaults to `prefer`. + +#### `DATABASE_URL` + +If provided, takes precedence over `DB_HOST`, `DB_USER`, `DB_NAME`, `DB_PASS` and `DB_PORT`. + +Example value: `postgresql://user:password@localhost:5432` + +### Redis {#redis} + +{{< hint style="info" >}} +It is possible to use a separate Redis server for volatile cache. You may wish to do so if your Redis server starts getting overwhelmed. +{{}} + +#### `REDIS_HOST` + +Defaults to `localhost`. + +#### `REDIS_PORT` + +Defaults to `6379`. + +#### `REDIS_URL` + +If provided, takes precedence over `REDIS_HOST` and `REDIS_PORT`. + +Example value: `redis://user:password@localhost:6379` + +#### `REDIS_NAMESPACE` + +If provided, namespaces all Redis keys. This allows sharing the same Redis database between different projects or Mastodon servers. + +#### `CACHE_REDIS_HOST` + +Defaults to value of `REDIS_HOST`. + +#### `CACHE_REDIS_PORT` + +Defaults to value of `REDIS_PORT`. + +#### `CACHE_REDIS_URL` + +If provided, takes precedence over `CACHE_REDIS_HOST` and `CACHE_REDIS_PORT`. Defaults to value of `REDIS_URL`. + +#### `CACHE_REDIS_NAMESPACE` + +Defaults to value of `REDIS_NAMESPACE`. + +#### `SIDEKIQ_REDIS_URL` + +### ElasticSearch {#elasticsearch} + +{{< page-ref page="admin/optional/elasticsearch" >}} + +#### `ES_ENABLED` + +If set to `true`, Mastodon will use ElasticSearch for its search functions. + +#### `ES_HOST` + +Host of the ElasticSearch server. Defaults to `localhost` + +#### `ES_PORT` + +Port of the ElasticSearch server. Defaults to `9200` + +#### `ES_USER` + +Used for optionally authenticating with ElasticSearch + +#### `ES_PASS` + +Used for optionally authenticating with ElasticSearch + +#### `ES_PREFIX` + +Useful if the ElasticSearch server is shared between multiple projects or different Mastodon servers. Defaults to value of `REDIS_NAMESPACE`. + +### StatsD {#statsd} + +#### `STATSD_ADDR` + +If set, Mastodon will log some events and metrics into a StatsD instance identified by its hostname and port. + +Example value: `localhost:8125` + +#### `STATSD_NAMESPACE` + +If set, all StatsD keys will be prefixed with this. Defaults to `Mastodon.production` when `RAILS_ENV` is `production`, `Mastodon.development` when it's `development`, etc. + +### SMTP email delivery {#smtp} + +#### `SMTP_SERVER` +#### `SMTP_PORT` +#### `SMTP_LOGIN` +#### `SMTP_PASSWORD` +#### `SMTP_FROM_ADDRESS` +#### `SMTP_DOMAIN` +#### `SMTP_DELIVERY_METHOD` +#### `SMTP_AUTH_METHOD` +#### `SMTP_CA_FILE` +#### `SMTP_OPENSSL_VERIFY_MODE` +#### `SMTP_ENABLE_STARTTLS_AUTO` +#### `SMTP_ENABLE_STARTTLS` + +Set to `auto` (default), `always`, or `never`. + +**Version history:**\ +4.0.0 - added + +#### `SMTP_TLS` +#### `SMTP_SSL` + +## File storage {#files} + +### CDN {cdn} #### `CDN_HOST` @@ -434,7 +433,7 @@ It is *extremely recommended* to use your own host instead, for a few reasons: Example value: `files.example.com` -{{< page-ref page="admin/optional/object-storage-proxy.md" >}} +{{< page-ref page="admin/optional/object-storage-proxy" >}} {{< hint style="info" >}} You must serve the files with CORS headers, otherwise some functions of Mastodon's web UI will not work. For example, `Access-Control-Allow-Origin: *` @@ -442,119 +441,218 @@ You must serve the files with CORS headers, otherwise some functions of Mastodon ### Local file storage {#paperclip} -* `PAPERCLIP_ROOT_PATH` -* `PAPERCLIP_ROOT_URL` +#### `PAPERCLIP_ROOT_PATH` +#### `PAPERCLIP_ROOT_URL` ### Amazon S3 and compatible {#s3} -* `S3_ENABLED` -* `S3_BUCKET` -* `AWS_ACCESS_KEY_ID` -* `AWS_SECRET_ACCESS_KEY` -* `S3_REGION` -* `S3_PROTOCOL` -* `S3_HOSTNAME` -* `S3_ENDPOINT` -* `S3_SIGNATURE_VERSION` -* `S3_OVERRIDE_PATH_STYLE` -* `S3_OPEN_TIMEOUT` -* `S3_READ_TIMEOUT` +#### `S3_ENABLED` +#### `S3_BUCKET` +#### `AWS_ACCESS_KEY_ID` +#### `AWS_SECRET_ACCESS_KEY` +#### `S3_REGION` +#### `S3_PROTOCOL` +#### `S3_HOSTNAME` +#### `S3_ENDPOINT` +#### `S3_SIGNATURE_VERSION` +#### `S3_OVERRIDE_PATH_STYLE` +#### `S3_OPEN_TIMEOUT` +#### `S3_READ_TIMEOUT` +#### `S3_FORCE_SINGLE_REQUEST` ### Swift {#swift} -* `SWIFT_ENABLED` -* `SWIFT_USERNAME` -* `SWIFT_TENANT` -* `SWIFT_PASSWORD` -* `SWIFT_PROJECT_ID` -* `SWIFT_AUTH_URL` -* `SWIFT_CONTAINER` -* `SWIFT_OBJECT_URL` -* `SWIFT_REGION` -* `SWIFT_DOMAIN_NAME` -* `SWIFT_CACHE_TTL` +#### `SWIFT_ENABLED` +#### `SWIFT_USERNAME` +#### `SWIFT_TENANT` +#### `SWIFT_PASSWORD` +#### `SWIFT_PROJECT_ID` +#### `SWIFT_AUTH_URL` +#### `SWIFT_CONTAINER` +#### `SWIFT_OBJECT_URL` +#### `SWIFT_REGION` +#### `SWIFT_DOMAIN_NAME` +#### `SWIFT_CACHE_TTL` ## External authentication {#external-authentication} -* `OAUTH_REDIRECT_AT_SIGN_IN` +### OmniAuth + +#### `OMNIAUTH_ONLY` ### LDAP {#ldap} -* `LDAP_ENABLED` -* `LDAP_HOST` -* `LDAP_PORT` -* `LDAP_METHOD` -* `LDAP_BASE` -* `LDAP_BIND_DN` -* `LDAP_PASSWORD` -* `LDAP_UID` -* `LDAP_SEARCH_FILTER` -* `LDAP_MAIL` -* `LDAP_UID_CONVERSTION_ENABLED` +#### `LDAP_ENABLED` +#### `LDAP_HOST` +#### `LDAP_PORT` +#### `LDAP_METHOD` +#### `LDAP_BASE` +#### `LDAP_BIND_DN` +#### `LDAP_PASSWORD` +#### `LDAP_UID` +#### `LDAP_SEARCH_FILTER` +#### `LDAP_MAIL` +#### `LDAP_UID_CONVERSTION_ENABLED` ### PAM {#pam} -* `PAM_ENABLED` -* `PAM_EMAIL_DOMAIN` -* `PAM_DEFAULT_SERVICE` -* `PAM_CONTROLLED_SERVICE` +#### `PAM_ENABLED` +#### `PAM_EMAIL_DOMAIN` +#### `PAM_DEFAULT_SERVICE` +#### `PAM_CONTROLLED_SERVICE` ### CAS {#cas} -* `CAS_ENABLED` -* `CAS_URL` -* `CAS_HOST` -* `CAS_PORT` -* `CAS_SSL` -* `CAS_VALIDATE_URL` -* `CAS_CALLBACK_URL` -* `CAS_LOGOUT_URL` -* `CAS_LOGIN_URL` -* `CAS_UID_FIELD` -* `CAS_CA_PATH` -* `CAS_DISABLE_SSL_VERIFICATION` -* `CAS_UID_KEY` -* `CAS_NAME_KEY` -* `CAS_EMAIL_KEY` -* `CAS_NICKNAME_KEY` -* `CAS_FIRST_NAME_KEY` -* `CAS_LAST_NAME_KEY` -* `CAS_LOCATION_KEY` -* `CAS_IMAGE_KEY` -* `CAS_PHONE_KEY` +#### `CAS_ENABLED` +#### `CAS_DISPLAY_NAME` +#### `CAS_URL` +#### `CAS_HOST` +#### `CAS_PORT` +#### `CAS_SSL` +#### `CAS_VALIDATE_URL` +#### `CAS_CALLBACK_URL` +#### `CAS_LOGOUT_URL` +#### `CAS_LOGIN_URL` +#### `CAS_UID_FIELD` +#### `CAS_CA_PATH` +#### `CAS_DISABLE_SSL_VERIFICATION` +#### `CAS_UID_KEY` +#### `CAS_NAME_KEY` +#### `CAS_EMAIL_KEY` +#### `CAS_NICKNAME_KEY` +#### `CAS_FIRST_NAME_KEY` +#### `CAS_LAST_NAME_KEY` +#### `CAS_LOCATION_KEY` +#### `CAS_IMAGE_KEY` +#### `CAS_PHONE_KEY` +#### `CAS_SECURITY_ASSUME_EMAIL_IS_VERIFIED` ### SAML {#saml} -* `SAML_ENABLED` -* `SAML_ACS_URL` -* `SAML_ISSUER` -* `SAML_IDP_SSO_TARGET_URL` -* `SAML_IDP_CERT` -* `SAML_IDP_CERT_FINGERPRINT` -* `SAML_NAME_IDENTIFIER_FORMAT` -* `SAML_CERT` -* `SAML_PRIVATE_KEY` -* `SAML_SECURITY_WANT_ASSERTION_SIGNED` -* `SAML_SECURITY_WANT_ASSERTION_ENCRYPTED` -* `SAML_SECURITY_ASSUME_EMAIL_IS_VERIFIED` -* `SAML_ATTRIBUTES_STATEMENTS_UID` -* `SAML_ATTRIBUTES_STATEMENTS_EMAIL` -* `SAML_ATTRIBUTES_STATEMENTS_FULL_NAME` -* `SAML_ATTRIBUTES_STATEMENTS_FIRST_NAME` -* `SAML_ATTRIBUTES_STATEMENTS_LAST_NAME` -* `SAML_UID_ATTRIBUTE` -* `SAML_ATTRIBUTES_STATEMENTS_VERIFIED` -* `SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL` +#### `SAML_ENABLED` +#### `SAML_ACS_URL` +#### `SAML_ISSUER` +#### `SAML_IDP_SSO_TARGET_URL` +#### `SAML_IDP_CERT` +#### `SAML_IDP_CERT_FINGERPRINT` +#### `SAML_NAME_IDENTIFIER_FORMAT` +#### `SAML_CERT` +#### `SAML_PRIVATE_KEY` +#### `SAML_SECURITY_WANT_ASSERTION_SIGNED` +#### `SAML_SECURITY_WANT_ASSERTION_ENCRYPTED` +#### `SAML_SECURITY_ASSUME_EMAIL_IS_VERIFIED` +#### `SAML_ATTRIBUTES_STATEMENTS_UID` +#### `SAML_ATTRIBUTES_STATEMENTS_EMAIL` +#### `SAML_ATTRIBUTES_STATEMENTS_FULL_NAME` +#### `SAML_ATTRIBUTES_STATEMENTS_FIRST_NAME` +#### `SAML_ATTRIBUTES_STATEMENTS_LAST_NAME` +#### `SAML_UID_ATTRIBUTE` +#### `SAML_ATTRIBUTES_STATEMENTS_VERIFIED` +#### `SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL` ## Hidden services {#hidden-services} -{{< page-ref page="admin/optional/tor.md" >}} +### TOR {#tor} -* `http_proxy` -* `ALLOW_ACCESS_TO_HIDDEN_SERVICE` +{{< page-ref page="admin/optional/tor" >}} + +#### `http_proxy` +#### `http_hidden_proxy` +#### `ALLOW_ACCESS_TO_HIDDEN_SERVICE` + +## Limits {#limits} + +### Email domains + +#### `EMAIL_DOMAIN_ALLOWLIST` + +If set, registrations will not be possible with any e-mails **except** those from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com` + +#### `EMAIL_DOMAIN_DENYLIST` + +If set, registrations will not be possible with any e-mails from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com` + +{{< hint style="warning" >}} +This option is deprecated. You can dynamically block e-mail domains from the admin interface or from the `tootctl` command-line interface. +{{}} + +### Sessions + +#### `MAX_SESSION_ACTIVATIONS` + +How many browser sessions are allowed per-user. Defaults to `10`. If a new browser session is created, then the oldest session is deleted, e.g. user in that browser is logged out. + +### Home feeds + +#### `USER_ACTIVE_DAYS` + +Mastodon stores home feeds in RAM (specifically, in the Redis database). This makes them very fast to access and update, but it also means that you don't want to keep them there if they're not used, and you don't want to spend resources on inserting new items into home feeds that will not be accessed. For this reason, Mastodon periodically clears out home feeds of users who haven't been online in a while, and if they re-appear, it regenerates those home feeds from database data. By default, users are considered active if they have been online in the past `7` days. + +Regeneration of home feeds is computationally expensive, if your Sidekiq is constantly doing it because your users come online every 3 days but your `USER_ACTIVE_DAYS` is set to 2, then consider adjusting it up. + +{{< hint style="info" >}} +This setting has no relation to which users are considered active for the purposes of statistics, such as the Monthly Active Users number. +{{}} ## Other {#other} +### DB migrations {#migrations} + #### `SKIP_POST_DEPLOYMENT_MIGRATIONS` This variable only has any effect when running `rake db:migrate` and it is extremely specific to the Mastodon upgrade process. There are two types of database migrations, those that run before new code is deployed and running, and those that run after. By default, both types of migrations are executed. If you shut down all Mastodon processes before running migrations, then there is no difference. The variable makes sense for zero-downtime upgrades. You will see in the upgrade instructions of a specific Mastodon version if you need to use it or not. + +### Uncategorized or unsorted + +#### `BUNDLE_GEMFILE` +#### `DEEPL_API_KEY` +#### `DEEPL_PLAN` +#### `LIBRE_TRANSLATE_ENDPOINT` +#### `LIBRE_TRANSLATE_API_KEY` +#### `CACHE_BUSTER_ENABLED` +#### `CACHE_BUSTER_SECRET_HEADER` +#### `CACHE_BUSTER_SECRET` +#### `GITHUB_REPOSITORY` + +Defaults to `mastodon/mastodon` + +#### `SOURCE_BASE_URL` + +Defaults to `https://github.com/$GITHUB_REPOSITORY` + +#### `FFMPEG_BINARY` +#### `LOCAL_HTTPS` +#### `PATH` +#### `MAX_FOLLOWS_THRESHOLD` + +Defaults to `7500` + +#### `MAX_FOLLOWS_RATIO` + +Defaults to `1.1` + +#### `IP_RETENTION_PERIOD` + +Defaults to `31536000` (1 year) + +#### `SESSION_RETENTION_PERIOD` + +Defaults to `31536000` (1 year) + +#### `BACKTRACE` + +Set to `1` to allow backtracing to Rails framework code. + +#### `DISABLE_SIMPLECOV` + +#### `EMAIL_DOMAIN_LISTS_APPLY_AFTER_CONFIRMATION` + +#### `DISABLE_FOLLOWERS_SYNCHRONIZATION` + +#### `MAX_REQUEST_POOL_SIZE` + +Defaults to `512`. + +#### `GITHUB_API_TOKEN` + +Used in a rake task for generating AUTHORS.md from Github commit history. \ No newline at end of file diff --git a/content/en/admin/install.md b/content/en/admin/install.md index dddc14b0..0984c370 100644 --- a/content/en/admin/install.md +++ b/content/en/admin/install.md @@ -10,7 +10,7 @@ menu: ## Pre-requisites {#pre-requisites} * A machine running **Ubuntu 20.04** or **Debian 11** that you have root access to -* A **domain name** \(or a subdomain\) for the Mastodon server, e.g. `example.com` +* A **domain name** (or a subdomain) for the Mastodon server, e.g. `example.com` * An e-mail delivery service or other **SMTP server** You will be running the commands as root. If you aren’t already root, switch to root: @@ -84,8 +84,8 @@ git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build Once this is done, we can install the correct Ruby version: ```bash -RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.3 -rbenv global 3.0.3 +RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.4 +rbenv global 3.0.4 ``` We’ll also need to install bundler: @@ -104,7 +104,7 @@ exit ### Setting up PostgreSQL {#setting-up-postgresql} -#### Performance configuration \(optional\) {#performance-configuration-optional} +#### Performance configuration (optional) {#performance-configuration-optional} For optimal performance, you may use [pgTune](https://pgtune.leopard.in.ua/#/) to generate an appropriate configuration and edit values in `/etc/postgresql/14/main/postgresql.conf` before restarting PostgreSQL with `systemctl restart postgresql` @@ -140,7 +140,7 @@ su - mastodon Use git to download the latest stable release of Mastodon: ```bash -git clone https://github.com/tootsuite/mastodon.git live && cd live +git clone https://github.com/mastodon/mastodon.git live && cd live git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1) ``` @@ -173,7 +173,7 @@ This will: * Run asset precompilation * Create the database schema -The configuration file is saved as `.env.production`. You can review and edit it to your liking. Refer to the [documentation on configuration.]({{< relref "config.md" >}}) +The configuration file is saved as `.env.production`. You can review and edit it to your liking. Refer to the [documentation on configuration.]({{< relref "config" >}}) You’re done with the mastodon user for now, so switch back to root: diff --git a/content/en/admin/migrating.md b/content/en/admin/migrating.md index 90ff6367..35b3bcb7 100644 --- a/content/en/admin/migrating.md +++ b/content/en/admin/migrating.md @@ -15,10 +15,10 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth ## Basic steps {#basic-steps} -1. Set up a new Mastodon server using the [Production Guide]({{< relref "install.md" >}}) \(however, don’t run `mastodon:setup`\). -2. Stop Mastodon on the old server \(e.g. `systemctl stop 'mastodon-*.service'`\). +1. Set up a new Mastodon server using the [Production Guide]({{< relref "install" >}}) (however, don’t run `mastodon:setup`). +2. Stop Mastodon on the old server (e.g. `systemctl stop 'mastodon-*.service'`). 3. Dump and load the Postgres database using the instructions below. -4. Copy the `system/` files using the instructions below. \(Note: if you’re using S3, you can skip this step.\) +4. Copy the `system/` files using the instructions below. (Note: if you’re using S3, you can skip this step.) 5. Copy the `.env.production` file. 6. Run `RAILS_ENV=production bundle exec rails assets:precompile` to compile Mastodon 7. Run `RAILS_ENV=production ./bin/tootctl feeds build` to rebuild the home timelines for each user. @@ -33,19 +33,19 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth At a high level, you’ll need to copy over the following: -* The `~/live/public/system` directory, which contains user-uploaded images and videos \(if using S3, you don’t need this\) -* The Postgres database \(using [pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)\) +* The `~/live/public/system` directory, which contains user-uploaded images and videos (if using S3, you don’t need this) +* The Postgres database (using [pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)) * The `~/live/.env.production` file, which contains server config and secrets Less crucially, you’ll probably also want to copy the following for convenience: -* The nginx config \(under `/etc/nginx/sites-available/default`\) -* The systemd config files \(`/etc/systemd/system/mastodon-*.service`\), which may contain your server tweaks and customizations -* The pgbouncer configuration under `/etc/pgbouncer` \(if you’re using it\) +* The nginx config (under `/etc/nginx/sites-available/default`) +* The systemd config files (`/etc/systemd/system/mastodon-*.service`), which may contain your server tweaks and customizations +* The pgbouncer configuration under `/etc/pgbouncer` (if you’re using it) ### Dump and load Postgres {#dump-and-load-postgres} -Instead of running `mastodon:setup`, we’re going to create an empty Postgres database using the `template0` database \(which is useful when restoring a Postgres dump, [as described in the pg\_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)\). +Instead of running `mastodon:setup`, we’re going to create an empty Postgres database using the `template0` database (which is useful when restoring a Postgres dump, [as described in the pg\_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)). Run this as the `mastodon` user on your old system: @@ -66,7 +66,7 @@ pg_restore -Fc -U mastodon -n public --no-owner --role=mastodon \ -d mastodon_production backup.dump ``` -\(Note that if the username is not `mastodon` on the new server, you should change the `-U` AND `--role` values above. It’s okay if the username is different between the two servers.\) +(Note that if the username is not `mastodon` on the new server, you should change the `-U` AND `--role` values above. It’s okay if the username is different between the two servers.) ### Copy files {#copy-files} @@ -86,7 +86,7 @@ Optionally, you may copy over the nginx, systemd, and pgbouncer config files, or You can edit the `~/live/public/500.html` page on the old machine if you want to show a nice error message to let existing users know that a migration is in progress. -You’ll probably also want to set the DNS TTL to something small \(30-60 minutes\) about a day in advance, so that DNS can propagate quickly once you point it to the new IP address. +You’ll probably also want to set the DNS TTL to something small (30-60 minutes) about a day in advance, so that DNS can propagate quickly once you point it to the new IP address. ### After migrating {#after-migrating} diff --git a/content/en/admin/moderation.md b/content/en/admin/moderation.md index e073600a..14dc0cbb 100644 --- a/content/en/admin/moderation.md +++ b/content/en/admin/moderation.md @@ -7,10 +7,12 @@ menu: parent: admin --- -## Individual moderation {#individual-moderation} +## Moderating individual users {#individual-moderation} Moderation in Mastodon is always applied locally, i.e. as seen from the particular server. An admin or moderator on one server cannot affect a user on another server, they can only affect the local copy on their own server. +As of v3.5.0, all default user moderation decisions will notify the affected user by email. The user can access an appeal page, where they can submit one appeal within 20 days of the decision. Moderators can approve or reject the appeal. + ### Sensitive {#sensitive-user} When an account is marked as sensitive, all media that user posts will be automatically [marked as sensitive](https://docs.joinmastodon.org/user/posting/#cw). @@ -27,9 +29,9 @@ When the user's account is un-frozen, normal functionality resumes. ### Limit {#limit-user} -A limited account is hidden to all other users on that instance, except for its followers. All of the content is still there, and it can still be found via search, mentions, and following, but the content is invisible publicly. +Previously known as "silencing". A limited account is hidden to all other users on that instance, except for its followers. All of the content is still there, and it can still be found via search, mentions, and following, but the content is invisible publicly. -At this moment, limit does not affect federation. A locally limited account is _not_ limited automatically on other servers. Account limitations are reversible. +At this moment, limit does not affect federation. A locally limited account is *not* limited automatically on other servers. Account limitations are reversible. ### Suspend {#suspend-user} @@ -37,9 +39,9 @@ A Mastodon suspension means the account is effectively deleted. The account no l If the account is reinstated within the 30 day period, all data is once again accessible publicly without any adverse affects. If the 30 day period lapses, **all** that user's data is purged from the instance. Admins also have the option to immediately delete the user's account data at any point during the 30 days. -Once the data has been deleted, whether than be after the 30 day period, or if an admin has force deleted it, the account can still be un-suspended. However, the account will have no data (toots, profile information, avatar or header image) associated with it. +Once the data has been deleted, whether than be after the 30 day period, or if an admin has force deleted it, the account can still be un-suspended. However, the account will have no data (statuses, profile information, avatar or header image) associated with it. -## Server-wide moderation {#server-wide-moderation} +## Moderating entire websites {#server-wide-moderation} Because individually moderating a large volume of users from a misbehaving server can be exhausting, it is possible to pre-emptively moderate against all users from that particular server using a so-called **domain block**, which comes with several different levels of severity. @@ -47,13 +49,13 @@ Because individually moderating a large volume of users from a misbehaving serve With this option active, no files from the server will be processed locally. That includes avatars, headers, emojis and media attachments. -### Silence {#silence-server} +### Limit {#limit-server} -Applies a silence to all past and future accounts from the server. +Equivalent to [limiting](#limit-user) all past and future accounts from the server. Previously known as "silencing". ### Suspend {#suspend-server} -Applies a suspension to all past and future accounts from the server. No content from the server will be stored locally except for usernames. +Equivalent to [suspending](#suspend-user) all past and future accounts from the server. No content from the server will be stored locally except for usernames. ## Spam-fighting measures {#spam-fighting-measures} diff --git a/content/en/admin/optional/elasticsearch.md b/content/en/admin/optional/elasticsearch.md index 755e40e2..e6c52bf6 100644 --- a/content/en/admin/optional/elasticsearch.md +++ b/content/en/admin/optional/elasticsearch.md @@ -7,7 +7,7 @@ menu: parent: admin-optional --- -Mastodon supports full-text search when ElasticSearch is available. Mastodon’s full-text search allows logged in users to find results from their own toots, their favourites, and their mentions. It deliberately does not allow searching for arbitrary strings in the entire database. +Mastodon supports full-text search when ElasticSearch is available. Mastodon’s full-text search allows logged in users to find results from their own statuses, their mentions, their favourites, and their bookmarks. It deliberately does not allow searching for arbitrary strings in the entire database. ## Installing ElasticSearch {#install} diff --git a/content/en/admin/optional/sso.md b/content/en/admin/optional/sso.md index 7617235d..234fc89a 100644 --- a/content/en/admin/optional/sso.md +++ b/content/en/admin/optional/sso.md @@ -8,5 +8,7 @@ menu: {{< hint style="danger" >}} This page is under construction. + +For the moment, please refer to [this pull request](https://github.com/mastodon/mastodon/pull/16221) {{< /hint >}} diff --git a/content/en/admin/prerequisites.md b/content/en/admin/prerequisites.md index ba9a8bac..e5214a35 100644 --- a/content/en/admin/prerequisites.md +++ b/content/en/admin/prerequisites.md @@ -8,7 +8,7 @@ menu: If you are setting up a fresh machine, it is recommended that you secure it first. Assuming that you are running **Ubuntu 20.04**: -## Do not allow password-based SSH login \(keys only\) +## Do not allow password-based SSH login (keys only) First make sure you are actually logging in to the server using keys and not via a password, otherwise this will lock you out. Many hosting providers support uploading a public key and automatically set up key-based root login on new machines for you. diff --git a/content/en/admin/scaling.md b/content/en/admin/scaling.md index 6c9d4a45..ba003312 100644 --- a/content/en/admin/scaling.md +++ b/content/en/admin/scaling.md @@ -11,11 +11,11 @@ menu: Mastodon has three types of processes: -* Web \(Puma\) +* Web (Puma) * Streaming API -* Background processing \(Sidekiq\) +* Background processing (Sidekiq) -### Web \(Puma\) {#web} +### Web (Puma) {#web} The web process serves short-lived HTTP requests for most of the application. The following environment variables control it: @@ -37,7 +37,7 @@ The streaming API handles long-lived HTTP and WebSockets connections, through wh One process can handle a reasonably high number of connections. The streaming API can be hosted on a different subdomain if you want to e.g. avoid the overhead of nginx proxying the connections. -### Background processing \(Sidekiq\) {#sidekiq} +### Background processing (Sidekiq) {#sidekiq} Many tasks in Mastodon are delegated to background processing to ensure the HTTP requests are fast, and to prevent HTTP request aborts from affecting the execution of those tasks. Sidekiq is a single process, with a configurable number of threads. @@ -84,7 +84,7 @@ As a solution, it is possible to start different Sidekiq processes for the queue ### Why you might need PgBouncer {#pgbouncer-why} -If you start running out of available Postgres connections \(the default is 100\) then you may find PgBouncer to be a good solution. This document describes some common gotchas as well as good configuration defaults for Mastodon. +If you start running out of available Postgres connections (the default is 100) then you may find PgBouncer to be a good solution. This document describes some common gotchas as well as good configuration defaults for Mastodon. Note that you can check “PgHero” in the administration view to see how many Postgres connections are currently being used. Typically Mastodon uses as many connections as there are threads both in Puma, Sidekiq and the streaming API combined. @@ -108,7 +108,7 @@ Here’s how you might reset the password: psql -p 5432 -U mastodon mastodon_production -w ``` -Then \(obviously, use a different password than the word “password”\): +Then (obviously, use a different password than the word “password”): ```sql ALTER USER mastodon WITH PASSWORD 'password'; @@ -164,13 +164,13 @@ listen_addr = 127.0.0.1 listen_port = 6432 ``` -Put `md5` as the `auth_type` \(assuming you’re using the md5 format in `userlist.txt`\): +Put `md5` as the `auth_type` (assuming you’re using the md5 format in `userlist.txt`): Make sure the `pgbouncer` user is an admin: **This next part is very important!** The default pooling mode is session-based, but for Mastodon we want transaction-based. In other words, a Postgres connection is created when a transaction is created and dropped when the transaction is done. So you’ll want to change the `pool_mode` from `session` to `transaction`: -Next up, `max_client_conn` defines how many connections PgBouncer itself will accept, and `default_pool_size` puts a limit on how many Postgres connections will be opened under the hood. \(In PgHero the number of connections reported will correspond to `default_pool_size` because it has no knowledge of PgBouncer.\) +Next up, `max_client_conn` defines how many connections PgBouncer itself will accept, and `default_pool_size` puts a limit on how many Postgres connections will be opened under the hood. (In PgHero the number of connections reported will correspond to `default_pool_size` because it has no knowledge of PgBouncer.) The defaults are fine to start, and you can always increase them later: @@ -211,7 +211,7 @@ PREPARED_STATEMENTS=false Since we’re using transaction-based pooling, we can’t use prepared statements. -Next up, configure Mastodon to use port 6432 \(PgBouncer\) instead of 5432 \(Postgres\) and you should be good to go: +Next up, configure Mastodon to use port 6432 (PgBouncer) instead of 5432 (Postgres) and you should be good to go: ```bash DB_HOST=localhost @@ -222,7 +222,7 @@ DB_PORT=6432 ``` {{< hint style="warning" >}} -You cannot use pgBouncer to perform `db:migrate` tasks. But this is easy to work around. If your postgres and pgbouncer are on the same host, it can be as simple as defining `DB_PORT=5432` together with `RAILS_ENV=production` when calling the task, for example: `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` \(you can specify `DB_HOST` too if it’s different, etc\) +You cannot use pgBouncer to perform `db:migrate` tasks. But this is easy to work around. If your postgres and pgbouncer are on the same host, it can be as simple as defining `DB_PORT=5432` together with `RAILS_ENV=production` when calling the task, for example: `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` (you can specify `DB_HOST` too if it’s different, etc) {{< /hint >}} #### Administering PgBouncer {#pgbouncer-admin} @@ -249,13 +249,13 @@ Then use `\q` to quit. ## Separate Redis for cache {#redis} -Redis is used widely throughout the application, but some uses are more important than others. Home feeds, list feeds, and Sidekiq queues as well as the streaming API are backed by Redis and that’s important data you wouldn’t want to lose \(even though the loss can be survived, unlike the loss of the PostgreSQL database - never lose that!\). However, Redis is also used for volatile cache. If you are at a stage of scaling up where you are worried if your Redis can handle everything, you can use a different Redis database for the cache. In the environment, you can specify `CACHE_REDIS_URL` or individual parts like `CACHE_REDIS_HOST`, `CACHE_REDIS_PORT` etc. Unspecified parts fallback to the same values as without the cache prefix. +Redis is used widely throughout the application, but some uses are more important than others. Home feeds, list feeds, and Sidekiq queues as well as the streaming API are backed by Redis and that’s important data you wouldn’t want to lose (even though the loss can be survived, unlike the loss of the PostgreSQL database - never lose that!). However, Redis is also used for volatile cache. If you are at a stage of scaling up where you are worried if your Redis can handle everything, you can use a different Redis database for the cache. In the environment, you can specify `CACHE_REDIS_URL` or individual parts like `CACHE_REDIS_HOST`, `CACHE_REDIS_PORT` etc. Unspecified parts fallback to the same values as without the cache prefix. As far as configuring the Redis database goes, basically you can get rid of background saving to disk, since it doesn’t matter if the data gets lost on restart and you can save some disk I/O on that. You can also add a maximum memory limit and a key eviction policy, for that, see this guide: [Using Redis as an LRU cache](https://redis.io/topics/lru-cache) ## Read-replicas {#read-replicas} -To reduce the load on your Postgresql server, you may wish to setup hot streaming replication \(read replica\). [See this guide for an example](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby). You can make use of the replica in Mastodon in these ways: +To reduce the load on your Postgresql server, you may wish to setup hot streaming replication (read replica). [See this guide for an example](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby). You can make use of the replica in Mastodon in these ways: * The streaming API server does not issue writes at all, so you can connect it straight to the replica. But it’s not querying the database very often anyway so the impact of this is little. * Use the Makara driver in the web and sidekiq processes, so that writes go to the master database, while reads go to the replica. Let’s talk about that. diff --git a/content/en/admin/setup.md b/content/en/admin/setup.md index fc8af204..28127503 100644 --- a/content/en/admin/setup.md +++ b/content/en/admin/setup.md @@ -17,6 +17,10 @@ After signing up in the browser, you will need to use the command line to give y RAILS_ENV=production bin/tootctl accounts modify alice --role Owner ``` +{{}} +Prior to Mastodon 4.0, roles were hardcoded to be one of `user`, `moderator`, or `admin`. Since Mastodon 4.0, there is a customizable role system, with default roles created for `Moderator`, `Admin`, and `Owner`. Names of custom roles are case-sensitive. +{{}} + ### From the command line {#admin-cli} You can create a new account using the command-line interface. @@ -42,7 +46,7 @@ After logging in, navigate to the **Site settings** page. While there are no tec | Instance description | Why did you start this server? Who is it for? What makes it different? | | Custom extended information | You can put all sorts of information in here but a **code of conduct** is recommended | -After you fill these in, simply hit “Save changes”. +After you fill these in, click “Save changes”. ## Running periodic cleanup tasks {#cleanup} diff --git a/content/en/admin/tootctl.md b/content/en/admin/tootctl.md index 2c0ddf22..879d5a33 100644 --- a/content/en/admin/tootctl.md +++ b/content/en/admin/tootctl.md @@ -7,7 +7,7 @@ menu: parent: admin --- -The command-line interface of Mastodon is an executable file called `tootctl` residing in the `bin` directory within the Mastodon root directory. You must specify which environment you intend to use whenever you execute it by specifying the `RAILS_ENV` environment variable. Unless you are a developer working on a local machine, you need to use `RAILS_ENV=production`. If you are sure that you will never need another environment \(for development, testing, or staging\), you can add it to your `.bashrc` file for convenience, e.g.: +The command-line interface of Mastodon is an executable file called `tootctl` residing in the `bin` directory within the Mastodon root directory. You must specify which environment you intend to use whenever you execute it by specifying the `RAILS_ENV` environment variable. Unless you are a developer working on a local machine, you need to use `RAILS_ENV=production`. If you are sure that you will never need another environment (for development, testing, or staging), you can add it to your `.bashrc` file for convenience, e.g.: ```bash echo "export RAILS_ENV=production" >> ~/.bashrc @@ -22,7 +22,11 @@ RAILS_ENV=production bin/tootctl help ## Base CLI -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/cli.rb" caption="lib/cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/cli.rb" caption="lib/cli.rb" >}} + + +--- + ### `tootctl self-destruct` {#self-destruct} @@ -34,12 +38,15 @@ No local data is actually deleted, because emptying the database or deleting the **Make sure you know exactly what you are doing before running this command.** This operation is NOT reversible, and it can take a long time. The server will be in a BROKEN STATE after this command finishes. A running Sidekiq process is required, so do not shut down the server until the queues are fully cleared. {{< /hint >}} +`--dry-run` +: Print expected results only, without performing any actions. + **Version history:**\ 2.8.0 - added -| Option | Description | -| :--- | :--- | -| `--dry-run` | Print expected results only, without performing any actions. | + +--- + ### `tootctl --version` {#version} @@ -48,180 +55,298 @@ Show the version of the currently running Mastodon instance. **Version history:**\ 2.7.0 - added + +--- + + ## Accounts CLI {#accounts} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts_cli.rb" >}} + + +--- + ### `tootctl accounts rotate` {#accounts-rotate} Generate and broadcast new RSA keys, as part of security maintenance. +`USERNAME` +: Local username for an account. + +`--all` +: Can be provided instead of `USERNAME` to rotate keys for all local accounts. + **Version history:**\ 2.5.0 - added -| Option | Description | -| :--- | :--- | -| `USERNAME` | Local username for an account. | -| `--all` | Can be provided instead of USERNAME to rotate keys for all local accounts. | + +--- + ### `tootctl accounts create` {#accounts-create} -Create a new user account with given USERNAME and provided --email. +Create a new user account with given `USERNAME` and provided `--email`. + +`USERNAME` +: Local username for the new account. {{}} + +`--email EMAIL` +: Email address to be attached to the user. {{}} + +`--confirmed` +: Skip sending the confirmation email and activate the account immediately. + +`--role ROLE` +: Define the new account's custom role by providing the `name` of that [Role]({{< relref "entities/Role" >}}). Default roles include `Owner`, `Admin`, and `Moderator`. + +`--reattach` +: Reuse an old USERNAME after its account has been deleted. + +`--force` +Forcefully delete any existing account with this `USERNAME` and reattach the new account in place of the (just-deleted) account. + +`--skip-sign-in-token` +: Forcefully ensure that the user is never asked for an e-mailed security code. **Version history:**\ -2.6.0 - added +2.6.0 - added\ +4.0.0 - `--role` no longer takes hard-coded `user`, `moderator`, or `admin` roles. Specify the name of the custom Role instead. + + +--- -| Option | Description | -| :--- | :--- | -| `USERNAME` | Local username for the new account. Required. | -| `--email EMAIL` | Email address to be attached to the user. Required. | -| `--confirmed` | Skip sending the confirmation email and activate the account immediately. | -| `--role ROLE` | Define the new account as a `User`, `Moderator`, or `Admin`. Defaults to `User`. | -| `--reattach` | Reuse an old USERNAME after its account has been deleted. | -| `--force` | Forcefully delete any existing account with this USERNAME and reattach the new account in place of the \(just-deleted\) account. | -| `--skip-sign-in-token` | Forcefully ensure that the user is never asked for an e-mailed security code. | ### `tootctl accounts modify` {#accounts-modify} Modify a user account's role, email, active status, approval mode, or 2FA requirement. +`USERNAME` +: Local username for the account. {{}} + +`--role ROLE` +: Define the existing account's custom role by providing the `name` of that [Role]({{< relref "entities/Role" >}}). Default roles include `Owner`, `Admin`, and `Moderator`. + +`--email EMAIL` +: Update the user's email address to `EMAIL`. + +`--confirm` +: Skip confirmation email, when used with `--email`. + +`--disable` +: Lock `USERNAME` out of their account. + +`--enable` +: Unlock `USERNAME`'s account if it is currently disabled. + +`--approve` +: Approve `USERNAME`'s account, if you are/were in approval mode. + +`--disable-2fa` +: Remove additional factors and allow login with password. + +`--reset-password` +: Resets the password of the given account. + +`--skip-sign-in-token` +: Forcefully ensure that the user is never asked for an e-mailed security code. + **Version history:**\ 2.6.0 - added\ -3.1.2 - added `--reset-password` +3.1.2 - added `--reset-password`\ +4.0.0 - `--role` no longer takes hard-coded `user`, `moderator`, or `admin` roles. Specify the name of the custom Role instead. + + +--- -| Option | Description | -| :--- | :--- | -| `USERNAME` | Local username for the account. Required. | -| `--role ROLE` | Define the account as a `user`, `moderator`, or `admin`. | -| `--email EMAIL` | Update the user's email address to EMAIL. | -| `--confirm` | Skip confirmation email, when used with --email. | -| `--disable` | Lock USERNAME out of their account. | -| `--enable` | Unlock USERNAME's account if it is currently disabled. | -| `--approve` | Approve the account, if you are/were in approval mode. | -| `--disable-2fa` | Remove additional factors and allow login with password. | -| `--reset-password` | Resets the password of the given account. | -| `--skip-sign-in-token` | Forcefully ensure that the user is never asked for an e-mailed security code. | ### `tootctl accounts delete` {#accounts-delete} Delete a user account with given USERNAME. +`USERNAME` +: Local username for the new account. {{}} + **Version history:**\ 2.6.0 - added -| Option | Description | -| :--- | :--- | -| `USERNAME` | Local username for the account. Required. | + +--- + ### `tootctl accounts backup` {#accounts-backup} Request a backup for a user account with given USERNAME. The backup will be created in Sidekiq asynchronously, and the user will receive an email with a link to it once it's done. +`USERNAME` +: Local username for the new account. {{}} + **Version history:**\ 2.6.0 - added -| Option | Description | -| :--- | :--- | -| `USERNAME` | Local username for the account. Required. | + +--- + ### `tootctl accounts cull` {#accounts-cull} Remove remote accounts that no longer exist. Queries every single remote account in the database to determine if it still exists on the origin server, and if it doesn't, then remove it from the database. Accounts that have had confirmed activity within the last week are excluded from the checks, in case the server is just down. +`DOMAIN[...]` +: Optionally pass specific domains to cull + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=5. + +`--dry-run` +: Print expected results only, without performing any actions. + **Version history:**\ 2.6.0 - added\ -2.8.0 - add `--dry-run` +2.8.0 - add `--dry-run`\ +3.5.0 - add ability to pass specific domains + + +--- -| Option | Description | -| :--- | :--- | -| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. | -| `--dry-run` | Print expected results only, without performing any actions. | ### `tootctl accounts refresh` {#accounts-refresh} Refetch remote user data and files for one or multiple accounts. +`USERNAME` +: username@domain for the remote account. + +`--all` +: Can be provided instead of `USERNAME` to refresh all remote accounts. + +`--domain DOMAIN` +: Can be provided instead of `USERNAME`. Operate only on remote accounts from this `DOMAIN`. + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=5. + +`--verbose` +: Print additional information while task is processing. + +`--dry-run` +: Print expected results only, without performing any actions. + **Version history:**\ 2.6.0 - added -| Option | Description | -| :--- | :--- | -| `USERNAME` | username@domain for the remote account. | -| `--all` | Can be provided instead of USERNAME to refresh all remote accounts. | -| `--domain DOMAIN` | Can be provided instead of USERNAME. Operate only on remote accounts from this DOMAIN. | -| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. | -| `--verbose` | Print additional information while task is processing. | -| `--dry-run` | Print expected results only, without performing any actions. | + +--- + ### `tootctl accounts merge` {#accounts-merge} Merge two remote accounts into one. This is primarily meant to fix duplicates caused by other servers changing their domain. By default, this only works if the public key is the same, but this can be overridden. +`FROM` +: username@domain for the remote account to be removed. {{}} + +`TO` +: username@domain for the remote account to be kept. {{}} + +`--force` +: Override the public key check. + **Version history:**\ 3.3.0 - added -| Option | Description | -| :--- | :--- | -| `FROM` | username@domain for the remote account to be removed. | -| `TO` | username@domain for the remote account to be kept. | -| `--force` | Override the public key check. | + +--- + ### `tootctl accounts follow` {#accounts-follow} Force all local accounts to follow a local account specified by username. +`USERNAME` +: Local username. {{}} + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=5. + +`--verbose` +: Print additional information while task is processing. + **Version history:**\ 2.7.0 - added\ -3.0.0 - now uses USERNAME instead of ACCT +3.0.0 - now uses `USERNAME` instead of `ACCT` + + +--- -| Option | Description | -| :--- | :--- | -| `USERNAME` | Local username | -| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. | -| `--verbose` | Print additional information while task is processing. | ### `tootctl accounts unfollow` {#accounts-unfollow} Force all local accounts to unfollow an account specified by their address. +`ACCT` +: `username@domain` address. {{}} + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=5. + +`--verbose` +: Print additional information while task is processing. + **Version history:**\ 2.7.0 - added -| Option | Description | -| :--- | :--- | -| `ACCT` | `username@domain` address | -| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. | -| `--verbose` | Print additional information while task is processing. | + +--- + ### `tootctl accounts reset-relationships` {#accounts-reset-relationships} Reset all follow and/or follower relationships for a local account. +`USERNAME` +: Local username. + +`--follows` +: Force `USERNAME` to unfollow everyone, then re-follow them. + +`--followers` +: Remove all of `USERNAME`'s followers. + **Version history:**\ 2.8.0 - added -| Option | Description | -| :--- | :--- | -| `USERNAME` | Local username | -| `--follows` | Force USERNAME to unfollow everyone, then re-follow them. | -| `--followers` | Remove all of USERNAME's followers. | + +--- + ### `tootctl accounts approve` {#accounts-approve} Approve new registrations when instance is in approval mode. +`USERNAME` +: Local username. + +`--number N` +: Approve the N most recent registrations. + +`--all` +: Approve all pending registrations. + **Version history:**\ 2.8.0 - added -| Option | Description | -| :--- | :--- | -| `USERNAME` | Approve the pending account with this username. | -| `--number N` | Approve the N most recent registrations. | -| `--all` | Approve all pending registrations. | + +--- + ## Cache CLI {#cache} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/cache_cli.rb" caption="lib/mastodon/cache\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/cache_cli.rb" caption="lib/mastodon/cache_cli.rb" >}} + + +--- + ### `tootctl cache clear` {#cache-clear} @@ -230,60 +355,103 @@ Clear out the cache storage. **Version history:**\ 2.8.1 - added + +--- + + ### `tootctl cache recount` {#cache-recount} Update hard-cached counters of TYPE by counting referenced records from scratch. It may take a very long time to finish, depending on the size of the database. Accounts will have their follower, following, and status counts refreshed. Statuses will have their reply, boost, and favourite counts refreshed. +`TYPE` +: Either `accounts` or `statuses`. {{}} + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=5. + +`--verbose` +: Print additional information while task is processing. + **Version history:**\ 3.0.0 - added -| Option | Description | -| :--- | :--- | -| TYPE | Either `accounts` or `statuses` | -| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. | -| `--verbose` | Print additional information while task is processing. | + +--- + ## Domains CLI {#domains} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/domains_cli.rb" caption="lib/mastodon/domains\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/domains_cli.rb" caption="lib/mastodon/domains_cli.rb" >}} + + +--- + ### `tootctl domains purge` {#domains-purge} Remove all accounts from a given DOMAIN without leaving behind any records. Unlike a suspension, if the DOMAIN still exists in the wild, it means the accounts could return if they are resolved again. +`DOMAIN[...]` +: Domains to purge, separated by space. + +`--by-uri` +: Match domains in the actor URI rather than in the Webfinger address. + +`--limited-federation-mode` +: Can be provided instead of DOMAIN. Instead of purging from a single domain, all accounts from domains that are not allow-listed will be removed from the database. Use this after enabling limited federation mode and defining your allow-list. + +`--concurrency N` +: The number of workers to use for this task. Defaults to 5. + +`--verbose` +: Print additional information while task is processing. + +`--dry-run` +: Print expected results only, without performing any actions. + **Version history:**\ 2.6.0 - added\ 2.8.0 - add `--whitelist-mode`\ 2.9.0 - remove custom emoji as well\ 3.0.0 - accept multiple domains\ -3.2.0 - rename `--whitelist-mode` to `--limited-federation-mode` +3.2.0 - rename `--whitelist-mode` to `--limited-federation-mode`\ +3.5.0 - add `--by-uri` + + +--- -| Option | Description | -| :--- | :--- | -| `DOMAIN[...]` | Domains to purge, separated by space. | -| `--limited-federation-mode` | Can be provided instead of DOMAIN. Instead of purging from a single domain, all accounts from domains that are not allow-listed will be removed from the database. Use this after enabling limited federation mode and defining your allow-list. | -| `--concurrency N` | The number of workers to use for this task. Defaults to 5. | -| `--verbose` | Print additional information while task is processing. | -| `--dry-run` | Print expected results only, without performing any actions. | ### `tootctl domains crawl` {#domains-crawl} Crawl the known fediverse by using Mastodon REST API endpoints that expose all known peers, and collect statistics from those peers, as long as those peers support those API endpoints. When no START is given, the command uses the server's own database of known peers to seed the crawl. Returns total servers, total registered users, total active users in the last week, and total users joined in the last week. +`START` +: Optionally start from a different domain name. + +`--exclude-suspended` +: Do not include instances that you have suspended in the output. Also includes any subdomains. + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=50. + +`--format FORMAT` +: Control how results are returned. `summary` will print a summary. `domains` will return a newline-delimited list of all discovered peers. `json` will dump aggregated raw data. Defaults to `summary`. + **Version history:**\ 2.7.0 - added\ 3.0.0 - add `--exclude-suspended` -| Option | Description | -| :--- | :--- | -| START | Optionally start from a different domain name. | -| `--concurrency N` | The number of workers to use for this task. Defaults to 50. | -| `--format FORMAT` | Control how results are returned. `summary` will print a summary. `domains` will return a newline-delimited list of all discovered peers. `json` will dump aggregated raw data. Defaults to `summary`. | -| `--exclude-suspended` | Do not include instances that you have suspended in the output. Also includes any subdomains. | + +--- + ## Email domain blocks CLI {#email-domain-blocks} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/email_domain_blocks_cli.rb" caption="lib/mastodon/email\_domain\_blocks\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/email_domain_blocks_cli.rb" caption="lib/mastodon/email_domain_blocks_cli.rb" >}} + + +--- + ### `tootctl email-domain-blocks list` {#email-domain-blocks-list} @@ -292,92 +460,146 @@ List all currently blocked email domains. **Version history:**\ 3.2.0 - added + +--- + + ### `tootctl email-domain-blocks add` {#email-domain-blocks-add} -Add entries to the e-mail domain blocklist. +Add entries to the email domain blocklist. + +`DOMAIN[...]` +: Email domains to block, separated by space. {{}} + +`--with-dns-records` +: If provided, will also lookup A, AAAA, and MX records and block them as well. **Version history:**\ 3.2.0 - added -| Option | Description | -| :--- | :--- | -| `DOMAIN[...]` | E-mail domains to block, separated by space. | -| `--with-dns-records` | If provided, will also lookup A, AAAA, and MX records and block them as well. | + +--- + ### `tootctl email-domain-blocks remove` {#email-domain-blocks-remove} Remove entries from the e-mail domain blocklist. +`DOMAIN[...]` +: Email domains to unblock, separated by space. {{}} + **Version history:**\ 3.2.0 - added -| Option | Description | -| :--- | :--- | -| `DOMAIN[...]` | E-mail domains to unblock, separated by space. | + +--- + ## Emoji CLI {#emoji} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji_cli.rb" >}} + + +--- + ### `tootctl emoji export` {#emoji-export} Exports custom emoji to `export.tar.gz` at PATH. +`PATH` +: Path to create a .tar.gz archive containing pictures. {{}} + +`--overwrite` +: Overwrite any existing archive at `PATH`. + +`--category CATEGORY` +: Export only the specified `CATEGORY`. If not provided, will export all emoji. + **Version history:**\ 3.1.4 - added -| Option | Description | -| :--- | :--- | -| `PATH` | Path to create a .tar.gz archive containing pictures. | -| `--overwrite` | Overwrite the existing archive. | -| `--category CATEGORY` | Export only the specified CATEGORY. If not provided, will export all emoji. | + +--- + ### `tootctl emoji import` {#emoji-import} Imports custom emoji from a .tar.gz archive at a given path. The archive should contain PNG or GIF files no larger than 50KB, and the shortcode will be set equal to the filename minus the extension, with optional prefixes and/or suffixes. +`PATH` +: Path to create a .tar.gz archive containing pictures. {{}} + +`--prefix PREFIX` +: Add PREFIX to the beginning of generated shortcodes. + +`--suffix SUFFIX` +: Add SUFFIX to the end of generated shortcodes. + +`--overwrite` +: Instead of skipping existing emoji, replace them with any discovered emoji with the same shortcode. + +`--category CATEGORY` +: Group the processed emoji under CATEGORY in the picker. + +`--unlisted` +: Processed emoji will not be shown in the emoji picker, but will be usable only by their direct shortcode. + **Version history:**\ 2.5.0 - added -| Option | Description | -| :--- | :--- | -| `PATH` | Path to a .tar.gz archive containing pictures. | -| `--prefix PREFIX` | Add PREFIX to the beginning of generated shortcodes. | -| `--suffix SUFFIX` | Add SUFFIX to the end of generated shortcodes. | -| `--overwrite` | Instead of skipping existing emoji, replace them with any discovered emoji with the same shortcode. | -| `--unlisted` | Processed emoji will not be shown in the emoji picker, but will be usable only by their direct shortcode. | -| `--category CATEGORY` | Group the processed emoji under CATEGORY in the picker. | + +--- + ### `tootctl emoji purge` {#emoji-purge} Remove all custom emoji. +`--remote-only` +: If provided, remove only from remote domains. + **Version history:**\ 2.8.0 - added\ 3.1.0 - add `--remote-only` -| Option | Description | -| :--- | :--- | -| `--remote-only` | If provided, remove only from remote domains. | + +--- + ## Feeds CLI {#feeds} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/feeds_cli.rb" caption="lib/mastodon/feeds\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/feeds_cli.rb" caption="lib/mastodon/feeds_cli.rb" >}} + + +--- + ### `tootctl feeds build` {#feeds-build} Build home and list feeds for one or all users. Feeds will be built from the database and cached in-memory with Redis. Mastodon manages home feeds for active users automatically. +`USERNAME` +: Local username whose feeds will be regenerated. + +`--all` +: Can be provided instead of `USERNAME` to refresh all remote accounts. + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=5. + +`--verbose` +: Print additional information while task is processing. + +`--dry-run` +: Print expected results only, without performing any actions. + **Version history:**\ 2.6.0 - added -| Option | Description | -| :--- | :--- | -| `USERNAME` | Local username whose feeds will be regenerated. | -| `--all` | Can be provided instead of USERNAME to refresh all local accounts' feeds. | -| `--concurrency N` | The number of workers to use for this task. Defaults to N=5. | -| `--verbose` | Print additional information while task is processing. | -| `--dry-run` | Print expected results only, without performing any actions. | + +--- + ### `tootctl feeds clear` {#feeds-clear} @@ -386,66 +608,118 @@ Remove all home and list feeds from Redis. **Version history:**\ 2.6.0 - added + +--- + + ## Maintenance CLI {#maintenance} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/maintenance_cli.rb" caption="lib/mastodon/maintenance\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/maintenance_cli.rb" caption="lib/mastodon/maintenance_cli.rb" >}} + + +--- + ### `tootctl maintenance fix-duplicates` {#maintenance-fix-duplicates} Fix corrupted database indexes that may have been caused due to changing collation rules. Deletes or merges duplicate accounts, statuses, emojis, etc. Mastodon has to be stopped to run this task, which will take a long time and may be destructive. This is useful if your database indexes are corrupted because of issues such as . +**Version history:**\ +3.3.0 - added + + +--- + + ## Media CLI {#media} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/media_cli.rb" caption="lib/mastodon/media\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/media_cli.rb" caption="lib/mastodon/media_cli.rb" >}} + + +--- + ### `tootctl media remove` {#media-remove} Remove locally cached copies of media attachments from other servers. +`--days N` +: How old media attachments have to be before they are removed. Defaults to 7. + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=5. + +`--verbose` +: Print additional information while task is processing. + +`--dry-run` +: Print expected results only, without performing any actions. + **Version history:**\ 2.5.0 - added\ 2.6.2 - show freed disk space -| Option | Description | -| :--- | :--- | -| `--days` | How old media attachments have to be before they are removed. Defaults to 7. | -| `--concurrency N` | The number of workers to use for this task. Defaults to 5. | -| `--verbose` | Print additional information while task is processing. | -| `--dry-run` | Print expected results only, without performing any actions. | + +--- + ### `tootctl media remove-orphans` {#media-remove-orphans} Scans for files that do not belong to existing media attachments, and remove them. Please mind that some storage providers charge for the necessary API requests to list objects. Also, this operation requires iterating over every single file individually, so it will be slow. +`--start-after` +: The Paperclip attachment key where the loop will start. Use this option if the command was interrupted before. + +`--dry-run` +: Print expected results only, without performing any actions. + +`--prefix` +: Traverse only a specific prefix of files in the system. + +`--fix-permissions` +: Sets S3 ACL to be default according to environment variables. + **Version history:**\ 3.1.0 - added\ 3.1.3 - added `--prefix`\ 3.3.0 - added `--fix-permissions` -| Option | Description | -| :--- | :--- | -| `--start-after` | The Paperclip attachment key where the loop will start. Use this option if the command was interrupted before. | -| `--dry-run` | Print expected results only, without performing any actions. | -| `--prefix` | Traverse only a specific prefix of files in the system. | -| `--fix-permissions` | Sets S3 ACL to be default according to environment variables. | + +--- + ### `tootctl media refresh` {#media-refresh} -Refetch remote media attachments from other servers. You must specify the source of media attachments with either --status, --account, or --domain. If an attachment already exists in the database, it will not be overwritten unless you use --force. +Refetch remote media attachments from other servers. You must specify the source of media attachments with either `--status`, `--account`, or `--domain`. If an attachment already exists in the database, it will not be overwritten unless you use `--force`. + +`--account ACCT` +: String `username@domain` handle of the account + +`--domain DOMAIN` +: FQDN string + +`--status ID` +: Local numeric ID of the status in the database. + +`--concurrency N` +: The number of workers to use for this task. Defaults to 5. + +`--verbose` +: Print additional information while task is processing. + +`--dry-run` +: Print expected results only, without performing any actions. + +`--force` +: Force redownload the remote resource and overwrite the local attachment. **Version history:**\ 3.0.0 - added\ 3.0.1 - add `--force` and skip already downloaded attachments by default -| Option | Description | -| :--- | :--- | -| `--account ACCT` | String `username@domain` handle of the account | -| `--domain DOMAIN` | FQDN string | -| `--status ID` | Local numeric ID of the status in the database. | -| `--concurrency N` | The number of workers to use for this task. Defaults to 5. | -| `--verbose` | Print additional information while task is processing. | -| `--dry-run` | Print expected results only, without performing any actions. | -| `--force` | Force redownload the remote resource and overwrite the local attachment. | + +--- + ### `tootctl media usage` {#media-usage} @@ -454,54 +728,93 @@ Calculate disk space consumed by Mastodon. **Version history:** 3.0.1 - added + +--- + + ### `tootctl media lookup` {#media-lookup} -Prompts for a media URL, then looks up where the media is displayed. +Prompts for a media URL, then looks up the status where the media is displayed. **Version history:**\ 3.1.0 - added + +--- + + ## Preview Cards CLI {#preview_cards} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/preview_cards_cli.rb" caption="lib/mastodon/preview\_cards\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/preview_cards_cli.rb" caption="lib/mastodon/preview_cards_cli.rb" >}} + + +--- + ### `tootctl preview_cards remove` {#preview_cards-remove} Remove local thumbnails for preview cards. +`--days N` +: How old media attachments have to be before they are removed. Defaults to 180. (NOTE: it is not recommended to delete preview cards within the last 14 days, because preview cards will not be refetched unless the link is reposted after 2 weeks from last time.) + +`--concurrency N` +: The number of workers to use for this task. Defaults to N=5. + +`--verbose` +: Print additional information while task is processing. + +`--dry-run` +: Print expected results only, without performing any actions. + +`--link` +: Only delete link-type preview cards; leave video and photo cards untouched. + **Version history:**\ 3.0.0 - added -| Option | Description | -| :--- | :--- | -| `--days` | How old media attachments have to be before they are removed. Defaults to 180. \(NOTE: it is not recommended to delete preview cards within the last 14 days, because preview cards will not be refetched unless the link is reposted after 2 weeks from last time.\) | -| `--concurrency N` | The number of workers to use for this task. Defaults to 5. | -| `--verbose` | Print additional information while task is processing. | -| `--dry-run` | Print expected results only, without performing any actions. | -| `--link` | Only delete link-type preview cards; leave video and photo cards untouched. | + +--- + ## Search CLI {#search} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/search_cli.rb" caption="lib/mastodon/search\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/search_cli.rb" caption="lib/mastodon/search_cli.rb" >}} + + +--- + ### `tootctl search deploy` {#search-deploy} Create or update an ElasticSearch index and populate it. If ElasticSearch is empty, this command will create the necessary indices and then import data from the database into those indices. This command will also upgrade indices if the underlying schema has been changed since the last run. +`--batch-size` +: Defaults to 1000. A lower batch size can make ElasticSearch process records more quickly. + +`--only INDEX` +: Specify an index name [`accounts`, `tags`, `statuses`] to create or update only that index. + +`--concurrency N` +: Parallelize execution of the command on multiple threads. Defaults to N=2. + **Version history:** 2.8.0 - added\ 3.0.0 - add `--processes` for parallelization -3.3.0 - options changed +3.3.0 - options changed\ +3.5.0 - add `--batch-size` -| Option | Description | -| :--- | :--- | -| `--concurrency N` | Parallelize execution of the command on multiple threads. Defaults to N=2. | -| `--only INDEX` | Specify an index name [`accounts`, `tags`, `statuses`] to create or update only that index. | + +--- ## Settings CLI {#settings} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/settings_cli.rb" caption="lib/mastodon/settings\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/settings_cli.rb" caption="lib/mastodon/settings_cli.rb" >}} + + +--- + ### `tootctl settings registrations open` {#settings-registrations-open} @@ -510,6 +823,10 @@ Opens registrations. **Version history:**\ 2.6.0 - added + +--- + + ### `tootctl settings registrations close` {#settings-registrations-close} Closes registrations. @@ -517,9 +834,31 @@ Closes registrations. **Version history:**\ 2.6.0 - added + +--- + + +### `tootctl settings registrations approved` {#settings-registrations-approved} + +Set registration to require approval. + +**Version history:**\ +3.5.2 - added + +`--require_reason` +: If true, users must enter a reason when registering. + + +--- + + ## Statuses CLI {#statuses} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/statuses\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/statuses_cli.rb" >}} + + +--- + ### `tootctl statuses remove` {#statuses-remove} @@ -527,29 +866,38 @@ Remove unreferenced statuses from the database, such as statuses that came from This is a computationally heavy procedure that creates extra database indices before commencing, and removes them afterward. +`--days N` +: How old statuses have to be before they are removed. Defaults to 90. + +`--skip-media-remove` +: Skips removing the media, in case S3 errors out. Defaults to false. + **Version history:**\ 2.8.0 - added\ -3.1.3 - added `--skip-media-remove` +3.1.3 - added `--skip-media-remove`\ +3.5.0 - now removes orphaned records and performs additional cleanup tasks + + +--- -| Option | Description | -| :--- | :--- | -| `--days` | How old statuses have to be before they are removed. Defaults to 90. | -| `--skip-media-remove` | Skips removing the media, in case S3 errors out. Defaults to false. | ## Upgrade CLI {#upgrade} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/upgrade_cli.rb" caption="lib/mastodon/upgrade\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/upgrade_cli.rb" caption="lib/mastodon/upgrade_cli.rb" >}} + + +--- + ### `tootctl upgrade storage-schema` {#upgrade-storage-schema} Upgrade the storage schema to store all non-local media resources in a top-level cache directory. WARNING: This is optional, and only for deployments made before v3.1.4. This command can incur massive object storage costs due to moving potentially terabytes of data. +`--verbose` +: Print additional information while task is processing. + +`--dry-run` +: Print expected results only, without performing any actions. + **Version history:**\ -3.1.4 - added - -| Option | Description | -| :--- | :--- | -| `--verbose` | Print additional information while task is processing. | -| `--dry-run` | Print expected results only, without performing any actions. | - - +3.1.4 - added \ No newline at end of file diff --git a/content/en/admin/troubleshooting.md b/content/en/admin/troubleshooting.md index 304f1c88..3099d97e 100644 --- a/content/en/admin/troubleshooting.md +++ b/content/en/admin/troubleshooting.md @@ -9,7 +9,7 @@ menu: ## **I see an error page that says something went wrong. How do I find out what’s wrong?** -All error messages with stack traces are written to the system log. When using systemd, the logs of each systemd service can be browsed with `journalctl -u mastodon-web` \(substitute with the correct service name\). When using Docker, it’s similar: `docker logs mastodon_web_1` \(substitute with the correct container name\). +All error messages with stack traces are written to the system log. When using systemd, the logs of each systemd service can be browsed with `journalctl -u mastodon-web` (substitute with the correct service name). When using Docker, it’s similar: `docker logs mastodon_web_1` (substitute with the correct container name). Specific details of server-side errors are _never_ displayed to the public, as they can reveal what your setup looks like internally and give attackers clues how to get in, or how to abuse the system more efficiently. diff --git a/content/en/admin/troubleshooting/index-corruption.md b/content/en/admin/troubleshooting/index-corruption.md index 4394d672..78a2ef61 100644 --- a/content/en/admin/troubleshooting/index-corruption.md +++ b/content/en/admin/troubleshooting/index-corruption.md @@ -11,7 +11,7 @@ A somewhat common configuration issue can lead to index corruption throughout th ## Locale data and collation {#explanation} -Textual values in the database, such as usernames, or toot identifiers, are compared using so-called collation rules defining how characters are ordered and how to change their case. +Textual values in the database, such as usernames, or status identifiers, are compared using so-called collation rules defining how characters are ordered and how to change their case. When setting up a database, Mastodon will use the database server's default locale settings, including the default collation rules, which often is defined by the operating system's settings. Unfortunately, in late 2018, a `glibc` update changed the collation rules for many locales, which means databases using an affected locale would now order textual values differently. diff --git a/content/en/admin/upgrading.md b/content/en/admin/upgrading.md index 3962bb55..2497f1ba 100644 --- a/content/en/admin/upgrading.md +++ b/content/en/admin/upgrading.md @@ -7,10 +7,10 @@ menu: --- {{< hint style="info" >}} -When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). Please mind that running unreleased code from the `master` branch, while possible, is not recommended. +When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/mastodon/mastodon/releases). Please mind that running unreleased code from the `master` branch, while possible, is not recommended. {{< /hint >}} -Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). The page will contain a **changelog** describing everything you need to know about what's different, as well as **specific upgrade instructions**. +Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the [GitHub releases page](https://github.com/mastodon/mastodon/releases). The page will contain a **changelog** describing everything you need to know about what's different, as well as **specific upgrade instructions**. To begin, switch to the `mastodon` user: diff --git a/content/en/api/guidelines.md b/content/en/api/guidelines.md new file mode 100644 index 00000000..3cc4585a --- /dev/null +++ b/content/en/api/guidelines.md @@ -0,0 +1,134 @@ +--- +title: Guidelines and best practices +description: Things to keep in mind when implementing a Mastodon app. +menu: + docs: + weight: 10 + parent: api +--- + +## Login {#login} + +**The user must be able to login to any Mastodon server from the app**. This means you must ask for the server's domain and use the app registrations API to dynamically obtain OAuth2 credentials. + +{{< page-ref page="client/authorized" >}} + +{{< page-relref ref="methods/oauth" caption="oauth methods" >}} + +{{< page-relref ref="api/oauth-scopes" caption="OAuth scopes" >}} + +## Usernames {#username} + +**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, for example, by displaying their `acct` somewhere. Note that `acct` is equal to `username` for local users, and equal to `username@domain` for remote users. + +## Handling and sorting IDs {#id} + +Vanilla Mastodon entity IDs are generated as integers and cast to string. However, this does not mean that IDs _are_ integers, nor should they be cast to integer! Doing so can lead to broken client apps due to integer overflow, so **always treat IDs as strings.** + +With that said, because IDs are string representations of numbers, they can still be sorted chronologically very easily by doing the following: + +1. Sort by size. Newer statuses will have longer IDs. +2. Sort lexically. Newer statuses will have at least one digit that is higher when compared positionally. + +## Paginating through API responses {#pagination} + +Many API methods allow you to paginate for more information, using parameters such as `limit`, `max_id`, `min_id`, and `since_id`. However, some of these API methods operate on entity IDs that are not publicly exposed in the API response, and are only known to the backend and the database. (This is usually the case for entities that reference other entities, such as Follow entities which reference Accounts, or Favourite entities which reference Statuses, etc.) + +To get around this, Mastodon may return links to a "prev" and "next" page. These links are made available via the HTTP `Link` header on the response. Consider the following fictitious API call: + +```http +GET https://mastodon.social/api/v1/endpoint HTTP/1.1 +Authorization: Bearer token + +Link: ; rel="next", ; rel="prev" +[ + { + // some Entity + }, + // more Entities in an Array +] +``` + +In this case, you may retrieve the `Link` header and parse it for links to the older or newer page. Keep in mind the following rules: + +- The links will be returned all via one `Link` header, separated by a comma and a space (`, `) +- Each link consists of a URL and a link relation, separated by a semicolon and a space (`; `) +- The URL will be surrounded by angle brackets (`<>`), and the link relation will be surrounded by double quotes (`""`) and prefixed with `rel=`. +- The value of the link relation will be either `prev` or `next`. + +Following the `next` link should show you older results. Following the `prev` link should show you newer results. + +## Formatting {#formatting} + +Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. See [HTML Sanitization]({{< relref "spec/activitypub#sanitization" >}}) for more details. You may expect these tags to appear in the content: + +* `

` +* `
` +* `` +* `` + +{{< page-relref ref="spec/activitypub#sanitization" caption="ActivityPub > HTML Sanitization" >}} + +### Mentions, hashtags, and custom emoji {#tags} + +Mentions and hashtags are `` tags. Custom emoji remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "entities/Status" >}}), which can be matched to a particular tag. + +{{< page-relref ref="entities/Status" caption="Status entity" >}} + +{{< page-relref ref="entities/Status#mentions" caption="Status#mentions" >}} + +{{< page-relref ref="entities/Status#tags" caption="Status#tags" >}} + +{{< page-relref ref="entities/Status#emojis" caption="Status#emojis" >}} + +### Link shortening {#links} + +Links in Mastodon are not shortened using URL shorteners, and the usage of URL shorteners is heavily discouraged. URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this: + +```html + + + example.com/page + + +``` + +The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long; otherwise it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup; instead, you are expected to insert it yourself if you need it in your app. + +## Filters {#filters} + +### Server-side filtering (v2, Mastodon 4.0 and above) {#server-filtered} + +If a filter applies to a Status, a corresponding FilterResult will be included in the `filtered` attribute. Clients should check this attribute for any matches and use them to apply the intended filter action. + +However, client implementations may still want to perform their own rule matching client-side, as this would allow retroactively apply filter changes without re-fetching posts from the server. When doing so, they should take care to not ignore `filtered` entries for which there are other attributes than `keyword_matches`, so as to handle extensions of the filtering system (e.g. `status_matches`). + +Matched filters need to be filtered based on context (`home`, `notifications`, `public`, `thread` or `profile`) and expiration date. + +When at least one active matched filter has `hide` for `filter_action`, the post should not be shown at all. Otherwise, if at least one active matched filter has `warn` for `filter_action`, the post should be hidden with a warning, and the user should be able to reveal the post after being informed of which filters matched (identified by `title` rather than the exact matched keywords). + +For extension purposes, unknown values for `filter_action` should be treated as `warn`. + +### Client-side filtering (v1, prior to Mastodon 4.0) {#client-filtered} + +Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for `home` and `notifications` contexts, but **anything else is still up to the client to filter**! If a status is somehow not removed by an `irreversible` filter, the client should still filter it. + +Expired filters are not deleted by the server. They should no longer be applied, but they are still stored by the server, as users may update the expiry time to re-enable the filter. It is up to users to delete those filters eventually, if they wish to do so. + +If `whole_word` is true, the client app should do the following: + +* Define ‘word constituent characters’ for your app. In the official implementation, it’s `[A-Za-z0-9_]` in JavaScript, and `[[:word:]]` in Ruby. Ruby uses the POSIX character class (Letter | Mark | Decimal_Number | Connector_Punctuation). +* If the phrase starts with a word character, and if the previous character before matched range is a word character, its matched range should be treated to not match. +* If the phrase ends with a word character, and if the next character after matched range is a word character, its matched range should be treated to not match. + +Please check `app/javascript/mastodon/selectors/index.js` and `app/lib/feed_manager.rb` in the Mastodon source code for more details. + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/javascript/mastodon/selectors/index.js" caption="app/javascript/mastodon/selectors/index.js" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/feed_manager.rb" caption="app/lib/feed_manager.rb" >}} + +## Focal points for cropping media thumbnails {#focal-points} + +Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. See this [guide on how focal points are defined](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point). In summary, floating points range from -1.0 to 1.0, left-to-right or bottom-to-top. (0,0) is the center of the image. (0.5, 0.5) would be in the center of the upper-right quadrant. (-0.5, -0.5) would be in the center of the lower-left quadrant. For reference, thumbnails in the Mastodon frontend are most commonly 16:9. + +{{< figure src="/assets/focal-points.jpg" caption="A demonstration of various focal points and their coordinates." >}} \ No newline at end of file diff --git a/content/en/api/oauth-scopes.md b/content/en/api/oauth-scopes.md index d14d1697..91550cd4 100644 --- a/content/en/api/oauth-scopes.md +++ b/content/en/api/oauth-scopes.md @@ -3,7 +3,7 @@ title: OAuth Scopes description: Defining what you have permission to do with the API menu: docs: - weight: 10 + weight: 20 parent: api --- @@ -11,7 +11,7 @@ menu: The API is divided up into access scopes. The scopes are hierarchical, i.e. if you have access to `read`, you automatically have access to `read:accounts`. **It is recommended that you request as little as possible for your application.** -Multiple scopes can be requested at the same time: During app creation with the `scopes` param, and during the authorization phase with the `scope` query param \(space-separate the scopes\). +Multiple scopes can be requested at the same time: During app creation with the `scopes` param, and during the authorization phase with the `scope` query param (space-separate the scopes). {{< hint style="info" >}} Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon’s own REST API uses the more appropriate `scopes`. @@ -25,11 +25,12 @@ The set of scopes saved during app creation must include all the scopes that you - 0.9.0 - read, write, follow - 2.4.0 - push -- 2.4.3 - granular scopes [https://github.com/tootsuite/mastodon/pull/7929](https://github.com/tootsuite/mastodon/pull/7929) -- 2.6.0 - read:reports deprecated \(unused stub\) [https://github.com/tootsuite/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f](https://github.com/tootsuite/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f) -- 2.6.0 - write:conversations added [https://github.com/tootsuite/mastodon/pull/9009](https://github.com/tootsuite/mastodon/pull/9009) -- 2.9.1 - Admin scopes added [https://github.com/tootsuite/mastodon/pull/9387](https://github.com/tootsuite/mastodon/pull/9387) -- 3.1.0 - Bookmark scopes added +- 2.4.3 - granular scopes [#7929](https://github.com/mastodon/mastodon/pull/7929) +- 2.6.0 - read:reports deprecated (unused stub) [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f) +- 2.6.0 - write:conversations added [#9009](https://github.com/mastodon/mastodon/pull/9009) +- 2.9.1 - Admin scopes added [#9387](https://github.com/mastodon/mastodon/pull/9387) +- 3.1.0 - Bookmark scopes added [#7107](https://github.com/mastodon/mastodon/pull/7107) +- 4.0.3 - Added admin scopes for blocks and allows [#20918](https://github.com/mastodon/mastodon/pull/20918) ## List of scopes @@ -37,12 +38,45 @@ The set of scopes saved during app creation must include all the scopes that you Grants access to read data. Requesting `read` will also grant child scopes shown in the left column of the table below. +* `read` + * `read:accounts` + * `read:blocks` + * `read:bookmarks` + * `read:favourites` + * `read:filters` + * `read:follows` + * `read:lists` + * `read:mutes` + * `read:notifications` + * `read:search` + * `read:statuses` + ### `write` {#write} Grants access to write data. Requesting `write` will also grant child scopes shown in the right column of the table below. +* `write` + * `write:accounts` + * `write:blocks` + * `write:bookmarks` + * `write:conversations` + * `write:favourites` + * `write:filters` + * `write:follows` + * `write:lists` + * `write:media` + * `write:mutes` + * `write:notifications` + * `write:reports` + * `write:statuses` + ### `follow` {#follow} +{{< hint style="danger" >}} +**Deprecated**\ +This scope has been deprecated in 3.5.0 and newer. You should instead request the child scopes individually, or request read/write permission as needed. +{{< /hint >}} + Grants access to manage relationships. Requesting `follow` will also grant the following child scopes, shown in bold in the table: * `read:blocks`, `write:blocks` @@ -51,18 +85,28 @@ Grants access to manage relationships. Requesting `follow` will also grant the f ### `push` {#push} -Grants access to [Web Push API subscriptions.]({{< relref "../methods/notifications/push.md" >}}) Added in Mastodon 2.4.0. +Grants access to [Web Push API subscriptions.]({{< relref "methods/push" >}}) Added in Mastodon 2.4.0. ### Admin scopes {#admin} -Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available \(note that there is no singular `admin` scope\): +Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available (note that there is no singular `admin` scope): * `admin:read` * `admin:read:accounts` * `admin:read:reports` + * `admin:read:domain_allows` + * `admin:read:domain_blocks` + * `admin:read:ip_blocks` + * `admin:read:email_domain_blocks` + * `admin:read:canonical_email_blocks` * `admin:write` * `admin:write:accounts` * `admin:write:reports` + * `admin:write:domain_allows` + * `admin:write:domain_blocks` + * `admin:write:ip_blocks` + * `admin:write:email_domain_blocks` + * `admin:write:canonical_email_blocks` ## Granular scopes {#granular} @@ -87,4 +131,8 @@ Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes | :--- | :--- | | admin:read:accounts | admin:write:accounts | | admin:read:reports | admin:write:reports | - +| admin:read:domain_allows | admin:write:domain_allows | +| admin:read:domain_blocks | admin:write:domain_blocks | +| admin:read:ip_blocks | admin:write:ip_blocks | +| admin:read:email_domain_blocks | admin:write:email_domain_blocks | +| admin:read:canonical_email_blocks | admin:write:canonical_email_blocks | \ No newline at end of file diff --git a/content/en/api/rate-limits.md b/content/en/api/rate-limits.md index a983c2d7..81ee404f 100644 --- a/content/en/api/rate-limits.md +++ b/content/en/api/rate-limits.md @@ -1,31 +1,49 @@ --- title: Rate limits -description: Defining how often you can hit the REST API +description: Defining how often you can call the REST API menu: docs: - weight: 20 + weight: 30 parent: api --- +## Headers + Rate limit information is returned in the response headers: -|Header|Description| -| :--- | :--- | -|`X-RateLimit-Limit`|Number of requests permitted per time period| -|`X-RateLimit-Remaining`|Number of requests you can still make| -|`X-RateLimit-Reset`|Timestamp when your rate limit will reset| +`X-RateLimit-Limit` +: Number of requests permitted per time period + +`X-RateLimit-Remaining` +: Number of requests you can still make + +`X-RateLimit-Reset` +: Timestamp when your rate limit will reset {{< hint style="info" >}} -Mind that an API method can be subject to multiple overlapping rate limits. The headers return information about the one you are closest to exceeding. +An API method can be subject to multiple overlapping rate limits. The headers return information about the one you are closest to exceeding. {{}} -Here is a list of various rate limits: +## Limits -|Endpoint|Bucket|Time period|Limit|Limit type| -| :--- | :--- | :--- | :--- | :--- | -|`* /api/*`|Account access|5 minutes|300|Account| -|`* /api/*`|IP access|5 minutes|300|IP| -|`POST /api/v1/accounts`|App sign-up|30 minutes|5|IP| -|`POST /api/v1/media`|Uploading|30 minutes|30|Account| -|`DELETE /api/v1/statuses/:id`|Deletion|30 minutes|30|Account| -|`POST /api/v1/statuses/:id/unreblog`|Deletion|30 minutes|30|Account| +By default, the following limits are hardcoded: + +### Per account + +All endpoints and methods can be called 300 times within 5 minutes. + +#### Uploading media + +`POST /api/v1/media` can be called 30 times within 30 minutes. + +#### Deleting statuses + +Either `DELETE /api/v1/statuses/:id` or `POST /api/v1/statuses/:id/unreblog` can be called 30 times within 30 minutes. + +### Per IP + +All endpoints and methods can be called 300 times within 5 minutes. + +#### Creating accounts + +`POST /api/v1/accounts` can be called 5 times within 30 minutes. diff --git a/content/en/client/authorized.md b/content/en/client/authorized.md index 7c3b4f3c..0e877fbe 100644 --- a/content/en/client/authorized.md +++ b/content/en/client/authorized.md @@ -11,7 +11,7 @@ menu: When we registered our app and when we will authorize our user, we need to define what exactly our generated token will have permission to do. This is done through the use of OAuth scopes. Each API method has an associated scope, and can only be called if the token being used for authorization has been generated with the corresponding scope. -Scopes must be a subset. When we created our app, we specified `read write follow push` -- we could simply request all available scopes by specifying `read write follow push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it. +Scopes must be a subset. When we created our app, we specified `read write follow push` -- we could request all available scopes by specifying `read write follow push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it. ## **Example authorization code flow** {#flow} @@ -19,11 +19,11 @@ This is similar to the authentication flow from before, but this time, we need t ### Client ID and secret {#client} -First, if you have not already registered a client application, then see [Creating our application]({{< relref "token.md#creating-our-application" >}}) on the previous page or go directly to [POST /api/v1/apps]({{< relref "../methods/apps.md#create-an-application" >}}) for the full documentation of that method. We will need the `client_id` and `client_secret` for our application. +First, if you have not already registered a client application, then see [Creating our application]({{< relref "client/token#creating-our-application" >}}) on the previous page or go directly to [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for the full documentation of that method. We will need the `client_id` and `client_secret` for our application. ### Authorize the user {#login} -To authorize a user, request [GET /oauth/authorize]({{< relref "../methods/apps/oauth.md#authorize-a-user" >}}) in a browser with the following query parameters: +To authorize a user, request [GET /oauth/authorize]({{< relref "methods/oauth#authorize" >}}) in a browser with the following query parameters: ```bash https://mastodon.example/oauth/authorize @@ -35,13 +35,13 @@ https://mastodon.example/oauth/authorize Note the following: -* `client_id` and `client_secret` were obtained when registering our application. -* `scope` must be a subset of our registered app's registered scopes. It is a good idea to only request what you need. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for more information. +* `client_id` was obtained when registering our application. +* `scope` must be a subset of our registered app's registered scopes. It is a good idea to only request what you need. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information. * `redirect_uri` is one of the URIs we registered with our app. We are still using "out of band" for this example, which means we will have to manually copy and paste the resulting code, but if you registered your application with a URI that you control, then the code will be returned as a query parameter `code` and can be logged by your request handler. See the response section of the API method documentation for more information on this. ### Obtain the token {#token} -Now that we have an authorization `code`, let's obtain an access token that will authenticate our requests as the authorized user. To do so, use [POST /oauth/token]({{< relref "../methods/apps/oauth.md#obtain-a-token" >}}) like before, but pass the authorization code we just obtained: +Now that we have an authorization `code`, let's obtain an access token that will authenticate our requests as the authorized user. To do so, use [POST /oauth/token]({{< relref "methods/oauth#token" >}}) like before, but pass the authorization code we just obtained: ```bash curl -X POST \ @@ -59,9 +59,9 @@ Note the following: * `client_id` and `client_secret` were provided in the response text when you registered your application. * `redirect_uri` must be one of the URIs defined when registering the application. * We are requesting a `grant_type` of `authorization_code`, which still defaults to giving us the `read` scope. However, while authorizing our user, we requested a certain `scope` -- pass the exact same value here. -* The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user]({{< relref "authorized.md#authorize-the-user" >}}) step. +* The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user]({{< relref "client/authorized#authorize-the-user" >}}) step. -The response of this method is a [Token]({{< relref "../entities/token.md" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth \(i.e., one that is not publicly accessible\). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify\_credentials]({{< relref "../methods/accounts/#verify-account-credentials" >}}): +The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify\_credentials]({{< relref "methods/accounts#verify_credentials" >}}): ```bash curl \ @@ -69,7 +69,7 @@ curl \ https://mastodon.example/api/v1/accounts/verify_credentials ``` -If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Account]({{< relref "../entities/account.md" >}}) entity, with the `source` parameter included. +If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Account]({{< relref "entities/account" >}}) entity, with the `source` parameter included. ## Performing actions as the authorized user {#actions} @@ -77,48 +77,48 @@ With our OAuth token for the authorized user, we can now perform any action as t ### Publish and delete statuses {#statuses} -* See [POST /api/v1/statuses]({{< relref "../methods/statuses/#publish-new-status" >}}) for how to create statuses. - * See [/api/v1/media]({{< relref "../methods/statuses/media.md" >}}) for creating media attachments. - * See [/api/v1/scheduled\_statuses]({{< relref "../methods/statuses/scheduled_statuses.md" >}}) for managing scheduled statuses. +* See [POST /api/v1/statuses]({{< relref "methods/statuses#create" >}}) for how to create statuses. + * See [/api/v1/media]({{< relref "methods/media" >}}) for creating media attachments. + * See [/api/v1/scheduled\_statuses]({{< relref "methods/scheduled_statuses" >}}) for managing scheduled statuses. ### Interact with timelines {#timelines} -* See [/api/v1/timelines]({{< relref "../methods/timelines/" >}}) for accessing timelines. -* See [/api/v1/markers]({{< relref "../methods/timelines/markers.md" >}}) for saving and loading positions in timelines. -* See [/api/v1/statuses]({{< relref "../methods/statuses/" >}}) for performing actions on statuses. - * See [/api/v1/polls]({{< relref "../methods/statuses/polls.md" >}}) for viewing and voting on polls. -* See [/api/v1/lists]({{< relref "../methods/timelines/lists.md" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list\_id]({{< relref "../methods/timelines/#list-timeline" >}}). -* See [/api/v1/conversations]({{< relref "../methods/timelines/conversations.md" >}}) for obtaining direct conversations. -* See [/api/v1/favourites]({{< relref "../methods/accounts/favourites.md" >}}) for listing favourites. -* See [/api/v1/bookmarks]({{< relref "../methods/accounts/bookmarks.md" >}}) for listing bookmarks. +* See [/api/v1/timelines]({{< relref "methods/timelines" >}}) for accessing timelines. +* See [/api/v1/markers]({{< relref "methods/markers" >}}) for saving and loading positions in timelines. +* See [/api/v1/statuses]({{< relref "methods/statuses" >}}) for performing actions on statuses. + * See [/api/v1/polls]({{< relref "methods/polls" >}}) for viewing and voting on polls. +* See [/api/v1/lists]({{< relref "methods/lists" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list\_id]({{< relref "methods/timelines#list" >}}). +* See [/api/v1/conversations]({{< relref "methods/conversations" >}}) for obtaining direct conversations. +* See [/api/v1/favourites]({{< relref "methods/favourites" >}}) for listing favourites. +* See [/api/v1/bookmarks]({{< relref "methods/bookmarks" >}}) for listing bookmarks. ### Interact with other users {#accounts} -* See [/api/v1/accounts]({{< relref "../methods/accounts/" >}}) for performing actions on other users. -* See [/api/v1/follow\_requests]({{< relref "../methods/accounts/follow_requests.md" >}}) for handling follow requests. -* See [/api/v1/mutes]({{< relref "../methods/accounts/mutes.md" >}}) for listing mutes. -* See [/api/v1/blocks]({{< relref "../methods/accounts/blocks.md" >}}) for listing blocks. +* See [/api/v1/accounts]({{< relref "methods/accounts" >}}) for performing actions on other users. +* See [/api/v1/follow\_requests]({{< relref "methods/follow_requests" >}}) for handling follow requests. +* See [/api/v1/mutes]({{< relref "methods/mutes" >}}) for listing mutes. +* See [/api/v1/blocks]({{< relref "methods/blocks" >}}) for listing blocks. ### Receive notifications {#notifications} -* See [/api/v1/notifications]({{< relref "../methods/notifications/" >}}) for managing a user's notifications. -* See [/api/v1/push]({{< relref "../methods/notifications/push.md" >}}) for subscribing to push notifications. +* See [/api/v1/notifications]({{< relref "methods/notifications" >}}) for managing a user's notifications. +* See [/api/v1/push]({{< relref "methods/push" >}}) for subscribing to push notifications. ### Discovery features {#discovery} -* See [/api/v2/search]({{< relref "../methods/search.md" >}}) for querying resources. -* See [/api/v1/suggestions]({{< relref "../methods/accounts/suggestions.md" >}}) for suggested accounts to follow. +* See [/api/v2/search]({{< relref "methods/search#v2" >}}) for querying resources. +* See [/api/v1/suggestions]({{< relref "methods/suggestions" >}}) for suggested accounts to follow. ### Use safety features {#safety} -* See [/api/v1/filters]({{< relref "../methods/accounts/filters.md" >}}) for managing filtered keywords. -* See [/api/v1/domain\_blocks]({{< relref "../methods/accounts/domain_blocks.md" >}}) for managing blocked domains. -* See [/api/v1/reports]({{< relref "../methods/accounts/reports.md" >}}) for creating reports. -* See [/api/v1/admin]({{< relref "../methods/admin.md" >}}) for moderator actions. +* See [/api/v1/filters]({{< relref "methods/filters" >}}) for managing filtered keywords. +* See [/api/v1/domain\_blocks]({{< relref "methods/domain_blocks" >}}) for managing blocked domains. +* See [/api/v1/reports]({{< relref "methods/reports" >}}) for creating reports. +* See [/api/v1/admin]({{< relref "methods/admin" >}}) for moderator actions. ### Manage account info {#manage} -* See [/api/v1/endorsements]({{< relref "../methods/accounts/endorsements.md" >}}) for managing a user profile's featured accounts. -* See [/api/v1/featured\_tags]({{< relref "../methods/accounts/featured_tags.md" >}}) for managing a user profile's featured hashtags. -* See [/api/v1/preferences]({{< relref "../methods/accounts/preferences.md" >}}) for reading user preferences. +* See [/api/v1/endorsements]({{< relref "methods/endorsements" >}}) for managing a user profile's featured accounts. +* See [/api/v1/featured\_tags]({{< relref "methods/featured_tags" >}}) for managing a user profile's featured hashtags. +* See [/api/v1/preferences]({{< relref "methods/preferences" >}}) for reading user preferences. diff --git a/content/en/client/guidelines.md b/content/en/client/guidelines.md deleted file mode 100644 index 84e06c38..00000000 --- a/content/en/client/guidelines.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Guidelines and best practices -description: Things to keep in mind when implementing a Mastodon app. -menu: - docs: - weight: 50 - parent: client ---- - -## Login {#login} - -**The user must be able to login to any Mastodon server from the app**. This means you must ask for the server's domain and use the app registrations API to dynamically obtain OAuth2 credentials. - -## Usernames {#username} - -**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, by e.g. displaying their `acct` somewhere. Note that `acct` is equal to username for local users, and equal to username@domain for remote users. - -## Handling and sorting IDs {#id} - -Vanilla Mastodon entity IDs are generated as integers and cast to string. However, this does not mean that IDs _are_ integers, nor should they be cast to integer! Doing so can lead to broken client apps due to integer overflow, so **always treat IDs as strings.** - -With that said, because IDs are string representations of numbers, they can still be sorted chronologically very easily by doing the following: - -1. Sort by size. Newer statuses will have longer IDs. -2. Sort lexically. Newer statuses will have at least one digit that is higher when compared positionally. - -## Formatting {#formatting} - -Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. You may expect these tags to appear in the content: `

`, `
`, ``, ``. See [HTML Sanitization]({{< relref "../spec/activitypub.md#html-sanitization" >}}) for more details. - -### Mentions, hashtags, and custom emoji {#tags} - -Mentions and hashtags are `` tags. Custom emoji remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "../entities/status.md" >}}), which can be matched to a particular tag. See [Status > Rendering attributes]({{< relref "../entities/status.md#rendering-attributes" >}}) for more information. - -### Link shortening {#links} - -Links in Mastodon are not shortened using URL shorteners, and the usage of URL shorteners is heavily discouraged. URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this: - -```markup - - - example.com/page - - -``` - -The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long, otherwise it will have an `ellipsis` class. No ellipsis \(`…`\) character is inserted in the markup, instead, you are expected to insert it yourself if you need it in your app. - -## Filters {#filters} - -Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for home and notifications context, but anything else is still up to the client to filter! - -Expired filters are not deleted by the server. They should no longer be applied but they are still stored by the server, as users may update the expiry time to re-enable the filter. It is up to users to delete those filters eventually. - diff --git a/content/en/client/intro.md b/content/en/client/intro.md index 8060da79..e3d98abd 100644 --- a/content/en/client/intro.md +++ b/content/en/client/intro.md @@ -20,7 +20,7 @@ REST API endpoints can be called with certain HTTP methods, and more than one me * **PUT** \| **PATCH**: Update a resource. * **DELETE**: Removes a resource. -Your favorite programming language probably has a utility or library to make HTTP requests. For the purposes of this section, the cURL utility will be used for examples, which is a command-line utility included with many operating systems by default \(as `curl`\). +Your favorite programming language probably has a utility or library to make HTTP requests. For the purposes of this section, the cURL utility will be used for examples, which is a command-line utility included with many operating systems by default (as `curl`). With cURL, the default HTTP method is GET, but you can specify the type of request to make by using the `--request` or `-X` flag; for example, `curl -X POST` will send a POST request instead of a GET request. You may also want to use the `-i` flag to include additional HTTP headers that may be returned as part of the response where relevant. @@ -34,7 +34,7 @@ Query strings, form data, and JSON submitted via POST body are equally understoo ### Query strings {#query-strings} -Simply request the URL, but append query strings to the end. Query strings can be appended by first typing ? and then appending them in the form of parameter=value. Multiple query strings can be appended by separating them with &. For example: +Request the URL, but append query strings to the end. Query strings can be appended by first typing ? and then appending them in the form of parameter=value. Multiple query strings can be appended by separating them with &. For example: ```bash curl https://mastodon.example/endpoint?q=test&n=0 @@ -75,7 +75,7 @@ curl -X POST \ ## Data types {#types} -### Multiple values \(Array\) {#array} +### Multiple values (Array) {#array} An array parameter must encoded using bracket notation, e.g. `array[]=foo&array[]=bar` would be translated into the following: @@ -88,13 +88,13 @@ array = [ As JSON, arrays are formatted like so: -```javascript +```json { "array": ["foo", "bar"] } ``` -### Nested parameters \(Hash\) {#hash} +### Nested parameters (Hash) {#hash} Some parameters need to be nested. For that, bracket notation must also be used. For example, `source[privacy]=public&source[language]=en` would be translated into: @@ -107,7 +107,7 @@ source = { As JSON, hashes are formatted like so: -```javascript +```json { "source": { "privacy": "public", @@ -116,7 +116,7 @@ As JSON, hashes are formatted like so: } ``` -### True-or-false \(Booleans\) {#boolean} +### True-or-false (Booleans) {#boolean} A boolean value is considered false for the values `0`, `f`, `F`, `false`, `FALSE`, `off`, `OFF`, considered to not be provided for empty strings, and considered to be true for all other values. When using JSON data, use the literals `true`, `false`, and `null` instead. diff --git a/content/en/client/libraries.md b/content/en/client/libraries.md index 352a918c..b3337ce7 100644 --- a/content/en/client/libraries.md +++ b/content/en/client/libraries.md @@ -7,11 +7,11 @@ menu: parent: client --- -## Apex \(Salesforce\) {#apex-salesforce} +## Apex (Salesforce) {#apex-salesforce} * [apex-mastodon](https://github.com/tzmfreedom/apex-mastodon) -## C\# \(.NET Standard\) {#c-net-standard} +## C\# (.NET Standard) {#c-net-standard} * [Mastodot](https://github.com/yamachu/Mastodot) * [Mastonet](https://github.com/glacasa/Mastonet) @@ -57,11 +57,11 @@ menu: * [masto.js](https://github.com/neet/masto.js) * [libodonjs](https://github.com/Zatnosk/libodonjs) -## JavaScript \(Browser\) {#javascript-browser} +## JavaScript (Browser) {#javascript-browser} * [mastodon.js](https://github.com/Kirschn/mastodon.js) -## JavaScript \(Node.js\) {#javascript-node-js} +## JavaScript (Node.js) {#javascript-node-js} * [node-mastodon](https://github.com/jessicahayley/node-mastodon) * [mastodon-api](https://github.com/vanita5/mastodon-api) @@ -90,7 +90,7 @@ menu: ## Ruby {#ruby} -* [mastodon-api](https://github.com/tootsuite/mastodon-api) +* [mastodon-api](https://github.com/mastodon/mastodon-api) ## Rust {#rust} diff --git a/content/en/client/public.md b/content/en/client/public.md index e2794bba..e8c9c3af 100644 --- a/content/en/client/public.md +++ b/content/en/client/public.md @@ -19,7 +19,7 @@ Examples will be written using the fictional Mastodon website, mastodon.example, Let's take a look at one of the most basic use cases for public data from Mastodon -- the public timelines. -We can try to request [GET /api/v1/timelines/public]({{< relref "../../methods/timelines.md" >}}) like so: +We can try to request [GET /api/v1/timelines/public]({{< relref "methods/timelines" >}}) like so: ```bash curl https://mastodon.example/api/v1/timelines/public @@ -33,32 +33,32 @@ curl https://mastodon.example/api/v1/timelines/public?limit=2 Our response should be more manageable this time. We can parse or beautify this JSON with our chosen utility, and we should see that the response looks something like this: -```javascript +```json [ { "id": "103206804533200177", "created_at": "2019-11-26T23:27:31.000Z", - ... + // ... "visibility": "public", - ... + // ... }, { "id": "103206804086086361", "created_at": "2019-11-26T23:27:32.000Z", - ... + // ... "visibility": "public", - ... + // ... } ] ``` -We can do similarly for hashtags by calling [GET /api/v1/timelines/tag/:hashtag]({{< relref "../../methods/timelines.md#hashtag-timeline" >}}) -- here, the colon means that this part of the endpoint is a path parameter. In the case of :hashtag, this means we use the hashtag's name \(and once again, a limit of 2\): +We can do similarly for hashtags by calling [GET /api/v1/timelines/tag/:hashtag]({{< relref "methods/timelines#tag" >}}) -- here, the colon means that this part of the endpoint is a path parameter. In the case of :hashtag, this means we use the hashtag's name (and once again, a limit of 2): ```bash curl https://mastodon.example/api/v1/timelines/tag/cats?limit=2 ``` -We should once again see 2 statuses have been returned in a JSON array of [Status]({{< relref "../entities/status.md" >}}) entities. We can parse the JSON by array, then by object. If we were using Python, our code might look something like this: +We should once again see 2 statuses have been returned in a JSON array of [Status]({{< relref "entities/status" >}}) entities. We can parse the JSON by array, then by object. If we were using Python, our code might look something like this: ```python import requests @@ -78,17 +78,17 @@ Parsing JSON and using it in your program is outside of the scope of this tutori [MastoVue](https://mastovue.glitch.me) is an example of an application that lets you browse public timelines. {{< /hint >}} -## Fetching public accounts and statuses {#toots} +## Fetching public accounts and statuses {#posts} Now that we are familiar with how to make requests and how to handle responses, you can experiment with more public data. The following methods may be of interest: -* Once you know an account's id, you can use [GET /api/v1/accounts/:id]({{< relref "../../methods/accounts.md" >}}) to view the [Account]({{< relref "../entities/account.md" >}}) entity. - * To view public statuses posted by that account, you can use [GET /api/v1/accounts/:id/statuses]({{< relref "../../methods/statuses.md" >}}) and parse the resulting array of [Status]({{< relref "../entities/status.md" >}}) entities. -* Once you know a status's id, you can use [GET /api/v1/statuses/:id]({{< relref "../../methods/statuses.md#view-specific-status" >}}) to view the Status entity. - * You can also use [GET /api/v1/statuses/:id/reblogged\_by]({{< relref "../../methods/statuses.md#boosted-by" >}}) to view who boosted that status, - * or [GET /api/v1/statuses/:id/favourited\_by]({{< relref "../../methods/statuses.md#favourited-by" >}}) to view who favourited that status. - * Requesting [GET /api/v1/statuses/:id/context]({{< relref "../../methods/statuses.md#parent-and-child-statuses" >}}) will show you the ancestors and descendants of that status in the tree that is the conversational thread. - * If the status has a poll attached, you can use [GET /api/v1/polls/:id]({{< relref "../../methods/statuses/polls.md" >}}) to view the poll separately. +* Once you know an account's id, you can use [GET /api/v1/accounts/:id]({{< relref "methods/accounts" >}}) to view the [Account]({{< relref "entities/account" >}}) entity. + * To view public statuses posted by that account, you can use [GET /api/v1/accounts/:id/statuses]({{< relref "methods/statuses" >}}) and parse the resulting array of [Status]({{< relref "entities/status" >}}) entities. +* Once you know a status's id, you can use [GET /api/v1/statuses/:id]({{< relref "methods/statuses#get-one" >}}) to view the Status entity. + * You can also use [GET /api/v1/statuses/:id/reblogged\_by]({{< relref "methods/statuses#boosted_by" >}}) to view who boosted that status, + * or [GET /api/v1/statuses/:id/favourited\_by]({{< relref "methods/statuses#favourited_by" >}}) to view who favourited that status. + * Requesting [GET /api/v1/statuses/:id/context]({{< relref "methods/statuses#context" >}}) will show you the ancestors and descendants of that status in the tree that is the conversational thread. + * If the status has a poll attached, you can use [GET /api/v1/polls/:id]({{< relref "methods/polls" >}}) to view the poll separately. IDs of accounts and statuses are local to the Mastodon website's database and will differ for each Mastodon website. @@ -96,12 +96,12 @@ IDs of accounts and statuses are local to the Mastodon website's database and wi One last thing you can do with anonymous requests is to view information about the Mastodon website. -* View general information with [GET /api/v1/instance]({{< relref "../../methods/instance.md#fetch-instance" >}}), - * view its peers with [GET /api/v1/instance/peers]({{< relref "../../methods/instance.md#list-of-connected-domains" >}}) or - * its weekly activity with [GET /api/v1/instance/activity]({{< relref "../../methods/instance.md#weekly-activity" >}}), or to - * list all custom emoji available with [GET /api/v1/custom\_emojis]({{< relref "../../methods/instance/custom_emojis.md#custom-emoji" >}}). -* See [GET /api/v1/directory]({{< relref "../../methods/instance/directory.md#view-profile-directory" >}}) for a directory of all available profiles. -* See [GET /api/v1/trends]({{< relref "../../methods/instance/trends.md#trending-tags" >}}) for currently trending hashtags. +* View general information with [GET /api/v1/instance]({{< relref "methods/instance#fetch-instance" >}}), + * view its peers with [GET /api/v1/instance/peers]({{< relref "methods/instance#peers" >}}) or + * its weekly activity with [GET /api/v1/instance/activity]({{< relref "methods/instance#activity" >}}), or to + * list all custom emoji available with [GET /api/v1/custom\_emojis]({{< relref "methods/custom_emojis" >}}). +* See [GET /api/v1/directory]({{< relref "methods/directory" >}}) for a directory of all available profiles. +* See [GET /api/v1/trends]({{< relref "methods/trends" >}}) for currently trending hashtags. {{< hint style="info" >}} For a practical example of what you can do with just instance data, see [emojos.in](https://emojos.in/), which lets you preview all custom emoji at a given instance. diff --git a/content/en/client/token.md b/content/en/client/token.md index b8206a2e..f84af186 100644 --- a/content/en/client/token.md +++ b/content/en/client/token.md @@ -9,9 +9,9 @@ menu: ## Authentication and authorization {#auth} -Up until this point, we've been working with publicly available information, but not all information is public. Some information requires permission before viewing it, in order to audit who is requesting that information \(and to potentially revoke or deny access\). +Up until this point, we've been working with publicly available information, but not all information is public. Some information requires permission before viewing it, in order to audit who is requesting that information (and to potentially revoke or deny access). -This is where [OAuth]({{< relref "../spec/oauth.md" >}}) comes in. OAuth is a mechanism for generating access tokens which can be used to _authenticate \(verify\)_ that a request is coming from a specific client, and ensure that the requested action is _authorized \(allowed\)_ by the server's access control policies. +This is where [OAuth]({{< relref "spec/oauth" >}}) comes in. OAuth is a mechanism for generating access tokens which can be used to _authenticate (verify)_ that a request is coming from a specific client, and ensure that the requested action is _authorized (allowed)_ by the server's access control policies. ## Creating our application {#app} @@ -29,13 +29,13 @@ curl -X POST \ In the above example, we specify the client name and website, which will be shown on statuses if applicable. But more importantly, note the following two parameters: * `redirect_uris` has been set to the "out of band" token generation, which means that any generated tokens will have to be copied and pasted manually. The parameter is called `redirect_uris` because it is possible to define more than one redirect URI, but when generating the token, we will need to provide a URI that is included within this list. -* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for more information. +* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information. -We should see an Application entity returned, but for now we only care about client\_id and client\_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "../../methods/apps.md#create-an-application" >}}) for more details on registering applications. +We should see an Application entity returned, but for now we only care about client\_id and client\_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for more details on registering applications. ## Example authentication code flow {#flow} -Now that we have an application, let's obtain an access token that will authenticate our requests as that client application. To do so, use [POST /oauth/token]({{< relref "../../methods/apps/oauth.md#obtain-a-token" >}}) like so: +Now that we have an application, let's obtain an access token that will authenticate our requests as that client application. To do so, use [POST /oauth/token]({{< relref "methods/oauth#token" >}}) like so: ```bash curl -X POST \ @@ -52,7 +52,7 @@ Note the following: * `redirect_uri` must be one of the URIs defined when registering the application. * We are requesting a `grant_type` of `client_credentials`, which defaults to giving us the `read` scope. -The response of this method is a [Token]({{< relref "../entities/token.md" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth \(i.e., one that is not publicly accessible\). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify\_credentials]({{< relref "../methods/apps.md#verify-your-app-works" >}}): +The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify\_credentials]({{< relref "methods/apps#verify_credentials" >}}): ```bash curl \ @@ -60,9 +60,9 @@ curl \ https://mastodon.example/api/v1/apps/verify_credentials ``` -If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Application]({{< relref "../entities/application.md" >}}) entity. +If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Application]({{< relref "entities/application" >}}) entity. ## What we can do with authentication {#methods} -With our authenticated client application, we can view relations of an account with [GET /api/v1/accounts/:id/following]({{< relref "../methods/accounts.md#following" >}}) and [GET /api/v1/accounts/:id/followers]({{< relref "../methods/accounts.md#followers" >}}). Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work. +With our authenticated client application, we can view relations of an account with [GET /api/v1/accounts/:id/following]({{< relref "methods/accounts#following" >}}) and [GET /api/v1/accounts/:id/followers]({{< relref "methods/accounts#followers" >}}). Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work. diff --git a/content/en/dev/code.md b/content/en/dev/code.md index 7fa3b632..69d9303d 100644 --- a/content/en/dev/code.md +++ b/content/en/dev/code.md @@ -17,45 +17,62 @@ The following overview should not be seen as complete or authoritative, but as a #### Ruby {#ruby} -| Path | Description | -| :--- | :--- | -| `app/controllers` | Code that binds business logic to templates | -| `app/helpers` | Code that can be used from views, i.e. common operations | -| `app/lib` | Code that doesn’t fit in the other categories | -| `app/models` | Code that represents data entities | -| `app/serializers` | Code that generates JSON from models | -| `app/services` | Complex logical operations involving multiple models | -| `app/views` | Templates for generating HTML or other output | -| `app/workers` | Code that executes outside the request-response cycle | -| `spec` | Automated test suite | +`app/controllers` +: Code that binds business logic to templates + +`app/helpers` +: Code that can be used from views, i.e. common operations + +`app/lib` +: Code that doesn’t fit in the other categories + +`app/models` +: Representation of data entities and their associated methods + +`app/policies` +: Permission checks and other validations, before calling related methods + +`app/serializers` +: Code that generates JSON from models + +`app/services` +: Complex logical operations involving multiple models + +`app/views` +: Templates for generating HTML or other output + +`app/workers` +: Code that executes outside the request-response cycle + +`spec` +: Automated test suite #### JavaScript {#javascript} -| Path | Description | -| :--- | :--- | -| `app/javascript/mastodon` | Code for the multi-column React.js application | -| `app/javascript/packs` | Code for non-React.js pages | +`app/javascript/mastodon` +: Code for the frontend React.js application + +`app/javascript/packs` +: Code for non-React.js pages #### CSS and other assets {#assets} -| Path | Description | -| :--- | :--- | -| `app/javascript/images` | Images | -| `app/javascript/styles` | Code that turns into CSS via Sass | +`app/javascript/images` +: Images + +`app/javascript/styles` +: Code that turns into CSS via Sass #### Localizations {#localizations} -| Path | Description | -| :--- | :--- | -| `config/locales` | Server-side localizations in the YML format | -| `app/javascript/mastodon/locales` | Client-side localizations in the JSON format | +`config/locales` +: Server-side localizations in the YML format -### Localization maintenance {#localization-maintenance} +`app/javascript/mastodon/locales` +: Client-side localizations in the JSON format All locale files are normalized to ensure consistent formatting and key order, which minimizes changesets in version control. -| Command | Description | -| :--- | :--- | -| `i18n-tasks normalize` | Normalize server-side translations | -| `yarn run manage:translations` | Normalize client-side translations | +- Run `bundle exec i18n-tasks normalize` to normalize server-side translations +- Run `yarn run manage:translations` to normalize client-side translations diff --git a/content/en/dev/routes.md b/content/en/dev/routes.md index e056bc4d..3c13d32d 100644 --- a/content/en/dev/routes.md +++ b/content/en/dev/routes.md @@ -7,7 +7,7 @@ menu: parent: dev --- -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/config/routes.rb" caption="config/routes.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/config/routes.rb" caption="config/routes.rb" >}} ## Explanation of routes {#routes} @@ -67,7 +67,7 @@ Maps to HTTP DELETE. Handled by the \#destroy action in a controller. ### /.well-known/host-meta {#host-meta} -Extensible Resource Descriptor \(XRD\). Advertises existence of Webfinger. +Extensible Resource Descriptor (XRD). Advertises existence of Webfinger. ### /.well-known/nodeinfo {#nodeinfo} @@ -75,7 +75,7 @@ Maps to NodeInfo 2.0 endpoint at `/nodeinfo/2.0`, used for advertising software ### /.well-know/webfinger {#webfinger} -Used for discovering ActivityPub actor id. See [Spec compliance > WebFinger]({{< relref "../spec/webfinger.md" >}}) for more information. +Used for discovering ActivityPub actor id. See [Spec compliance > WebFinger]({{< relref "spec/webfinger" >}}) for more information. ### /.well-known/change-password {#change-password} @@ -94,8 +94,8 @@ The sections below this point are under construction. * `/users/username` = user URI * `/users/username/remote_follow` = remote follow dialog * `/users/username/statuses/id` = status URI -* `/@username` = "toots" tab -* `/@username/with_replies` = "toots and replies" tab +* `/@username` = "posts" tab +* `/@username/with_replies` = "posts and replies" tab * `/@username/media` = "media" tab * `/@username/tagged/:hashtag` = tagged statuses by user * `/@username/:status_id` = status permalink @@ -113,95 +113,95 @@ The sections below this point are under construction. * /api/oembed * /api/proofs * /api/v1 - * [statuses]({{< relref "../methods/statuses/" >}}) \[create, show, destroy\] - * reblogged\_by \[index\] - * favourited\_by \[index\] - * reblog \[create\] - * unreblog \[POST reblog\#destroy\] - * favourite \[create\] - * unfavourite \[POST favourites\#destroy\] - * bookmark \[create\] - * unbookmark \[POST bookmarks\#destroy\] - * mute \[create\] - * unmute \[POST mutes\#destroy\] - * pin \[create\] - * unpin \[POST pins\#destroy\] - * context \[GET\] - * [timelines]({{< relref "../methods/timelines/" >}}) - * home \[show\] - * public \[show\] - * tag \[show\] - * list \[show\] - * [streaming]({{< relref "../methods/timelines/streaming.md" >}}) \[index\] - * [custom\_emojis]({{< relref "../methods/instance/custom_emojis.md" >}}) \[index\] - * [suggestions]({{< relref "../methods/accounts/suggestions.md" >}}) \[index, destroy\] - * [scheduled\_statuses]({{< relref "../methods/statuses/scheduled_statuses.md" >}}) \[index, show, update, destroy\] - * [preferences]({{< relref "../methods/accounts/preferences.md" >}}) \[index\] - * [conversations]({{< relref "../methods/timelines/conversations.md" >}}) \[index, destroy\] - * read \[POST\] - * [media]({{< relref "../methods/statuses/media.md" >}}) \[create, update\] - * [blocks]({{< relref "../methods/accounts/blocks.md" >}}) \[index\] - * [mutes]({{< relref "../methods/accounts/mutes.md" >}}) \[index\] - * [favourites]({{< relref "../methods/accounts/favourites.md" >}}) \[index\] - * [bookmarks]({{< relref "../methods/accounts/bookmarks.md" >}}) \[index\] - * [reports]({{< relref "../methods/accounts/reports.md" >}}) \[create\] - * [trends]({{< relref "../methods/instance/trends.md" >}}) \[index\] - * [filters]({{< relref "../methods/accounts/filters.md" >}}) \[index, create, show, update, destroy\] - * [endorsements]({{< relref "../methods/accounts/endorsements.md" >}}) \[index\] - * [markers]({{< relref "../methods/timelines/markers.md" >}}) \[index, create\] - * [apps]({{< relref "../methods/apps/" >}}) \[create\] - * verify\_credentials \[credentials\#show\] - * [instance]({{< relref "../methods/instance/" >}}) \[show\] - * peers \[index\] - * activity \[show\] - * [domain\_blocks]({{< relref "../methods/accounts/domain_blocks.md" >}}) \[show, create, destroy\] - * [directory]({{< relref "../methods/instance/directory.md" >}}) \[show\] - * [follow\_requests]({{< relref "../methods/accounts/follow_requests.md" >}}) \[index\] - * authorize \[POST\] - * reject \[POST\] - * [notifications]({{< relref "../methods/notifications/" >}}) \[index, show\] - * clear \[POST\] - * dismiss \[POST\] - * [accounts]({{< relref "../methods/accounts/" >}}) - * verify\_credentials \[GET credentials\#show\] - * update\_credentials \[PATCH credentials\#update\] - * search \[show \(search\#index\)\] - * relationships \[index\] - * [accounts]({{< relref "../methods/accounts/" >}}) \[create, show\] - * statuses \[index accounts/statuses\] - * followers \[index accounts/follower\_accounts\] - * following \[index accounts/following\_accounts\] - * lists \[index accounts/lists\] - * identity\_proofs \[index accounts/identity\_proofs\] - * follow \[POST\] - * unfollow \[POST\] - * block \[POST\] - * unblock \[POST\] - * mute \[POST\] - * unmute \[POST\] - * pin \[POST\] - * unpin \[POST\] - * [lists]({{< relref "../methods/timelines/lists.md" >}}) \[index, create, show, update, destroy\] - * accounts \[POST accounts/pins\#destroy\] - * [featured\_tags]({{< relref "../methods/accounts/featured_tags.md" >}}) \[index, create, destroy\] - * suggestions \[GET suggestions\#index\] - * [polls]({{< relref "../methods/statuses/polls.md" >}}) \[create, show\] - * votes \[create polls/votes\] - * [push]({{< relref "../methods/notifications/push.md" >}}) - * subscription \[create, show, update, destroy\] - * [admin]({{< relref "../methods/admin.md" >}}) - * accounts \[index, show\] - * enable \[POST\] - * unsilence \[POST\] - * unsuspend \[POST\] - * approve \[POST\] - * reject \[POST\] - * action \[create account\_actions\] - * reports \[index, show\] - * assign\_to\_self \[POST\] - * unassign \[POST\] - * reopen \[POST\] - * resolve \[POST\] + * [statuses]({{< relref "methods/statuses" >}}) [create, show, destroy] + * reblogged\_by [index] + * favourited\_by [index] + * reblog [create] + * unreblog [POST reblog\#destroy] + * favourite [create] + * unfavourite [POST favourites\#destroy] + * bookmark [create] + * unbookmark [POST bookmarks\#destroy] + * mute [create] + * unmute [POST mutes\#destroy] + * pin [create] + * unpin [POST pins\#destroy] + * context [GET] + * [timelines]({{< relref "methods/timelines" >}}) + * home [show] + * public [show] + * tag [show] + * list [show] + * [streaming]({{< relref "methods/streaming" >}}) [index] + * [custom\_emojis]({{< relref "methods/custom_emojis" >}}) [index] + * [suggestions]({{< relref "methods/suggestions" >}}) [index, destroy] + * [scheduled\_statuses]({{< relref "methods/scheduled_statuses" >}}) [index, show, update, destroy] + * [preferences]({{< relref "methods/preferences" >}}) [index] + * [conversations]({{< relref "methods/conversations" >}}) [index, destroy] + * read [POST] + * [media]({{< relref "methods/media" >}}) [create, update] + * [blocks]({{< relref "methods/blocks" >}}) [index] + * [mutes]({{< relref "methods/mutes" >}}) [index] + * [favourites]({{< relref "methods/favourites" >}}) [index] + * [bookmarks]({{< relref "methods/bookmarks" >}}) [index] + * [reports]({{< relref "methods/reports" >}}) [create] + * [trends]({{< relref "methods/trends" >}}) [index] + * [filters]({{< relref "methods/filters" >}}) [index, create, show, update, destroy] + * [endorsements]({{< relref "methods/endorsements" >}}) [index] + * [markers]({{< relref "methods/markers" >}}) [index, create] + * [apps]({{< relref "methods/apps" >}}) [create] + * verify\_credentials [credentials\#show] + * [instance]({{< relref "methods/instance" >}}) [show] + * peers [index] + * activity [show] + * [domain\_blocks]({{< relref "methods/domain_blocks" >}}) [show, create, destroy] + * [directory]({{< relref "methods/directory" >}}) [show] + * [follow\_requests]({{< relref "methods/follow_requests" >}}) [index] + * authorize [POST] + * reject [POST] + * [notifications]({{< relref "methods/notifications" >}}) [index, show] + * clear [POST] + * dismiss [POST] + * [accounts]({{< relref "methods/accounts" >}}) + * verify\_credentials [GET credentials\#show] + * update\_credentials [PATCH credentials\#update] + * search [show (search\#index)] + * relationships [index] + * [accounts]({{< relref "methods/accounts" >}}) [create, show] + * statuses [index accounts/statuses] + * followers [index accounts/follower\_accounts] + * following [index accounts/following\_accounts] + * lists [index accounts/lists] + * identity\_proofs [index accounts/identity\_proofs] + * follow [POST] + * unfollow [POST] + * block [POST] + * unblock [POST] + * mute [POST] + * unmute [POST] + * pin [POST] + * unpin [POST] + * [lists]({{< relref "methods/lists" >}}) [index, create, show, update, destroy] + * accounts [POST accounts/pins\#destroy] + * [featured\_tags]({{< relref "methods/featured_tags" >}}) [index, create, destroy] + * suggestions [GET suggestions\#index] + * [polls]({{< relref "methods/polls" >}}) [create, show] + * votes [create polls/votes] + * [push]({{< relref "methods/push" >}}) + * subscription [create, show, update, destroy] + * [admin]({{< relref "methods/admin" >}}) + * accounts [index, show] + * enable [POST] + * unsilence [POST] + * unsuspend [POST] + * approve [POST] + * reject [POST] + * action [create account\_actions] + * reports [index, show] + * assign\_to\_self [POST] + * unassign [POST] + * reopen [POST] + * resolve [POST] * /api/v2 - * [search]({{< relref "../methods/search.md" >}}) \[GET search\#index\] + * [search]({{< relref "methods/search" >}}) [GET search\#index] diff --git a/content/en/dev/setup.md b/content/en/dev/setup.md index b29b3ce2..6c52096a 100644 --- a/content/en/dev/setup.md +++ b/content/en/dev/setup.md @@ -7,47 +7,99 @@ menu: parent: dev --- -{{< hint style="danger" >}} -This page is under construction. -{{< /hint >}} +## Quick start with Vagrant {#vagrant} -### Pre-requisites {#prerequisites} +For convenience, the Mastodon repository includes a Vagrantfile for quickly setting up a development environment without manual configuration. To use this development environment, install [Vagrant](https://vagrantup.com) using a binary executable or through your package manager. -You can follow the [pre-requisites instructions from the production guide](https://docs.joinmastodon.org/admin/install/), but do not create a `mastodon` user. You also don't have to install `nginx`, `certbot` and `python-certbot-nginx` as the development environment brings its own webserver. Setting up and running a development environment has been proven successful over WSL2 as well if you are on Windows. +Once you have Vagrant installed, for convenience, it is recommended to install a plugin to automatically update your machine's hosts file. This will allow you to access the dev environment at `http://mastodon.local` without manually editing the hosts file yourself. To do so: + +```sh +vagrant plugin install vagrant-hostsupdater +``` + +The virtual machine can then be started: + +```sh +vagrant up +``` + +Once the virtual machine has been started, you may launch the Foreman task executor to launch the various Mastodon processes: + +```sh +vagrant ssh -c "cd /vagrant && foreman start" +``` + +Once the Mastodon processes have fully started up, you can load `http://mastodon.local` in your browser to access the Mastodon instance within the VM. You can log in as the default admin user with the username `admin@mastodon.local` and the password `mastodonadmin`. + +Any changes to the source code will be reflected after saving your files. + +To reset the VM to a fresh state, you can destroy it and bring it up again: + +```sh +vagrant destroy +vagrant up +``` + +## Manual install from source {#manual} + +You can follow the [pre-requisites instructions from the production guide]({{}}), but do not create a `mastodon` user. You also don't have to install `nginx`, `certbot` and `python-certbot-nginx` as the development environment brings its own webserver. Setting up and running a development environment has been proven successful over WSL2 as well if you are on Windows. ### Setup {#setup} -Run following commands in the project directory `bundle install`, `yarn install`. +Run the following commands in the project directory: -In the development environment, Mastodon will use PostgreSQL as the currently signed-in Linux user using the `ident` method, which usually works out of the box. The one command you need to run is `rails db:setup` which will create the databases `mastodon_development` and `mastodon_test`, load the schema into them, and then create seed data defined in `db/seed.rb` in `mastodon_development`. The only seed data is an admin account with the credentials `admin@localhost:3000` / `mastodonadmin`. +```sh +bundle install +yarn install +``` -> Please keep in mind, by default Mastodon will run on port 3000. If you configure a different port for it, the generated admin account will use that number. +In the development environment, Mastodon will use PostgreSQL as the currently signed-in Linux user using the `ident` method. Ensure that you have created a Postgres user and database for your current signed-in user: -If `rails db:setup` gives you the Postgres error: +```sh +sudo -u postgres createuser $YOUR_USERNAME_HERE --createdb +``` - ActiveRecord::NoDatabaseError: FATAL: role "your_user_name" does not exist +You can now create the databases `mastodon_development` and `mastodon_test`, load the schema into them, and create seed data defined in `db/seeds/` into `mastodon_development`. -(where `your_user_name` is your username), then run: +```sh +rails db:setup +``` - sudo -u postgres createuser your_user_name --createdb +You can now launch `http://localhost:3000` in your browser and log in with the default admin user (`admin@localhost:3000` / `mastodonadmin`). -This will create the necessary Postgres user with the permission to create a database. +{{}} +By default, Mastodon will run on port 3000. If you configure a different port for it, the generated admin account will use that number as well. +{{}} ### Running {#running} -There are multiple processes that need to be run for the full set of Mastodon’s functionality, although they can be selectively omitted. To run all of them with just one command, you can install Foreman with `gem install foreman --no-document` and then use: +There are multiple processes that need to be run for the full set of Mastodon’s functionality, although they can be selectively omitted. To run all of them with just one command, you can install and use Foreman: -```text +```sh +gem install foreman --no-document foreman start ``` -In the Mastodon directory. This will start processes defined in `Procfile.dev`, which will give you: A Rails server, a Webpack server, a streaming API server, and Sidekiq. Of course, you can run any of those things stand-alone depending on your needs. +This will start processes defined in `Procfile.dev`, which will give you: A Rails server, a Webpack server, a streaming API server, and Sidekiq. Of course, you can run any of those things stand-alone depending on your needs. -### Testing {#testing} +## Useful commands for testing {#testing} -| Command | Description | -| :--- | :--- | -| `rspec` | Run the Ruby test suite | -| `yarn run test` | Run the JavaScript test suite | -| `rubocop` | Check the Ruby code for conformance with our code style | +`rspec` +: Run the Ruby test suite +`yarn run test` +: Run the JavaScript test suite + +`rubocop` +: Check the Ruby code for conformance with our code style + +## Updating your development instance {#update} + +`bundle install` +: Update Ruby gems and install any new dependencies + +`yarn install` +: Update Javascript packages and install any new dependencies + +`RAILS_ENV=development rails db:migrate` +: Run new database migrations for your development instance's database \ No newline at end of file diff --git a/content/en/entities/Account.md b/content/en/entities/Account.md new file mode 100644 index 00000000..0ed696ee --- /dev/null +++ b/content/en/entities/Account.md @@ -0,0 +1,442 @@ +--- +title: Account +description: Represents a user of Mastodon and their associated profile. +menu: + docs: + parent: entities +aliases: [ + "/entities/source/", + "/entities/Source/", + "/entities/field/", + "/entities/Field/", + "/entities/account", + "/entities/Account", + "/entities/credentialaccount", + "/entities/CredentialAccount", + "/entities/mutedaccount", + "/entities/MutedAccount", + "/api/entities/source/", + "/api/entities/Source/", + "/api/entities/field/", + "/api/entities/Field/", + "/api/entities/account", + "/api/entities/Account", + "/api/entities/credentialaccount", + "/api/entities/CredentialAccount", + "/api/entities/mutedaccount", + "/api/entities/MutedAccount", +] +--- + +## Example + +```json +{ + "id": "23634", + "username": "noiob", + "acct": "noiob@awoo.space", + "display_name": "ikea shark fan account", + "locked": false, + "bot": false, + "created_at": "2017-02-08T02:00:53.274Z", + "note": "

:ms_rainbow_flag:​ :ms_bisexual_flagweb:​ :ms_nonbinary_flag:​ #awoo#admin#bi#nonbinary#games@dzuk

", + "url": "https://awoo.space/@noiob", + "avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png", + "avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png", + "header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png", + "header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png", + "followers_count": 547, + "following_count": 404, + "statuses_count": 28468, + "last_status_at": "2019-11-17T00:02:23.693Z", + "emojis": [ + { + "shortcode": "ms_rainbow_flag", + "url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png", + "visible_in_picker": true + }, + { + "shortcode": "ms_bisexual_flag", + "url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png", + "visible_in_picker": true + }, + { + "shortcode": "ms_nonbinary_flag", + "url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png", + "visible_in_picker": true + } + ], + "fields": [ + { + "name": "Pronouns", + "value": "they/them", + "verified_at": null + }, + { + "name": "Alt", + "value": "@noiob", + "verified_at": null + }, + { + "name": "Bots", + "value": "@darksouls, @nierautomata, @fedi, code for @awoobot", + "verified_at": null + }, + { + "name": "Website", + "value": "http://shork.xyz}})\ +**Version history:**\ +2.4.0 - added + +### `bot` {#bot} + +**Description:** Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.\ +**Type:** Boolean\ +**Version history:**\ +2.4.0 - added + +### `group` {#group} + +**Description:** Indicates that the account represents a Group actor.\ +**Type:** Boolean\ +**Version history:**\ +3.1.0 - added + +### `discoverable` {#discoverable} + +**Description:** Whether the account has opted into discovery features such as the profile directory.\ +**Type:** {{}} Boolean\ +**Version history:**\ +3.1.0 - added + +### `moved` {{%optional%}} {#moved} + +**Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\ +**Type:** {{}} [Account]({{< relref "entities/Account" >}}), or null if the profile is supended.\ +**Version history:**\ +2.1.0 - added + +### `suspended` {{%optional%}} {#suspended} + +**Description:** An extra attribute returned only when an account is suspended.\ +**Type:** Boolean\ +**Version history:**\ +3.3.0 - added + +### `limited` {{%optional%}} {#limited} + +**Description:** An extra attribute returned only when an account is silenced. If true, indicates that the account should be hidden behing a warning screen.\ +**Type:** Boolean\ +**Version history:**\ +3.5.3 - added + +### `created_at` {#created_at} + +**Description:** When the account was created.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +0.1.0 - added +3.4.0 - now resolves to midnight instead of an exact time + +### `last_status_at` {#last_status_at} + +**Description:** When the most recent status was posted.\ +**Type:** {{}} String (ISO 8601 Date), or null if no statuses\ +**Version history:**\ +3.0.0 - added\ +3.1.0 - now returns date only, no time + +### `statuses_count` {#statuses_count} + +**Description:** How many statuses are attached to this account.\ +**Type:** Integer\ +**Version history:**\ +0.1.0 - added + +### `followers_count` {#followers_count} + +**Description:** The reported followers of this profile.\ +**Type:** Integer\ +**Version history:**\ +0.1.0 - added + +### `following_count` {#following_count} + +**Description:** The reported follows of this profile.\ +**Type:** Integer\ +**Version history:**\ +0.1.0 - added + +## CredentialAccount entity attributes {#CredentialAccount} + +```json +{ + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + "note": "

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

", + // ... + "source": { + "privacy": "public", + "sensitive": false, + "language": "", + "note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/trwnh or paypal\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence", + "fields": [ + { + "name": "Website", + "value": "https://trwnh.com", + "verified_at": "2019-08-29T04:14:55.571+00:00" + }, + { + "name": "Portfolio", + "value": "https://abdullahtarawneh.com", + "verified_at": "2021-02-11T20:34:13.574+00:00" + }, + { + "name": "Fan of:", + "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)", + "verified_at": null + }, + { + "name": "What to expect:", + "value": "talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.", + "verified_at": null + } + ], + "follow_requests_count": 5 + }, + // ... + "fields": [ + { + "name": "Website", + "value": "https://trwnh.com", + "verified_at": "2019-08-29T04:14:55.571+00:00" + }, + { + "name": "Portfolio", + "value": "https://abdullahtarawneh.com", + "verified_at": "2021-02-11T20:34:13.574+00:00" + }, + { + "name": "Fan of:", + "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)", + "verified_at": null + }, + { + "name": "What to expect:", + "value": "talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.", + "verified_at": null + } + ], + "role": { + "id": "-99", + "name": "", + "permissions": "65536", + "color": "", + "highlighted": false + } +} +``` + +### `source` {#source} + +**Description:** An extra attribute that contains source values to be used with API methods that [verify credentials]({{< relref "methods/accounts#verify_credentials" >}}) and [update credentials]({{< relref "methods/accounts#update_credentials" >}}).\ +**Type:** Hash\ +**Version history:**\ +2.4.0 - added + +#### `source[note]` {#source-note} + +**Description:** Profile bio, in plain-text instead of in HTML.\ +**Type:** String\ +**Version history:**\ +1.5.0 - added + +#### `source[fields]` {#source-fields} + +**Description:** Metadata about the account.\ +**Type:** Array of [Field](#Field)\ +**Version history:**\ +2.4.0 - added + +#### `source[privacy]` {#source-privacy} + +**Description:** The default post privacy to be used for new statuses.\ +**Type:** String (Enumerable, oneOf)\ +`public` = Public post\ +`unlisted` = Unlisted post\ +`private` = Followers-only post\ +`direct` = Direct post\ +**Version history:**\ +1.5.0 - added + +#### `source[sensitive]` {#source-sensitive} + +**Description:** Whether new statuses should be marked sensitive by default.\ +**Type:** Boolean\ +**Version history:**\ +1.5.0 - added + +#### `source[language]` {#source-language} + +**Description:** The default posting language for new statuses.\ +**Type:** String (ISO 639-1 language two-letter code) or empty string\ +**Version history:**\ +2.4.2 - added + +#### `source[follow_requests_count]` {#follow_requests_count} + +**Description:** The number of pending follow requests.\ +**Type:** Integer\ +**Version history:**\ +3.0.0 - added + +### `role` {#role} + +**Description:** The role assigned to the currently authorized user.\ +**Type:** [Role]({{< relref "entities/Role" >}})\ +**Version history:**\ +4.0.0 - added + +## MutedAccount entity attributes {#MutedAccount} + +### `mute_expires_at` {#mute_expires_at} + +**Description:** When a timed mute will expire, if applicable.\ +**Type:** {{}} String (ISO 8601 Datetime), or null if the mute is indefinite\ +**Version history:**\ +3.3.0 - added + +## Field entity attributes {#Field} + +### `name` {#name} + +**Description:** The key of a given field's key-value pair.\ +**Type:** String\ +**Version history:**\ +2.4.0 - added + +### `value` {#value} + +**Description:** The value associated with the `name` key.\ +**Type:** String (HTML)\ +**Version history:**\ +2.4.0 - added + +### `verified_at` {#verified_at} + +**Description:** Timestamp of when the server verified a URL value for a rel="me" link.\ +**Type:** {{}} String (ISO 8601 Datetime) if `value` is a verified URL. Otherwise, null.\ +**Version history:**\ +2.6.0 - added + +## See also + +{{< page-relref ref="methods/accounts" caption="accounts API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/serializers/rest/account_serializer.rb" caption="app/serializers/rest/account_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/serializers/rest/credential_account_serializer.rb" caption="app/serializers/rest/credential_account_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/serializers/rest/muted_account_serializer.rb" caption="app/serializers/rest/muted_account_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_Account.md b/content/en/entities/Admin_Account.md new file mode 100644 index 00000000..933bd385 --- /dev/null +++ b/content/en/entities/Admin_Account.md @@ -0,0 +1,213 @@ +--- +title: Admin::Account +description: Admin-level information about a given account. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-account", + "/entities/Admin-Account", + "/entities/admin_account", + "/entities/Admin_Account", + "/api/entities/admin-account", + "/api/entities/Admin-Account", + "/api/entities/admin_account", + "/api/entities/Admin_Account", +] +--- + +## Example + +```json +{ + "id": "108965278956942133", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T23:03:26.762Z", + "email": "admin@mastodon.local", + "ip": "192.168.42.1", + "role": { + "id": 3, + "name": "Owner", + "color": "", + "position": 1000, + "permissions": 1, + "highlighted": true, + "created_at": "2022-09-08T22:48:07.983Z", + "updated_at": "2022-09-08T22:48:07.983Z" + }, + "confirmed": true, + "suspended": false, + "silenced": false, + "disabled": false, + "approved": true, + "locale": null, + "invite_request": null, + "ips": [ + { + "ip": "192.168.42.1", + "used_at": "2022-09-15T01:38:58.851Z" + } + ], + "account": { + "id": "108965278956942133", + "username": "admin", + "acct": "admin", + "display_name": "", + "locked": false, + "bot": false, + "discoverable": null, + "group": false, + "created_at": "2022-09-08T00:00:00.000Z", + "note": "", + "url": "http://mastodon.local/@admin", + "avatar": "http://mastodon.local/avatars/original/missing.png", + "avatar_static": "http://mastodon.local/avatars/original/missing.png", + "header": "http://mastodon.local/headers/original/missing.png", + "header_static": "http://mastodon.local/headers/original/missing.png", + "followers_count": 0, + "following_count": 0, + "statuses_count": 0, + "last_status_at": null, + "emojis": [], + "fields": [] + } +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the account in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +2.9.1 - added + +### `username` {#username} + +**Description:** The username of the account.\ +**Type:** String\ +**Version history:**\ +2.9.1 - added + +### `domain` {#domain} + +**Description:** The domain of the account, if it is remote.\ +**Type:** {{}} String, or null for local accounts\ +**Version history:**\ +2.9.1 - added + +### `created_at` {#created_at} + +**Description:** When the account was first discovered.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +2.9.1 - added + +### `email` {#email} + +**Description:** The email address associated with the account.\ +**Type:** String\ +**Version history:**\ +2.9.1 - added + +### `ip` {#ip} + +**Description:** The IP address last used to login to this account.\ +**Type:** {{}} String\ +**Version history:**\ +2.9.1 - added +3.5.0 - return type changed from String to [Admin::Ip]({{< relref "entities/Admin_Ip" >}}) due to a bug +4.0.0 - bug fixed, return type is now a String again + +### `ips` {#ip} + +**Description:** All known IP addresses associated with this account.\ +**Type:** Array of [Admin::Ip]({{< relref "entities/Admin_Ip" >}})\ +**Version history:**\ +3.5.0 - added + +### `locale` {#locale} + +**Description:** The locale of the account.\ +**Type:** String (ISO 639 Part 1 two-letter language code)\ +**Version history:**\ +2.9.1 - added + +### `invite_request` {#invite_request} + +**Description:** The reason given when requesting an invite (for instances that require manual approval of registrations)\ +**Type:** {{}} String\ +**Version history:**\ +2.9.1 - added + +### `role` {#role} + +**Description:** The current role of the account.\ +**Type:** [Role]({{}})\ +**Version history:**\ +2.9.1 - added, returns a String (enumerable, oneOf `user` `moderator` `admin`) +4.0.0 - now uses Role entity + +### `confirmed` {#confirmed} + +**Description:** Whether the account has confirmed their email address.\ +**Type:** Boolean\ +**Version history:**\ +2.9.1 - added + +### `approved` {#approved} + +**Description:** Whether the account is currently approved.\ +**Type:** Boolean\ +**Version history:**\ +2.9.1 - added + +### `disabled` {#disabled} + +**Description:** Whether the account is currently disabled.\ +**Type:** Boolean\ +**Version history:**\ +2.9.1 - added + +### `silenced` {#silenced} + +**Description:** Whether the account is currently silenced. +**Type:** Boolean\ +**Version history:**\ +2.9.1 - added + +### `suspended` {#suspended} + +**Description:** Whether the account is currently suspended.\ +**Type:** Boolean\ +**Version history:**\ +2.9.1 - added + +### `account` {#account} + +**Description:** User-level information about the account.\ +**Type:** [Account]({{< relref "entities/account" >}})\ +**Version history:**\ +2.9.1 - added + +### `created_by_application_id` {{%optional%}} {#created_by_application_id} + +**Description:** The ID of the [Application]({{< relref "entities/application" >}}) that created this account, if applicable.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +2.9.1 - added + +### `invited_by_account_id` {{%optional%}} {#invited_by_account_id} + +**Description:** The ID of the [Account]({{< relref "entities/account" >}}) that invited this user, if applicable.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +2.9.1 - added + +## See also + +{{< page-relref ref="methods/admin/accounts" caption="admin/accounts API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/serializers/rest/admin/account_serializer.rb" caption="app/serializers/rest/admin/account_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_CanonicalEmailBlock.md b/content/en/entities/Admin_CanonicalEmailBlock.md new file mode 100644 index 00000000..d0506910 --- /dev/null +++ b/content/en/entities/Admin_CanonicalEmailBlock.md @@ -0,0 +1,48 @@ +--- +title: Admin::CanonicalEmailBlock +description: Represents a canonical email block (hashed). +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-canonicalemailblock", + "/entities/Admin-CanonicalEmailBlock", + "/entities/admin_canonicalemailblock", + "/entities/Admin_CanonicalEmailBlock", + "/api/entities/admin-canonicalemailblock", + "/api/entities/Admin-CanonicalEmailBlock", + "/api/entities/admin_canonicalemailblock", + "/api/entities/Admin_CanonicalEmailBlock", +] +--- + +## Example + +```json +{ + "id": "2", + "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c" +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the email block in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +### `canonical_email_hash` {#canonical_email_hash} + +**Description:** The SHA256 hash of the canonical email address.\ +**Type:** String (SHA256)\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="methods/admin/canonical_email_blocks" caption="admin/canonical_email_blocks API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/canonical_email_block_serializer.rb" caption="app/serializers/rest/admin/canonical_email_block_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_Cohort.md b/content/en/entities/Admin_Cohort.md new file mode 100644 index 00000000..6a79d665 --- /dev/null +++ b/content/en/entities/Admin_Cohort.md @@ -0,0 +1,135 @@ +--- +title: Admin::Cohort +description: Represents a retention metric. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-cohort", + "/entities/Admin-Cohort", + "/entities/admin_cohort", + "/entities/Admin_Cohort", + "/api/entities/admin-cohort", + "/api/entities/Admin-Cohort", + "/api/entities/admin_cohort", + "/api/entities/Admin_Cohort", +] +--- + +## Example + +Monthly retention data for the month of 2022-09, given that 2 users registered during 2022-09 and were active at least once during that month. + +```json +{ + "period": "2022-09-01T00:00:00+00:00", + "frequency": "month", + "data": [ + { + "date": "2022-09-01T00:00:00+00:00", + "rate": 1.0, + "value": "2" + } + ] +} +``` + +Daily retention data for the week between 2022-09-08 and 2022-09-14, given that 2 users registered on 2022-09-08 and 1 of those users stopped being active after 2022-09-09. + +```json +{ + "period": "2022-09-08T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-08T00:00:00+00:00", + "rate": 1.0, + "value": "2" + }, + { + "date": "2022-09-09T00:00:00+00:00", + "rate": 1.0, + "value": "2" + }, + { + "date": "2022-09-10T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + { + "date": "2022-09-11T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + { + "date": "2022-09-12T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + { + "date": "2022-09-13T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0.5, + "value": "1" + } + ] +}, +``` + +## Attributes + +### `period` {#period} + +**Description:** The timestamp for the start of the period, at midnight.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.5.0 - added + +### `frequency` {#frequency} + +**Description:** The size of the bucket for the returned data.\ +**Type:** String (Enumerable oneOf)\ +`day` = Daily buckets\ +`month` = Monthly buckets\ +**Version history:**\ +3.5.0 - added + +### `data` {#data} + +**Description:** Retention data for users who registered during the given period.\ +**Type:** Array of [CohortData](#CohortData)\ +**Version history:**\ +3.5.0 - added + +## CohortData entity attributes {#CohortData} + +### `date` {date} + +**Description:** The timestamp for the start of the bucket, at midnight.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.5.0 - added + +### `rate` {#rate} + +**Description:** The percentage rate of users who registered in the specified `period` and were active for the given `date` bucket.\ +**Type:** Number\ +**Version history:**\ +3.5.0 - added + +### `value` {#value} + +**Description:** How many users registered in the specified `period` and were active for the given `date` bucket.\ +**Type:** Integer\ +**Version history:**\ +3.5.0 - added + +## See also + +{{< page-relref ref="methods/admin/retention" caption="admin/retention API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/cohort_serializer.rb" caption="app/serializers/rest/admin/cohort_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_Dimension.md b/content/en/entities/Admin_Dimension.md new file mode 100644 index 00000000..1b4cc919 --- /dev/null +++ b/content/en/entities/Admin_Dimension.md @@ -0,0 +1,306 @@ +--- +title: Admin::Dimension +description: Represents qualitative data about the server. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-dimension", + "/entities/Admin-Dimension", + "/entities/admin_dimension", + "/entities/Admin_Dimension", + "/api/entities/admin-dimension", + "/api/entities/Admin-Dimension", + "/api/entities/admin_dimension", + "/api/entities/Admin_Dimension", +] +--- + +## Attributes + +### `key` {#key} + +**Description:** The unique keystring for the requested dimension.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +### `data` {#data} + +**Description:** The data available for the requested dimension.\ +**Type:** Array of Hash\ +**Version history:**\ +3.5.0 - added + +## Data attributes + +### `key` {#data-key} + +**Description:** The unique keystring for this data item.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +### `human_key` {#data-human_key} + +**Description:** A human-readable key for this data item.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +### `value` {#data-value} + +**Description:** The value for this data item.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +### `unit` {{%optional%}} {#data-unit} + +**Description:** The units associated with this data item's value, if applicable.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +### `human_value` {{%optional%}} {#data-human_value} + +**Description:** A human-readable formatted value for this data item.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +## Examples + +### `languages` {#languages} + +Count how many local statuses are posted in each language, then show dimensional data about how popular each language is. + +```json +{ + "key": "languages", + "data": [ + { + "key": "en", + "human_key": "English", + "value": "10" + }, + { + "key": "es", + "human_key": "Spanish", + "value": "1" + }, + // ... + ] +} +``` + +### `sources` {#sources} + +Count how many local statuses were authored by a given client, then show dimensional data about how popular each client is. + +```json +{ + "key": "sources", + "data": [ + { + "key": "web", + "human_key": "Website", + "value": "2" + }, + // ... + ] +} +``` + +### `servers` {#servers} + +Count how many statuses were posted from a given domain, then show dimensional data about the most popular remote servers. + +```json +{ + "key": "servers", + "data": [ + { + "key": "botsin.space", + "human_key": "botsin.space", + "value": "13738" + }, + { + "key": "mastodon.social", + "human_key": "mastodon.social", + "value": "8928" + }, + // ... + ] + } +``` + +### `space_usage` {#space_usage} + +Show dimensional data about how much space is used by each software in your server stack. + +```json +{ + "key": "space_usage", + "data": [ + { + "key": "postgresql", + "human_key": "PostgreSQL", + "value": "14924935", + "unit": "bytes", + "human_value": "14.2 MB" + }, + { + "key": "redis", + "human_key": "Redis", + "value": "1972544", + "unit": "bytes", + "human_value": "1.88 MB" + }, + { + "key": "media", + "human_key": "Media storage", + "value": "0", + "unit": "bytes", + "human_value": "0 Bytes" + } + ] +}, +``` + +### `software_versions` {#software_versions} + +Show dimensional data about which versions of software in your server stack you are using. + +```json +{ + "key": "software_versions", + "data": [ + { + "key": "mastodon", + "human_key": "Mastodon", + "value": "3.5.3", + "human_value": "3.5.3" + }, + { + "key": "ruby", + "human_key": "Ruby", + "value": "3.0.4p208", + "human_value": "3.0.4p208" + }, + { + "key": "postgresql", + "human_key": "PostgreSQL", + "value": "10.22", + "human_value": "10.22" + }, + { + "key": "redis", + "human_key": "Redis", + "value": "4.0.9", + "human_value": "4.0.9" + } + ] +} +``` + +### `tag_servers` {#tag_servers} + +Count how many statuses contain the trending tag with the given `id`, then show dimensional data about the most popular servers using that trending tag. + +```json +{ + "key": "tag_servers", + "data": [ + { + "key": "live.hatnix.net", + "human_key": "live.hatnix.net", + "value": "6" + }, + { + "key": "linuxrocks.online", + "human_key": "linuxrocks.online", + "value": "4" + } + ] +} +``` + +### `tag_languages` {#tag_languages} + +Count how many statuses contain the trending tag with the given `id`, then show dimensional data about the most popular languages for those statuses. + +```json +{ + "key": "tag_languages", + "data": [ + { + "key": "und", + "human_key": "und", + "value": "8" + }, + { + "key": "en", + "human_key": "English", + "value": "7" + }, + // ... + ] + } +``` + +### `instance_accounts` {#instance_accounts} + +Count how many followers each account from the given `domain` has, then show dimensional data about the most popular accounts from that remote server. + +```json +{ + "key": "instance_accounts", + "data": [ + { + "key": "fribbledom", + "human_key": "fribbledom", + "value": "33" + }, + { + "key": "ShugoWah", + "human_key": "ShugoWah", + "value": "26" + }, + // ... + ] +} +``` + +### `instance_languages` {#instance_languages} + +Count how many statuses from the given `domain` are posted in each language, then show dimensional data about how popular each language is on that remote server. + +```json +{ + "key": "instance_languages", + "data": [ + { + "key": "en", + "human_key": "English", + "value": "5848" + }, + { + "key": "de", + "human_key": "German", + "value": "155" + }, + // ... + ] +} +``` + +## See also + +{{< page-relref ref="methods/admin/dimensions" caption="admin/dimensions API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/dimension_serializer.rb" caption="app/serializers/rest/admin/dimension_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension.rb" caption="app/lib/admin/metrics/dimension.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension/" caption="app/lib/admin/metrics/dimension/" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_DomainAllow.md b/content/en/entities/Admin_DomainAllow.md new file mode 100644 index 00000000..69ecc1b4 --- /dev/null +++ b/content/en/entities/Admin_DomainAllow.md @@ -0,0 +1,56 @@ +--- +title: Admin::DomainAllow +description: Represents a domain allowed to federate. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-domainallow", + "/entities/Admin-DomainAllow", + "/entities/admin_domainallow", + "/entities/Admin_DomainAllow", + "/api/entities/admin-domainallow", + "/api/entities/Admin-DomainAllow", + "/api/entities/admin_domainallow", + "/api/entities/Admin_DomainAllow", +] +--- + +## Example + +```json +{ + "id": "1", + "domain": "mastodon.social", + "created_at": "2022-09-14T21:23:02.755Z" +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the DomainAllow in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +### `domain` {#domain} + +**Description:** The domain that is allowed to federate.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `created_at` {#created_at} + +**Description:** When the domain was allowed to federate.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref page="methods/admin/domain_allows" caption="admin/domain_allows API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_allows_serializer.rb" caption="app/serializers/rest/admin/domain_allows_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_DomainBlock.md b/content/en/entities/Admin_DomainBlock.md new file mode 100644 index 00000000..a1cf861a --- /dev/null +++ b/content/en/entities/Admin_DomainBlock.md @@ -0,0 +1,111 @@ +--- +title: Admin::DomainBlock +description: Represents a domain limited from federating. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-domainblock", + "/entities/Admin-DomainBlock", + "/entities/admin_domainblock", + "/entities/Admin_DomainBlock", + "/api/entities/admin-domainblock", + "/api/entities/Admin-DomainBlock", + "/api/entities/admin_domainblock", + "/api/entities/Admin_DomainBlock", +] +--- + +{{< hint style="danger" >}} +This page is under construction. +{{< /hint >}} + +## Example + +```json +{ + "id": "1", + "domain": "example.com", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the DomainBlock in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +### `domain` {#domain} + +**Description:** The domain that is not allowed to federate.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `created_at` {#created_at} + +**Description:** When the domain was blocked from federating.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +### `severity` {#severity} + +**Description:** The policy to be applied by this domain block.\ +**Type:** String (Enumerable oneOf)\ +`silence` = Account statuses from this domain will be hidden by default\ +`suspend` = All incoming data from this domain will be rejected\ +`noop` = Do nothing. Allows for rejecting media or reports\ +**Version history:**\ +4.0.0 - added + +### `reject_media` {#reject_media} + +**Description:** Whether to reject media attachments from this domain\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +### `reject_reports` {#reject_reports} + +**Description:** Whether to reject reports from this domain\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +### `private_comment` {#private_comment} + +**Description:** \ +**Type:** {{}} String\ +**Version history:**\ +4.0.0 - added + +### `public_comment` {#public_comment} + +**Description:** \ +**Type:** {{}} String\ +**Version history:**\ +4.0.0 - added + +### `obfuscate` {#obfuscate} + +**Description:** Whether to obfuscate public displays of this domain block\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref page="methods/admin/domain_blocks" caption="admin/domain_blocks API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_blocks_serializer.rb" caption="app/serializers/rest/admin/domain_blocks_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_EmailDomainBlock.md b/content/en/entities/Admin_EmailDomainBlock.md new file mode 100644 index 00000000..f436f35d --- /dev/null +++ b/content/en/entities/Admin_EmailDomainBlock.md @@ -0,0 +1,121 @@ +--- +title: Admin::EmailDomainBlock +description: Represents an email domain that cannot be used to sign up. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-emaildomainblock", + "/entities/Admin-EmailDomainBlock", + "/entities/admin_emaildomainblock", + "/entities/Admin_EmailDomainBlock", + "/api/entities/admin-emaildomainblock", + "/api/entities/Admin-EmailDomainBlock", + "/api/entities/admin_emaildomainblock", + "/api/entities/Admin_EmailDomainBlock", +] +--- + +## Example + +```json +{ + "id": "1", + "domain": "foo", + "created_at": "2022-11-16T06:09:36.176Z", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ] +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the EmailDomainBlock in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +### `domain` {#domain} + +**Description:** The email domain that is not allowed to be used for signups.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `created_at` {#created_at} + +**Description:** When the email domain was disallowed from signups.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +### `history` {#history} + +**Description:** Usage statistics for given days (typically the past week).\ +**Type:** Array of Hash\ +**Version history:**\ +4.0.0 - added + +#### `history[][day]` {#history-day} + +**Description:** UNIX timestamp on midnight of the given day.\ +**Type:** String (UNIX timestamp)\ +**Version history:**\ +4.0.0 - added + +#### `history[][accounts]` {#history-accounts} + +**Description:** The counted accounts signup attempts using that email domain within that day.\ +**Type:** String (cast from an integer)\ +**Version history:**\ +4.0.0 - added + +#### `history[][uses]` {#history-uses} + +**Description:** The counted IP signup attempts of that email domain within that day.\ +**Type:** String (cast from an integer)\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref page="methods/admin/email_domain_blocks" caption="admin/email_domain_blocks API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/email_domain_blocks_serializer.rb" caption="app/serializers/rest/admin/email_domain_blocks_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_Ip.md b/content/en/entities/Admin_Ip.md new file mode 100644 index 00000000..c577405d --- /dev/null +++ b/content/en/entities/Admin_Ip.md @@ -0,0 +1,48 @@ +--- +title: Admin::Ip +description: Represents an IP address associated with a user. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-ip", + "/entities/Admin-Ip", + "/entities/admin_ip", + "/entities/Admin_Ip", + "/api/entities/admin-ip", + "/api/entities/Admin-Ip", + "/api/entities/admin_ip", + "/api/entities/Admin_Ip", +] +--- + +## Example + +```json +{ + "ip": "192.168.42.1", + "used_at": "2022-09-15T01:38:58.851Z" +} +``` + +## Attributes + +### `ip` {#id} + +**Description:** The IP address.\ +**Type:** String (IP address)\ +**Version history:**\ +3.5.0 - added + +### `used_at` {#used_at} + +**Description:** The timestamp of when the IP address was last used for this account.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.5.0 - added + +## See also + +{{< page-relref ref="entities/Admin_Account#ips" caption="Admin::Account (`ips` attribute)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_serializer.rb" caption="app/serializers/rest/admin/ip_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_IpBlock.md b/content/en/entities/Admin_IpBlock.md new file mode 100644 index 00000000..53c2a6f8 --- /dev/null +++ b/content/en/entities/Admin_IpBlock.md @@ -0,0 +1,83 @@ +--- +title: Admin::IpBlock +description: Represents an IP address range that cannot be used to sign up. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-ipblock", + "/entities/Admin-IpBlock", + "/entities/admin_ipblock", + "/entities/Admin_IpBlock", + "/api/entities/admin-ipblock", + "/api/entities/Admin-IpBlock", + "/api/entities/admin_ipblock", + "/api/entities/Admin_IpBlock", +] +--- + +## Example + +```json +{ + "id": "1", + "ip": "8.8.8.8/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the DomainBlock in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +### `ip` {#ip} + +**Description:** The IP address range that is not allowed to federate.\ +**Type:** String (IP address and prefix)\ +**Version history:**\ +4.0.0 - added + +### `severity` {#severity} + +**Description:** The associated policy with this IP block.\ +**Type:** String (Enumerable, oneOf)\ +`sign_up_requires_approval` = Any signup from this IP range will create a pending account\ +`sign_up_block` = Any signup from this IP range will be rejected\ +`no_access` = Any activity from this IP range will be rejected entirely\ +**Version history:**\ +4.0.0 - added + +### `comment` {#comment} + +**Description:** The recorded reason for this IP block.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `created_at` {#created_at} + +**Description:** When the IP block was created.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +### `expires_at` {#expires_at} + +**Description:** When the IP block will expire.\ +**Type:** {{}} String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref page="methods/admin/ip_blocks" caption="admin/ip_blocks API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/ip_blocks_serializer.rb" caption="app/serializers/rest/admin/ip_blocks_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_Measure.md b/content/en/entities/Admin_Measure.md new file mode 100644 index 00000000..97105526 --- /dev/null +++ b/content/en/entities/Admin_Measure.md @@ -0,0 +1,787 @@ +--- +title: Admin::Measure +description: Represents quantitative data about the server. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-measure", + "/entities/Admin-Measure", + "/entities/admin_measure", + "/entities/Admin_Measure", + "/api/entities/admin-measure", + "/api/entities/Admin-Measure", + "/api/entities/admin_measure", + "/api/entities/Admin_Measure", +] +--- + +## Attributes + +### `key` {#key} + +**Description:** The unique keystring for the requested measure.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +### `unit` {#unit} + +**Description:** The units associated with this data item's value, if applicable.\ +**Type:** {{}} String or null\ +**Version history:**\ +3.5.0 - added + +### `total` {#total} + +**Description:** The numeric total associated with the requested measure.\ +**Type:** String (cast from integer)\ +**Version history:**\ +3.5.0 - added + +### `human_value` {{%optional%}} {#data-human_value} + +**Description:** A human-readable formatted value for this data item.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +### `previous_total` {{%optional%}} {#previous_total} + +**Description:** The numeric total associated with the requested measure, in the previous period. Previous period is calculated by subtracting the start_at and end_at dates, then offsetting both start and end dates backwards by the length of the time period.\ +**Type:** String (cast from integer)\ +**Version history:**\ +3.5.0 - added + +### `data` {#data} + +**Description:** The data available for the requested measure, split into daily buckets.\ +**Type:** Array of Hash\ +**Version history:**\ +3.5.0 - added + +#### `data[][date]` {#data-date} + +**Description:** Midnight on the requested day in the time period.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.5.0 - added + +#### `data[][value]` {#data-value} + +**Description:** The numeric value for the requested measure.\ +**Type:** String (cast from integer)\ +**Version history:**\ +3.5.0 - added + +## Examples + +### `active_users` + +Total active users on your instance within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "active_users", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00Z", + "value": "1" + }, + { + "date": "2022-09-18T00:00:00Z", + "value": "1" + }, + { + "date": "2022-09-19T00:00:00Z", + "value": "1" + }, + { + "date": "2022-09-20T00:00:00Z", + "value": "2" + }, + { + "date": "2022-09-21T00:00:00Z", + "value": "1" + } + ] +} +``` + +### `new_users` + +Users who joined your instance within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "new_users", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "1" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "1" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `interactions` + +Total interactions (favourites, boosts, replies) on local statuses within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "interactions", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00Z", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00Z", + "value": "0" + } + ] +} +``` + +### `opened_reports` + +Total reports filed within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "opened_reports", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] + } +``` + +### `resolved_reports` + +Total reports resolved within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "resolved_reports", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `tag_accounts` + +Total accounts who used a tag in at least one status within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "tag_accounts", + "unit": null, + "total": "1", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "1" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `tag_uses` + +Total statuses which used a tag within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "tag_uses", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "1" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "1" + } + ] +} +``` + +### `tag_servers` + +Total remote origin servers for statuses which used a tag within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "tag_servers", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_accounts` + +Total accounts originating from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "instance_accounts", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_media_attachments` + +Total space used by media attachments from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "instance_media_attachments", + "unit": "bytes", + "total": "0", + "human_value": "0 Bytes", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "" + } + ] +} +``` + +### `instance_reports` +Total reports filed against accounts from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "instance_reports", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_statuses` + +Total statuses originating from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "instance_statuses", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_follows` + +Total accounts from a remote domain followed by a local user within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "instance_follows", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +### `instance_followers` + +Total local accounts followed by accounts from a remote domain within the time period starting at 2022-09-14 and ending at 2022-09-22 + +```json +{ + "key": "instance_followers", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-15T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-16T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-17T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-18T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-19T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-20T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-21T00:00:00.000+00:00", + "value": "0" + }, + { + "date": "2022-09-22T00:00:00.000+00:00", + "value": "0" + } + ] +} +``` + +## See also + +{{< page-relref ref="methods/admin/dimensions" caption="admin/dimensions API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/measure_serializer.rb" caption="app/serializers/rest/admin/measure_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure.rb" caption="app/lib/admin/metrics/measure.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure/" caption="app/lib/admin/metrics/measure/" >}} \ No newline at end of file diff --git a/content/en/entities/Admin_Report.md b/content/en/entities/Admin_Report.md new file mode 100644 index 00000000..894d7a6a --- /dev/null +++ b/content/en/entities/Admin_Report.md @@ -0,0 +1,176 @@ +--- +title: Admin::Report +description: Admin-level information about a filed report. +menu: + docs: + parent: entities +aliases: [ + "/entities/admin-report", + "/entities/Admin-Report", + "/entities/admin_report", + "/entities/Admin_Report", + "/api/entities/admin-report", + "/api/entities/Admin-Report", + "/api/entities/admin_report", + "/api/entities/Admin_Report", +] +--- + +## Example + +```json +{ + "id": "1", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:23.085Z", + "updated_at": "2022-09-09T21:19:23.085Z", + "account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "target_account": { + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + "email": "goody@mastodon.local", + // ... + "account": { + "id": "108965430868193066", + "username": "goody", + "acct": "goody", + // ... + } + }, + "assigned_account": null, + "action_taken_by_account": null, + "statuses": [], + "rules": [] +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the report in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +2.9.1 - added + +### `action_taken` {#action_taken} + +**Description:** Whether an action was taken to resolve this report.\ +**Type:** Boolean\ +**Version history:**\ +2.9.1 - added + +### `action_taken_at` {#action_taken_at} + +**Description:** When an action was taken, if this report is currently resolved.\ +**Type:** {{}} String (ISO 8601 Datetime) or null\ +**Version history:**\ +2.9.1 - added + +### `category` {#category} + +**Description:** The category under which the report is classified.\ +**Type:** String (Enumerable oneOf)\ +`spam` = Malicious, fake, or repetitive content\ +`violation` = Violates one or more specific [`rules`](#rules)\ +`other` = The default (catch-all) category\ +**Version history:**\ +3.5.0 - added + +### `comment` {#comment} + +**Description:** An optional reason for reporting.\ +**Type:** String\ +**Version history:**\ +2.9.1 - added + +### `forwarded` {#forwarded} + +**Description:** Whether a report was forwarded to a remote instance.\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +### `created_at` {#created_at} + +**Description:** The time the report was filed.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +2.9.1 - added + +### `updated_at` {#updated_at} + +**Description:** The time of last action on this report.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +2.9.1 - added + +### `account` {#account} + +**Description:** The account which filed the report.\ +**Type:** [Admin::Account]({{< relref "entities/Admin_Account" >}})\ +**Version history:**\ +2.9.1 - added + +### `target_account` {#target_account} + +**Description:** The account being reported.\ +**Type:** [Admin::Account]({{< relref "entities/Admin_Account" >}})\ +**Version history:**\ +2.9.1 - added + +### `assigned_account` {#assigned_account} + +**Description:** The account of the moderator assigned to this report.\ +**Type:** {{}} [Admin::Account]({{< relref "entities/Admin_Account" >}}) or null\ +**Version history:**\ +2.9.1 - added + +### `action_taken_by_account` {#action_taken_by_account} + +**Description:** The account of the moderator who handled the report.\ +**Type:** {{}} [Admin::Account]({{< relref "entities/Admin_Account" >}}) or null\ +**Version history:**\ +2.9.1 - added + +### `statuses` {#statuses} + +**Description:** Statuses attached to the report, for context.\ +**Type:** Array of [Status]({{< relref "entities/Status" >}})\ +**Version history:**\ +2.9.1 - added + +### `rules` {#rules} + +**Description:** Rules attached to the report, for context.\ +**Type:** Array of [Rule]({{< relref "entities/Rule" >}})\ +**Version history:**\ +3.5.0 - added + +## See also + +{{< page-relref page="methods/admin/reports" caption="admin/reports API methods">}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/serializers/rest/admin/report_serializer.rb" caption="app/serializers/rest/admin/report_serializer.rb" >}} + + + diff --git a/content/en/entities/Announcement.md b/content/en/entities/Announcement.md new file mode 100644 index 00000000..aa58dde8 --- /dev/null +++ b/content/en/entities/Announcement.md @@ -0,0 +1,211 @@ +--- +title: Announcement +description: Represents an announcement set by an administrator. +menu: + docs: + parent: entities +aliases: [ + "/entities/announcement", + "/entities/Announcement", + "/api/entities/announcement", + "/api/entities/Announcement", +] +--- + +## Example +```json +{ + "id": "8", + "content": "

Looks like there was an issue processing audio attachments without embedded art since yesterday due to an experimental new feature. That issue has now been fixed, so you may see older posts with audio from other servers pop up in your feeds now as they are being finally properly processed. Sorry!

", + "starts_at": null, + "ends_at": null, + "all_day": false, + "published_at": "2020-07-03T01:27:38.726Z", + "updated_at": "2020-07-03T01:27:38.752Z", + "read": true, + "mentions": [], + "statuses": [], + "tags": [], + "emojis": [], + "reactions": [ + { + "name": "bongoCat", + "count": 9, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png" + }, + { + "name": "thonking", + "count": 1, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/098/690/original/a8d36edc4a7032e8.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/098/690/static/a8d36edc4a7032e8.png" + }, + { + "name": "AAAAAA", + "count": 1, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png" + }, + { + "name": "🤔", + "count": 1, + "me": true + } + ] +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the announcement in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +3.1.0 - added + +### `content` {#content} + +**Description:** The text of the announcement.\ +**Type:** String (HTML)\ +**Version history:**\ +3.1.0 - added + +### `starts_at` {#starts_at} + +**Description:** When the announcement will start.\ +**Type:** {{}} String (ISO 8601 Datetime) or null\ +**Version history:**\ +3.1.0 - added + +### `ends_at` {#ends_at} + +**Description:** When the announcement will end.\ +**Type:** {{}} String (ISO 8601 Datetime) or null\ +**Version history:**\ +3.1.0 - added + +### `published` {#published} + +**Description:** Whether the announcement is currently active.\ +**Type:** Boolean\ +**Version history:**\ +3.1.0 - added + +### `all_day` {#all_day} + +**Description:** Whether the announcement should start and end on dates only instead of datetimes. Will be false if there is no `starts_at` or `ends_at` time.\ +**Type:** Boolean\ +**Version history:**\ +3.1.0 - added + +### `published_at` {#created_at} + +**Description:** When the announcement was published.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.1.0 - added + +### `updated_at` {#updated_at} + +**Description:** When the announcement was last updated.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.1.0 - added + +### `read` {{%optional%}} {#read} + +**Description:** Whether the announcement has been read by the current user.\ +**Type:** Boolean\ +**Version history:**\ +3.1.0 - added + +### `mentions` {#mentions} + +**Description:** Accounts mentioned in the announcement text.\ +**Type:** Array of [Announcement::Account](#Account)\ +**Version history:**\ +3.1.0 - added + +### `statuses` {#statuses} + +**Description:** Statuses linked in the announcement text.\ +**Type:** Array of [Announcement::Status](#Status)\ +**Version history:**\ +3.1.0 - added + +### `tags` {#tags} + +**Description:** Tags linked in the announcement text.\ +**Type:** Array of [Status::Tag]({{< relref "entities/Status#Tag" >}})\ +**Version history:**\ +3.1.0 - added + +### `emojis` {#emojis} + +**Description:** Custom emoji used in the announcement text.\ +**Type:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\ +**Version history:**\ +3.1.0 - added + +### `reactions` {#reactions} + +**Description:** Emoji reactions attached to the announcement.\ +**Type:** Array of [Reaction]({{< relref "entities/Reaction" >}})\ +**Version history:**\ +3.1.0 - added + +## Announcement::Account attributes {#Account} + +### `id` {#Account-id} + +**Description:** The account ID of the mentioned user.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +3.1.0 - added + +### `username` {#Account-username} + +**Description:** The username of the mentioned user.\ +**Type:** String\ +**Version history:**\ +3.1.0 - added + +### `url` {#Account-url} + +**Description:** The location of the mentioned user's profile.\ +**Type:** String (URL)\ +**Version history:**\ +3.1.0 - added + +### `acct` {#Account-acct} + +**Description:** The webfinger acct: URI of the mentioned user. Equivalent to `username` for local users, or `username@domain` for remote users.\ +**Type:** String\ +**Version history:**\ +3.1.0 - added + +## Announcement::Status attributes {#Status} + +### `id` {#Status-id} + +**Description:** The ID of an attached Status in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +3.1.0 - added + +### `url` {#Status-url} + +**Description:** The URL of an attached Status.\ +**Type:** String (URL)\ +**Version history:**\ +3.1.0 - added + +## See also + +{{< page-relref ref="methods/announcements" caption="announcements API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/announcement_serializer.rb" caption="app/serializers/rest/announcement_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Application.md b/content/en/entities/Application.md new file mode 100644 index 00000000..76e5292e --- /dev/null +++ b/content/en/entities/Application.md @@ -0,0 +1,69 @@ +--- +title: Application +description: Represents an application that interfaces with the REST API to access accounts or post statuses. +menu: + docs: + parent: entities +aliases: [ + "/entities/application", + "/entities/Application", + "/api/entities/application", + "/api/entities/Application", +] +--- + +## Example + +```json +{ + "name": "test app", + "website": null, + "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +## Attributes + +### `name` {#name} + +**Description:** The name of your application.\ +**Type:** String\ +**Version history:**\ +0.9.9 - added + +### `website` {{%optional%}} {#website} + +**Description:** The website associated with your application.\ +**Type:** {{}} String (URL)\ +**Version history:**\ +0.9.9 - added +3.5.1 - this property is now nullable + +### `vapid_key` {#vapid_key} + +**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps]({{< relref "methods/apps#create" >}}). Equivalent to [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}})\ +**Type:** String\ +**Version history:**\ +2.8.0 - added + +### `client_id` {{%optional%}} {#client_id} + +**Description:** Client ID key, to be used for obtaining OAuth tokens\ +**Type:** String\ +**Version history:**\ +0.9.9 - added + +### `client_secret` {{%optional%}} {#client_secret} + +**Description:** Client secret key, to be used for obtaining OAuth tokens\ +**Type:** String\ +**Version history:**\ +0.9.9 - added + +## See also + +{{< page-relref ref="methods/apps" caption="apps API methods" >}} + +{{< page-relref ref="entities/Status#application" caption="Status (`application` attribute)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/serializers/rest/application_serializer.rb" caption="app/serializers/rest/application_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/context.md b/content/en/entities/Context.md similarity index 58% rename from content/en/entities/context.md rename to content/en/entities/Context.md index f0f4dfff..a7d87f98 100644 --- a/content/en/entities/context.md +++ b/content/en/entities/Context.md @@ -4,65 +4,67 @@ description: Represents the tree around a given status. Used for reconstructing menu: docs: parent: entities +aliases: [ + "/entities/context", + "/entities/Context", + "/api/entities/context", + "/api/entities/Context", +] --- ## Example -{{< code title="Truncated response from GET statuses/:id/context" >}} -```javascript +```json { "ancestors": [ { "id": "103188938570975982", "created_at": "2019-11-23T19:44:00.124Z", "in_reply_to_id": null, - ... + // ... }, { "id": "103188971072973252", "created_at": "2019-11-23T19:52:23.398Z", "in_reply_to_id": "103188938570975982", - ... + // ... }, { "id": "103188982235527758", "created_at": "2019-11-23T19:55:08.208Z", "in_reply_to_id": "103188971072973252", - ... + // ... + } ], "descendants": [ { "id": "103189026958574542", "created_at": "2019-11-23T20:06:36.011Z", "in_reply_to_id": "103189005915505698", - ... + // ... } ] } ``` -{{< /code >}} -## Required attributes +## Attributes ### `ancestors` {#ancestors} **Description:** Parents in the thread.\ -**Type:** Array of [Status]({{< relref "status.md" >}})\ -**Version history:** Added in 0.6.0 +**Type:** Array of [Status]({{< relref "entities/Status" >}})\ +**Version history:**\ +0.6.0 - added ### `descendants` {#descendants} **Description:** Children in the thread.\ -**Type:** Array of [Status]({{< relref "status.md" >}})\ -**Version history:** Added in 0.6.0 +**Type:** Array of [Status]({{< relref "entities/Status" >}})\ +**Version history:**\ +0.6.0 - added ## See also -* [GET /api/v1/statuses/:id/context]({{< relref "../methods/statuses/#parent-and-child-statuses" >}}) - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/context_serializer.rb" caption="app/serializers/rest/context\_serializer.rb" >}} - - - - +{{< page-relref ref="methods/statuses#context" caption="GET /api/v1/statuses/:id/context" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/context_serializer.rb" caption="app/serializers/rest/context_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Conversation.md b/content/en/entities/Conversation.md new file mode 100644 index 00000000..386e817b --- /dev/null +++ b/content/en/entities/Conversation.md @@ -0,0 +1,78 @@ +--- +title: Conversation +description: Represents a conversation with "direct message" visibility. +menu: + docs: + parent: entities +aliases: [ + "/entities/conversation", + "/entities/Conversation", + "/api/entities/conversation", + "/api/entities/Conversation", +] +--- + +## Example + +```json +{ + "id": "418450", + "unread": true, + "accounts": [ + { + "id": "482403", + "username": "amic", + "acct": "amic@nulled.red", + // ... + } + ], + "last_status": { + "id": "103196583826321184", + "created_at": "2019-11-25T04:08:24.000Z", + "in_reply_to_id": "103196540587943467", + "in_reply_to_account_id": "14715", + // ... + } +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the conversation in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +2.6.0 - added + +### `unread` {#unread} + +**Description:** Is the conversation currently marked as unread?\ +**Type:** Boolean\ +**Version history:**\ +2.6.0 - added + +### `accounts` {#accounts} + +**Description:** Participants in the conversation.\ +**Type:** Array of [Account]({{< relref "entities/Account" >}})\ +**Version history:**\ +2.6.0 - added + +### `last_status` {#last_status} + +**Description:** The last status in the conversation.\ +**Type:** {{}} [Status]({{< relref "entities/Status" >}})\ +**Version history:**\ +2.6.0 - added + +## See also + +{{< page-relref ref="methods/conversations" caption="conversations API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/conversation_serializer.rb" caption="app/serializers/rest/conversation_serializer.rb" >}} + + + + + diff --git a/content/en/entities/CustomEmoji.md b/content/en/entities/CustomEmoji.md new file mode 100644 index 00000000..49a9077c --- /dev/null +++ b/content/en/entities/CustomEmoji.md @@ -0,0 +1,81 @@ +--- +title: CustomEmoji +description: Represents a custom emoji. +menu: + docs: + parent: entities +aliases: [ + "/entities/emoji", + "/entities/Emoji", + "/entities/customemoji", + "/entities/CustomEmoji", + "/api/entities/emoji", + "/api/entities/Emoji", + "/api/entities/customemoji", + "/api/entities/CustomEmoji", +] +--- + +## Example + +```json +{ + "shortcode": "blobaww", + "url": "https://files.mastodon.social/custom_emojis/images/000/011/739/original/blobaww.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/011/739/static/blobaww.png", + "visible_in_picker": true, + "category": "Blobs" +} +``` + +## Attributes + +### `shortcode` {#shortcode} + +**Description:** The name of the custom emoji.\ +**Type:** String\ +**Version history:**\ +2.0.0 - added + +### `url` {#url} + +**Description:** A link to the custom emoji.\ +**Type:** String (URL)\ +**Version history:**\ +2.0.0 - added + +### `static_url` {#static_url} + +**Description:** A link to a static copy of the custom emoji.\ +**Type:** String (URL)\ +**Version history:**\ +2.0.0 - added + +### `visible_in_picker` {#visible_in_picker} + +**Description:** Whether this Emoji should be visible in the picker or unlisted.\ +**Type:** Boolean\ +**Version history:**\ +2.0.0 - added + +### `category` {#category} + +**Description:** Used for sorting custom emoji in the picker.\ +**Type:** String\ +**Version history:**\ +3.0.0 - added + +## See also + +{{< page-relref ref="methods/custom_emojis" caption="GET /api/v1/custom_emojis" >}} + +{{< page-relref ref="entities/Status#emojis" caption="Status (`emojis` attribute)" >}} + +{{< page-relref ref="entities/Announcement#emojis" caption="Announcement (`emojis` attribute)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/custom_emoji_serializer.rb" caption="app/serializers/rest/custom_emoji_serializer.rb" >}} + + + + + diff --git a/content/en/entities/DomainBlock.md b/content/en/entities/DomainBlock.md new file mode 100644 index 00000000..32f517ea --- /dev/null +++ b/content/en/entities/DomainBlock.md @@ -0,0 +1,62 @@ +--- +title: DomainBlock +description: Represents a domain that is blocked by the instance. +menu: + docs: + parent: entities +aliases: [ + "/entities/domainblock", + "/entities/DomainBlock", + "/api/entities/domainblock", + "/api/entities/DomainBlock", +] +--- + +## Example + +```json +{ + "domain":"daji******.com", + "digest":"3752f63a7079d60c2de5dceb8bd7608e86a15544eb78a494a482041c3684b37f", + "severity":"suspend", + "comment":"Inappropriate content" +} +``` + +## Attributes + +### `domain` {#domain} + +**Description:** The domain which is blocked. This may be obfuscated or partially censored.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `digest` {#digest} + +**Description:** The SHA256 hash digest of the domain string.\ +**Type:** String (SHA256)\ +**Version history:**\ +4.0.0 - added + +### `severity` {#severity} + +**Description:** The level to which the domain is blocked.\ +**Type:** String (Enumerable, oneOf)\ +`silence` = Users from this domain will be hidden from timelines, threads, and notifications (unless you follow the user).\ +`suspend` = Incoming messages from this domain will be rejected and dropped entirely.\ +**Version history:**\ +4.0.0 - added + +### `comment` {{}} {#comment} + +**Description:** An optional reason for the domain block.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="methods/instance#domain_blocks" caption="GET /api/v1/instance/domain_blocks" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/domain_block_serializer.rb" caption="app/serializers/rest/domain_block_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/EncryptedMessage.md b/content/en/entities/EncryptedMessage.md new file mode 100644 index 00000000..1203d9f9 --- /dev/null +++ b/content/en/entities/EncryptedMessage.md @@ -0,0 +1,90 @@ +--- +title: EncryptedMessage +description: Represents an encrypted message. +menu: + docs: + parent: entities +aliases: [ + "/entities/encryptedmessage", + "/entities/EncryptedMessage", + "/entities/encryptedmessage", + "/entities/EncryptedMessage", +] +draft: true +--- + +{{< hint style="info" >}} +This entity is currently unused. +{{}} + +## Example + +```json +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the EncryptedMessage in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +3.2.0 - added + +### `account_id` {#account_id} + +**Description:** The ID of the Account that sent this message.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +3.2.0 - added + +### `device_id` {#device_id} + +**Description:** The ID of the Device that sent this message.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +3.2.0 - added + +### `type` {#type} + +**Description:** Whether the message is a pre-key message (used to establish a new session) or a normally encrypted message (part of an existing session).\ +**Type:** String (Enumerable, oneOf)\ +`0` = Pre-key message (used to establish a new session)\ +`1` = Normal encrypted message (part of an existing session)\ +**Version history:**\ +3.2.0 - added + +### `body` {#body} + +**Description:** The encrypted message content.\ +**Type:** String\ +**Version history:**\ +3.2.0 - added + +### `digest` {#digest} + +**Description:** An HMAC SHA-256 digest hash of the message.\ +**Type:** String (SHA256)\ +**Version history:**\ +3.2.0 - added + +### `message_franking` {#message_franking} + +**Description:** A signed value to be used when reporting the message body for its content.\ +**Type:** String\ +**Version history:**\ +3.2.0 - added + +### `created_at` {#created_at} + +**Description:** A timestamp for when the message was created.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.2.0 - added + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/encrypted_message_serializer.rb" caption="app/serializers/rest/encrypted_message_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/pull/13820" caption="Add end-to-end encryption API (#13820)" >}} + diff --git a/content/en/entities/Error.md b/content/en/entities/Error.md new file mode 100644 index 00000000..67c29a09 --- /dev/null +++ b/content/en/entities/Error.md @@ -0,0 +1,125 @@ +--- +title: Error +description: Represents an error message. +menu: + docs: + parent: entities +aliases: [ + "/entities/error", + "/entities/Error", + "/api/entities/error", + "/api/entities/Error", +] +--- + +## Example + +```json +{ + "error": "invalid_grant", + "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." +} +``` + +{{< hint style="info" >}} +**The most important part of an error response is the HTTP status code.** Standard semantics are followed. The body of an error is a JSON object containing more information, if available. +{{< /hint >}} + +## Attributes + +### `error` {#error} + +**Description:** The error message.\ +**Type:** String\ +**Version history:**\ +0.6.0 - added + +### `error_description` {{%optional%}} {#error_description} + +**Description:** A longer description of the error, mainly provided with the OAuth API.\ +**Type:** String\ +**Version history:**\ +0.6.0 - added + +## Possible reasons {#reasons} + +### 400 - Bad request + +#### ParameterMissing {#parameter-missing} + +Error: {string}. Appears when a required parameter is missing from the API call. + +### 401 - Unauthorized {#401} + +#### require_authenticated_user! {#auth} + +Error: This API requires an authenticated user. Appears when the instance is in secure mode, which disables all public use of API methods. + +### 403 - Forbidden {#403} + +#### NotPermitted {#not-permitted} + +Error: This action is not allowed. Appears when trying to call a method that you do not have permission for (such as admin or staff methods), or performing actions you are not allowed to do (such as following a user that blocks you). + +#### current_user.disabled? {#disabled} + +Error: Your login is currently disabled. Appears when the OAuth token's authorized user has had their account disabled by a moderator. + +#### !current_user.confirmed? {#unconfirmed} + +Error: Your login is missing a confirmed e-mail address. Appears when the email address associated with the OAuth token's authorized user's account has not yet been confirmed. + +#### !current_user.approved? {#unapproved} + +Error: Your login is currently pending approval. Appears when the OAuth token's authorized user has signed up on an instance with approval-required registrations, and the user has not yet had their account approved by a moderator. + +### 404 - Not found {#404} + +#### RecordNotFound {#not-found} + +Error: Record not found. Appears when an entity record does not exist, or the authorized user is not within the audience of a private entity.operates on a user. + +### 422 - Unprocessable entity {#422} + +#### RecordInvalid {#invalid} + +Error: {string}. May appear when entity creation failed. + +#### RecordNotUnique {#not-unique} + +Error: Duplicate record. Appears when you are trying to pin an account or status that is already pinned. + +#### !current_user {#user-required} + +Error: This method requires an authenticated user. Appears when using an OAuth token without an authorized user (or no token at all), while trying to call an API method that requires a user to be processed. + +### 429 - Too many requests {#429} + +Error: {translated string}. Appears when you have exceeded the rate limit. See [Rate limits]({{< relref "api/rate-limits" >}}) for more information. + +### 503 - Remote service unavailable {#503} + +#### UnexpectedResponseError {#unexpected-response} + +Error: Remote data could not be fetched. Appears when Mastodon calls a remote service (such as WebFinger from another instance) which returns an error. + +#### SSLError {#ssl} + +Error: Remote SSL certificate could not be verified. Appears when a remote service is called, but it has an invalid SSL certificate. + +#### NetworkingError {#networking-error} + +Error: There was a temporary problem serving your request, please try again. Appears when there was a failed call to an S3 storage server. + +#### RaceConditionError {#race-condition} + +Error: There was a temporary problem serving your request, please try again. Appears when there was an error due to a race condition in server-side code. + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/controllers/api/base_controller.rb" caption="app/controllers/api/base_controller.rb" >}} + + + + + diff --git a/content/en/entities/ExtendedDescription.md b/content/en/entities/ExtendedDescription.md new file mode 100644 index 00000000..deba14ab --- /dev/null +++ b/content/en/entities/ExtendedDescription.md @@ -0,0 +1,44 @@ +--- +title: ExtendedDescription +description: Represents an extended description for the instance, to be shown on its about page. +menu: + docs: + parent: entities +aliases: [ + "/entities/extendeddescription", + "/entities/ExtendedDescription", + "/api/entities/extendeddescription", + "/api/entities/ExtendedDescription", +] +--- + +## Example + +```json +{ + "updated_at":"2022-11-03T04:09:07Z", + "content":"

For inquiries not related specifically to the operation of this server, such as press inquiries, please contact press@joinmastodon.org.

\n\n

Funding

\n\n

This server is crowdfunded by Patreon donations. For a list of sponsors, see joinmastodon.org.

\n\n

Reporting and moderation

\n\n

When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.

\n\n

We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.

\n\n

Impressum

\n\n

Mastodon gGmbH
\nMühlenstraße 8a
\n14167 Berlin
\nGermany

\n\n

E-Mail-Adresse: hello@joinmastodon.org

\n\n

Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)

\n\n

Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260

\n\n

Handelsregister
\nGeführt bei: Amtsgericht Charlottenburg
\nNummer: HRB 230086 B

\n" +} +``` + +## Attributes + +### `updated_at` {#updated_at} + +**Description:** A timestamp of when the extended description was last updated.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +### `content` {#content} + +**Description:** The rendered HTML content of the extended description.\ +**Type:** String (HTML)\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="methods/instance#extended_description" caption="GET /api/v1/instance/extended_description" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/extended_description_serializer.rb" caption="app/serializers/rest/extended_description_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/FamiliarFollowers.md b/content/en/entities/FamiliarFollowers.md new file mode 100644 index 00000000..84297fa8 --- /dev/null +++ b/content/en/entities/FamiliarFollowers.md @@ -0,0 +1,64 @@ +--- +title: FamiliarFollowers +description: Represents a subset of your follows who also follow some other user. +menu: + docs: + parent: entities +aliases: [ + "/entities/familiarfollowers", + "/entities/FamiliarFollowers", + "/api/entities/familiarfollowers", + "/api/entities/FamiliarFollowers", +] +--- + +## Example + +```json +[ + { + "id":"1", + "accounts":[ + { + "id":"1087990", + "username":"moss", + "acct":"moss@goblin.camp", + // ... + }, + { + "id":"1092723", + "username":"vivianrose", + "acct":"vivianrose", + // ... + }, + // ... + ] + }, + { + "id":"2", + "accounts":[] + } +] +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the Account in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +3.5.0 - added + +### `accounts` {#accounts} + +**Description:** Accounts you follow that also follow this account.\ +**Type:** Array of [Account]({{< relref "entities/Account" >}})\ +**Version history:**\ +3.5.0 - added + +## See also + +{{< page-relref ref="methods/accounts#familiar_followers" caption="GET /api/v1/accounts/:id/familiar_followers" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/familiar_followers_serializer.rb" caption="app/serializers/rest/familiar_followers_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/FeaturedTag.md b/content/en/entities/FeaturedTag.md new file mode 100644 index 00000000..8c245e2d --- /dev/null +++ b/content/en/entities/FeaturedTag.md @@ -0,0 +1,73 @@ +--- +title: FeaturedTag +description: Represents a hashtag that is featured on a profile. +menu: + docs: + parent: entities +aliases: [ + "/entities/featuredtag", + "/entities/FeaturedTag", + "/api/entities/featuredtag", + "/api/entities/FeaturedTag", +] +--- + +## Example + +```json +{ + "id": "627", + "name": "nowplaying", + "url": "https://mastodon.social/@trwnh/tagged/nowplaying", + "statuses_count": 70, + "last_status_at": "2022-08-29T12:03:35.061Z" +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The internal ID of the featured tag in the database.\ +**Type:** String (cast from integer but not guaranteed to be a number)\ +**Version history:**\ +3.0.0 - added + +### `name` {#name} + +**Description:** The name of the hashtag being featured.\ +**Type:** String\ +**Version history:**\ +3.0.0 - added + +### `url` {#url} + +**Description:** A link to all statuses by a user that contain this hashtag.\ +**Type:** String (URL)\ +**Version history:**\ +3.3.0 - added + +### `statuses_count` {#statuses_count} + +**Description:** The number of authored statuses containing this hashtag.\ +**Type:** Number\ +**Version history:**\ +3.0.0 - added + +### `last_status_at` {#last_status_at} + +**Description:** The timestamp of the last authored status containing this hashtag.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.0.0 - added + +## See also + +{{< page-relref ref="methods/featured_tags" caption="featured_tags API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/featured_tag_serializer.rb" caption="app/serializers/rest/featured_tag_serializer.rb" >}} + + + + + diff --git a/content/en/entities/Filter.md b/content/en/entities/Filter.md new file mode 100644 index 00000000..1f6d4eca --- /dev/null +++ b/content/en/entities/Filter.md @@ -0,0 +1,108 @@ +--- +title: Filter +description: Represents a user-defined filter for determining which statuses should not be shown to the user. +menu: + docs: + parent: entities +aliases: [ + "/entities/filter", + "/entities/Filter", + "/api/entities/filter", + "/api/entities/Filter", +] +--- + +## Example + +```json +{ + "id": "19972", + "title": "Test filter", + "context": [ + "home" + ], + "expires_at": "2022-09-20T17:27:39.296Z", + "filter_action": "warn", + "keywords": [ + { + "id": "1197", + "keyword": "bad word", + "whole_word": false + } + ], + "statuses": [ + { + "id": "1", + "status_id": "109031743575371913" + } + ] +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the Filter in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +### `title` {#title} + +**Description:** A title given by the user to name the filter.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `context` {#context} + +**Description:** The contexts in which the filter should be applied.\ +**Type:** Array of String (Enumerable, anyOf)\ +`home` = home timeline and lists\ +`notifications` = notifications timeline\ +`public` = public timelines\ +`thread` = expanded thread of a detailed status\ +`account` = when viewing a profile\ +**Version history:**\ +4.0.0 - added + +### `expires_at` {#expires_at} + +**Description:** When the filter should no longer be applied.\ +**Type:** {{}} String (ISO 8601 Datetime), or null if the filter does not expire\ +**Version history:**\ +4.0.0 - added + +### `filter_action` {#filter_action} + +**Description:** The action to be taken when a status matches this filter.\ +**Type:** String (Enumerable, oneOf)\ +`warn` = show a warning that identifies the matching filter by `title`, and allow the user to expand the filtered status. This is the default (and unknown values should be treated as equivalent to `warn`).\ +`hide` = do not show this status if it is received\ +**Version history:**\ +4.0.0 - added + +### `keywords` {#keywords} + +**Description:** The keywords grouped under this filter.\ +**Type:** Array of [FilterKeyword]({{< relref "entities/FilterKeyword" >}})\ +**Version history:**\ +4.0.0 - added + +### `statuses` {#statuses} + +**Description:** The statuses grouped under this filter.\ +**Type:** Array of [FilterStatus]({{< relref "entities/FilterStatus" >}})\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}} + +{{< page-relref ref="entities/V1_Filter" caption="V1::Filter (for Mastodon 3.5 and earlier)" >}} + +{{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_serializer.rb" caption="app/serializers/rest/filter_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/FilterKeyword.md b/content/en/entities/FilterKeyword.md new file mode 100644 index 00000000..eec298c3 --- /dev/null +++ b/content/en/entities/FilterKeyword.md @@ -0,0 +1,54 @@ +--- +title: FilterKeyword +description: Represents a keyword that, if matched, should cause the filter action to be taken. +menu: + docs: + parent: entities +aliases: [ + "/entities/filterkeyword", + "/entities/FilterKeyword", + "/api/entities/filterkeyword", + "/api/entities/FilterKeyword", +] +--- + +## Example + +```json +{ + "id": "1197", + "keyword": "bad word", + "whole_word": false +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the FilterKeyword in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +### `keyword` {#keyword} + +**Description:** The phrase to be matched against.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `whole_word` {#whole_word} + +**Description:** Should the filter consider word boundaries? See [implementation guidelines for filters]({{< relref "api/guidelines#filters" >}}).\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}} + +{{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_keyword_serializer.rb" caption="app/serializers/rest/filter_keyword_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/FilterResult.md b/content/en/entities/FilterResult.md new file mode 100644 index 00000000..d2323fbc --- /dev/null +++ b/content/en/entities/FilterResult.md @@ -0,0 +1,66 @@ +--- +title: FilterResult +description: Represents a filter whose keywords matched a given status. +menu: + docs: + parent: entities +aliases: [ + "/entities/filterresult", + "/entities/FilterResult", + "/api/entities/filterresult", + "/api/entities/FilterResult", +] +--- + +## Example + +```json +{ + "filter": { + "id": "3", + "title": "Hide completely", + "context": [ + "home" + ], + "expires_at": "2022-09-20T17:27:39.296Z", + "filter_action": "hide" + }, + "keyword_matches": [ + "bad word" + ], + "status_matches": [ + "109031743575371913" + ] +} +``` + +## Attributes + +### `filter` {#filter} + +**Description:** The filter that was matched.\ +**Type:** [Filter]({{< relref "entities/Filter" >}})\ +**Version history:**\ +4.0.0 - added + +### `keyword_matches` {#keyword_matches} + +**Description:** The keyword within the filter that was matched.\ +**Type:** {{}} Array of String, or null\ +**Version history:**\ +4.0.0 - added + +### `status_matches` {#status_matches} + +**Description:** The status ID within the filter that was matched.\ +**Type:** {{}} String, or null\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}} + +{{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_result_serializer.rb" caption="app/serializers/rest/filter_result_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/FilterStatus.md b/content/en/entities/FilterStatus.md new file mode 100644 index 00000000..b6402e40 --- /dev/null +++ b/content/en/entities/FilterStatus.md @@ -0,0 +1,46 @@ +--- +title: FilterStatus +description: Represents a status ID that, if matched, should cause the filter action to be taken. +menu: + docs: + parent: entities +aliases: [ + "/entities/filterstatus", + "/entities/FilterStatus", + "/api/entities/filterstatus", + "/api/entities/FilterStatus", +] +--- + +## Example + +```json +{ + "id": "1", + "status_id": "109031743575371913" +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the FilterStatus in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +### `status_id` {#keyword} + +**Description:** The ID of the filtered Status in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}} + +{{< page-relref ref="methods/filters" caption="/api/v2/filters methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/filter_status_serializer.rb" caption="app/serializers/rest/filter_status_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/identityproof.md b/content/en/entities/IdentityProof.md similarity index 53% rename from content/en/entities/identityproof.md rename to content/en/entities/IdentityProof.md index 88c3677b..f54f0291 100644 --- a/content/en/entities/identityproof.md +++ b/content/en/entities/IdentityProof.md @@ -4,9 +4,19 @@ description: Represents a proof from an external identity provider. menu: docs: parent: entities +aliases: [ + "/entities/identityproof", + "/entities/IdentityProof", + "/api/entities/identityproof", + "/api/entities/IdentityProof", +] --- -```javascript +{{< hint style="danger" >}} +Identity proofs have been deprecated in 3.5.0 and newer. Previously, the only proof provider was Keybase, but development on Keybase has stalled entirely since it was acquired by Zoom. +{{< /hint >}} + +```json { "provider": "Keybase", "provider_username": "gargron", @@ -22,39 +32,42 @@ menu: **Description:** The name of the identity provider.\ **Type:** String\ -**Version history:** Added in 2.8.0 +**Version history:**\ +2.8.0 - added ### `provider_username` {#provider_username} **Description:** The account owner's username on the identity provider's service.\ **Type:** String\ -**Version history:** Added in 2.8.0 - -### `profile_url` {#profile_url} - -**Description:** The account owner's profile URL on the identity provider.\ -**Type:** String \(URL\)\ -**Version history:** Added in 2.8.0 - -### `proof_url` {#proof_url} - -**Description:** A link to a statement of identity proof, hosted by the identity provider.\ -**Type:** String \(URL\)\ -**Version history:** Added in 2.8.0 +**Version history:**\ +2.8.0 - added ### `updated_at` {#updated_at} **Description:** When the identity proof was last updated.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:** Added in 2.8.0 +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +2.8.0 - added + +### `proof_url` {#proof_url} + +**Description:** A link to a statement of identity proof, hosted by the identity provider.\ +**Type:** String (URL)\ +**Version history:**\ +2.8.0 - added + +### `profile_url` {#profile_url} + +**Description:** The account owner's profile URL on the identity provider.\ +**Type:** String (URL)\ +**Version history:**\ +2.8.0 - added ## See also -* [GET /api/v1/accounts/:id/identity\_proofs]({{< relref "../methods/accounts/#identity-proofs" >}}) -* /api/proofs -* [About identity proofs]({{< relref "../user/contacts.md#identity-proofs" >}}) +{{< page-relref ref="methods/accounts#identity_proofs" caption="GET /api/v1/accounts/:id/identity_proofs" >}} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/identity_proof_serializer.rb" caption="app/serializers/rest/identity\_proof\_serializer.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/pull/17045" caption="Remove Keybase integration (#17045)" >}} diff --git a/content/en/entities/Instance.md b/content/en/entities/Instance.md new file mode 100644 index 00000000..18a9e23e --- /dev/null +++ b/content/en/entities/Instance.md @@ -0,0 +1,493 @@ +--- +title: Instance +description: Represents the software instance of Mastodon running on this domain. +menu: + docs: + parent: entities +aliases: [ + "/entities/instance", + "/entities/Instance", + "/api/entities/instance", + "/api/entities/Instance", +] +--- + +## Example + +```json +{ + "domain": "mastodon.social", + "title": "Mastodon", + "version": "4.0.0rc1", + "source_url": "https://github.com/mastodon/mastodon", + "description": "The original server operated by the Mastodon gGmbH non-profit", + "usage": { + "users": { + "active_month": 123122 + } + }, + "thumbnail": { + "url": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png", + "blurhash": "UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$", + "versions": { + "@1x": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png", + "@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png" + } + }, + "languages": [ + "en" + ], + "configuration": { + "urls": { + "streaming": "wss://mastodon.social" + }, + "accounts": { + "max_featured_tags": 10 + }, + "statuses": { + "max_characters": 500, + "max_media_attachments": 4, + "characters_reserved_per_url": 23 + }, + "media_attachments": { + "supported_mime_types": [ + "image/jpeg", + "image/png", + "image/gif", + "image/heic", + "image/heif", + "image/webp", + "video/webm", + "video/mp4", + "video/quicktime", + "video/ogg", + "audio/wave", + "audio/wav", + "audio/x-wav", + "audio/x-pn-wave", + "audio/vnd.wave", + "audio/ogg", + "audio/vorbis", + "audio/mpeg", + "audio/mp3", + "audio/webm", + "audio/flac", + "audio/aac", + "audio/m4a", + "audio/x-m4a", + "audio/mp4", + "audio/3gpp", + "video/x-ms-asf" + ], + "image_size_limit": 10485760, + "image_matrix_limit": 16777216, + "video_size_limit": 41943040, + "video_frame_rate_limit": 60, + "video_matrix_limit": 2304000 + }, + "polls": { + "max_options": 4, + "max_characters_per_option": 50, + "min_expiration": 300, + "max_expiration": 2629746 + }, + "translation": { + "enabled": true + } + }, + "registrations": { + "enabled": false, + "approval_required": false, + "message": null + }, + "contact": { + "email": "staff@mastodon.social", + "account": { + "id": "1", + "username": "Gargron", + "acct": "Gargron", + "display_name": "Eugen 💀", + "locked": false, + "bot": false, + "discoverable": true, + "group": false, + "created_at": "2016-03-16T00:00:00.000Z", + "note": "

Founder, CEO and lead developer @Mastodon, Germany.

", + "url": "https://mastodon.social/@Gargron", + "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count": 133026, + "following_count": 311, + "statuses_count": 72605, + "last_status_at": "2022-10-31", + "noindex": false, + "emojis": [], + "fields": [ + { + "name": "Patreon", + "value": "https://www.patreon.com/mastodon", + "verified_at": null + } + ] + } + }, + "rules": [ + { + "id": "1", + "text": "Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id": "3", + "text": "No incitement of violence or promotion of violent ideologies" + }, + { + "id": "4", + "text": "No harassment, dogpiling or doxxing of other users" + }, + { + "id": "5", + "text": "No content illegal in Germany" + }, + { + "id": "7", + "text": "Do not share intentionally false or misleading information" + } + ] +} +``` + +## Attributes + +### `domain` {#domain} + +**Description:** The domain name of the instance.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `title` {#title} + +**Description:** The title of the website.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `version` {#version} + +**Description:** The version of Mastodon installed on the instance.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `source_url` {#source_url} + +**Description:** The URL for the source code of the software running on this instance, in keeping with AGPL license requirements.\ +**Type:** String (URL)\ +**Version history:**\ +4.0.0 - added + +### `description` {#description} + +**Description:** A short, plain-text description defined by the admin.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `usage` {#usage} + +**Description:** Usage data for this instance.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +#### `usage[users]` {#users} + +**Description:** Usage data related to users on this instance.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `usage[users][active_month]` {#active_month} + +**Description:** The number of active users in the past 4 weeks.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +### `thumbnail` {#thumbnail} + +**Description:** An image used to represent this instance.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +#### `thumbnail[url]` {#thumbnail-url} + +**Description:** The URL for the thumbnail image.\ +**Type:** String (URL)\ +**Version history:**\ +4.0.0 - added + +#### `thumbnail[blurhash]` {{}} {#blurhash} + +**Description:** A hash computed by [the BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet.\ +**Type:** String (Blurhash)\ +**Version history:**\ +4.0.0 - added + +#### `thumbnail[versions]` {{}} {#thumbnail-versions} + +**Description:** Links to scaled resolution images, for high DPI screens.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `thumbnail[versions][@1x]` {{}} {#1x} + +**Description:** The URL for the thumbnail image at 1x resolution.\ +**Type:** String (URL)\ +**Version history:**\ +4.0.0 - added + +##### `thumbnail[versions][@2x]` {{}} {#2x} + +**Description:** The URL for the thumbnail image at 2x resolution.\ +**Type:** String (URL)\ +**Version history:**\ +4.0.0 - added + +### `languages` {#languages} + +**Description:** Primary languages of the website and its staff.\ +**Type:** Array of String (ISO 639-1 two-letter code)\ +**Version history:**\ +4.0.0 - added + +### `configuration` {#configuration} + +**Description:** Configured values and limits for this website.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +#### `configuration[urls]` {#urls} + +**Description:** URLs of interest for clients apps.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `configuration[urls][streaming_api]` {#streaming_api} + +**Description:** The Websockets URL for connecting to the streaming API.\ +**Type:** String (URL)\ +**Version history:**\ +4.0.0 - added + +#### `configuration[accounts]` {#accounts} + +**Description:** Limits related to accounts.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `configuration[accounts][max_featured_tags]` {#max_featured_tags} + +**Description:** The maximum number of featured tags allowed for each account.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +#### `configuration[statuses]` {#statuses} + +**Description:** Limits related to authoring statuses.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `configuration[statuses][max_characters]` {#max_characters} + +**Description:** The maximum number of allowed characters per status.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[statuses][max_media_attachments]` {#max_media_attachments} + +**Description:** The maximum number of media attachments that can be added to a status.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[statuses][characters_reserved_per_url]` {#characters_reserved_per_url} + +**Description:** Each URL in a status will be assumed to be exactly this many characters.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +#### `configuration[media_attachments]` {#media_attachments} + +**Description:** Hints for which attachments will be accepted.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `configuration[media_attachments][supported_mime_types]` {#supported_mime_types} + +**Description:** Contains MIME types that can be uploaded.\ +**Type:** Array of String\ +**Version history:**\ +4.0.0 - added + +##### `configuration[media_attachments][image_size_limit]` {#image_size_limit} + +**Description:** The maximum size of any uploaded image, in bytes.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[media_attachments][image_matrix_limit]` {#image_matrix_limit} + +**Description:** The maximum number of pixels (width times height) for image uploads.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[media_attachments][video_size_limit]` {#video_size_limit} + +**Description:** The maximum size of any uploaded video, in bytes.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[media_attachments][video_frame_rate_limit]` {#video_frame_rate_limit} + +**Description:** The maximum frame rate for any uploaded video.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[media_attachments][video_matrix_limit]` {#video_matrix_limit} + +**Description:** The maximum number of pixels (width times height) for video uploads.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +#### `configuration[polls]` {#polls} + +**Description:** Limits related to polls.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `configuration[polls][max_options]` {#max_options} + +**Description:** Each poll is allowed to have up to this many options.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[polls][max_characters_per_option]` {#max_characters_per_option} + +**Description:** Each poll option is allowed to have this many characters.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[polls][min_expiration]` {#min_expiration} + +**Description:** The shortest allowed poll duration, in seconds.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +##### `configuration[polls][max_expiration]` {#max_expiration} + +**Description:** The longest allowed poll duration, in seconds.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +#### `configuration[translation]` {#translation} + +**Description:** Hints related to translation.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `configuration[translation][enabled]` {#translation-enabled} + +**Description:** Whether the Translations API is available on this instance.\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +### `registrations` + +**Description:** Information about registering for this website.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +#### `registrations[enabled]` {#registrations-enabled} + +**Description:** Whether registrations are enabled.\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +#### `registrations[approval_required]` {#approval_required} + +**Description:** Whether registrations require moderator approval.\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +#### `registrations[message]` {#registrations-message} + +**Description:** A custom message to be shown when registrations are closed.\ +**Type:** {{}} String (HTML) or null\ +**Version history:**\ +4.0.0 - added + +### `contact` {#contact} + +**Description:** Hints related to contacting a representative of the website.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +#### `contact[email]` {#contact-email} + +**Description:** An email address that can be messaged regarding inquiries or issues.\ +**Type:** String (Email)\ +**Version history:**\ +4.0.0 - added + +#### `contact[account]` {#contact-account} + +**Description:** An account that can be contacted natively over the network regarding inquiries or issues.\ +**Type:** [Account]({{< relref "entities/Account" >}})\ +**Version history:**\ +4.0.0 - added + +### `rules` {#rules} + +**Description:** An itemized list of rules for this website.\ +**Type:** Array of [Rule]({{< relref "entities/Rule" >}})\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="methods/instance#v2" caption="GET /api/v2/instance" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/instance_serializer.rb" caption="app/serializers/rest/instance_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/list.md b/content/en/entities/List.md similarity index 52% rename from content/en/entities/list.md rename to content/en/entities/List.md index 9641e9e5..ad6df0d8 100644 --- a/content/en/entities/list.md +++ b/content/en/entities/List.md @@ -4,15 +4,21 @@ description: Represents a list of some users that the authenticated user follows menu: docs: parent: entities +aliases: [ + "/entities/list", + "/entities/List", + "/api/entities/list", + "/api/entities/List", +] --- ## Example -```javascript - { - "id": "12249", - "title": "Friends" - } +```json +{ + "id": "12249", + "title": "Friends" +} ``` ## Required attributes @@ -20,7 +26,7 @@ menu: ### `id` {#id} **Description:** The internal database ID of the list.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ **Version history:**\ 2.1.0 - added @@ -33,7 +39,7 @@ menu: ### `replies_policy` {#replies_policy} -**Description:** The user-defined title of the list.\ +**Description:** Which replies should be shown in the list.\ **Type:** String (Enumerable oneOf)\ `followed` = Show replies to any followed user\ `list` = Show replies to members of the list\ @@ -43,9 +49,11 @@ menu: ## See also -{{< page-ref page="methods/timelines/lists.md" >}} +{{< page-relref ref="methods/accounts#lists" caption="GET /api/v1/accounts/:id/lists" >}} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/list_serializer.rb" caption="app/serializers/rest/list\_serializer.rb" >}} +{{< page-relref ref="methods/lists" caption="lists API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/list_serializer.rb" caption="app/serializers/rest/list_serializer.rb" >}} diff --git a/content/en/entities/Marker.md b/content/en/entities/Marker.md new file mode 100644 index 00000000..24d3dc2b --- /dev/null +++ b/content/en/entities/Marker.md @@ -0,0 +1,53 @@ +--- +title: Marker +description: Represents the last read position within a user's timelines. +menu: + docs: + parent: entities +aliases: [ + "/entities/marker", + "/entities/Marker", + "/api/entities/marker", + "/api/entities/Marker", +] +--- + +## Example + +```json +{ + "last_read_id": "103194548672408537", + "version": 462, + "updated_at": "2019-11-24T19:39:39.337Z" +} +``` + +## Attributes + +### `last_read_id` {#last_read_id} + +**Description:** The ID of the most recently viewed entity.\ +**Type:** String (cast from integer but not guaranteed to be a number)\ +3.0.0 - added + +### `version` {#version} + +**Description:** An incrementing counter, used for locking to prevent write conflicts.\ +**Type:** Integer\ +**Version history:**\ +3.0.0 - added + +### `updated_at` {#updated_at} + +**Description:** The timestamp of when the marker was set.\ +**Type:** String (ISO 8601 Datetime)\ +3.0.0 - added + +## See also + +{{< page-relref ref="methods/markers" caption="markers API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/marker_serializer.rb" caption="app/serializers/rest/marker_serializer.rb" >}} + + + diff --git a/content/en/entities/attachment.md b/content/en/entities/MediaAttachment.md similarity index 74% rename from content/en/entities/attachment.md rename to content/en/entities/MediaAttachment.md index 7c912011..eadd1bcd 100644 --- a/content/en/entities/attachment.md +++ b/content/en/entities/MediaAttachment.md @@ -1,16 +1,26 @@ --- -title: Attachment +title: MediaAttachment description: Represents a file or media attachment that can be added to a status. menu: docs: parent: entities +aliases: [ + "/entities/attachment", + "/entities/Attachment", + "/entities/mediaattachment", + "/entities/MediaAttachment", + "/api/entities/attachment", + "/api/entities/Attachment", + "/api/entities/mediaattachment", + "/api/entities/MediaAttachment", +] --- ## Example -{{< tabs >}} -{{< tab title="Image" >}} -```javascript +### Image + +```json { "id": "22345792", "type": "image", @@ -40,10 +50,10 @@ menu: "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" } ``` -{{< endtab >}} -{{< tab title="Video" >}} -```javascript +### Video + +```json { "id": "22546306", "type": "video", @@ -80,10 +90,10 @@ menu: "blurhash": "U58E0g8_0M.94T?bIr00?bD%NGoM?bD%oLt7" } ``` -{{< endtab >}} -{{< tab title="GIFV" >}} -```javascript +### GIFV + +```json { "id": "21130559", "type": "gifv", @@ -117,10 +127,10 @@ menu: "blurhash": "URHT%Jm,2a1d%MRO%LozkrNH$*n*oMn$Rjt7" } ``` -{{< endtab >}} -{{< tab title="Audio" >}} -```javascript +### Audio + +```json { "id": "21165404", "type": "audio", @@ -143,90 +153,90 @@ menu: "blurhash": null } ``` -{{< endtab >}} -{{< endtabs >}} -## Required attributes +## Attributes ### `id` {#id} **Description:** The ID of the attachment in the database.\ -**Type:** String \(cast from an integer but not guaranteed to be a number\)\ -**Version history:** Added in 0.6.0. +**Type:** String (cast from an integer but not guaranteed to be a number)\ +**Version history:**\ +0.6.0 - added ### `type` {#type} **Description:** The type of the attachment.\ -**Type:** String \(Enumerable, oneOf\)\ +**Type:** String (Enumerable, oneOf)\ `unknown` = unsupported or unrecognized file type\ `image` = Static image\ `gifv` = Looping, soundless animation\ `video` = Video clip\ `audio` = Audio track\ -**Version history:** Added in 0.6.0. Audio added in 2.9.1. +**Version history:**\ +0.6.0 - added\ +2.9.1 - added `audio` ### `url` {#url} **Description:** The location of the original full-size attachment.\ -**Type:** String \(URL\)\ -**Version history:** Added in 0.6.0. +**Type:** String (URL)\ +**Version history:**\ +0.6.0 - added ### `preview_url` {#preview_url} **Description:** The location of a scaled-down preview of the attachment.\ -**Type:** String \(URL\)\ -**Version history:** Added in 0.6.0. - -## Optional attributes +**Type:** String (URL)\ +**Version history:**\ +0.6.0 - added ### `remote_url` {#remote_url} **Description:** The location of the full-size original attachment on the remote website.\ -**Type:** String \(URL\), or null if the attachment is local\ -**Version history:** Added in 0.6.0. +**Type:** {{}} String (URL), or null if the attachment is local\ +**Version history:**\ +0.6.0 - added ### `meta` {#meta} **Description:** Metadata returned by Paperclip.\ **Type:** Hash\ -**Version history:** Added in 1.5.0. meta\[focus\] added in 2.3.0. +**Version history:**\ +1.5.0 - added\ +2.3.0 - added `meta.focus` May contain subtrees `small` and `original`, as well as various other top-level properties. -More importantly, there may be another top-level `focus` Hash object as of 2.3.0, with coordinates can be used for smart thumbnail cropping -- see [Focal points]({{< relref "../methods/statuses/media.md#focal-points" >}}) for more. +More importantly, there may be another topl-level `focus` Hash object on images as of 2.3.0, with coordinates can be used for smart thumbnail cropping -- see [Focal points for cropped media thumbnails]({{< relref "api/guidelines#focal-points" >}}) for more. ### `description` {#description} **Description:** Alternate text that describes what is in the media attachment, to be used for the visually impaired or when media attachments do not load.\ **Type:** String\ -**Version history:** Added in 2.0.0 +**Version history:**\ +2.0.0 - added ### `blurhash` {#blurhash} **Description:** A hash computed by [the BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet.\ -**Type:** String\ -**Version history:** Added in 2.8.1 +**Type:** String (Blurhash)\ +**Version history:**\ +2.8.1 - added ## Deprecated attributes ### `text_url` {#text_url} **Description:** A shorter URL for the attachment.\ -**Type:** String \(URL\)\ -**Version history:** Added in 0.6.0 and deprecated in 3.5.0. +**Type:** String (URL)\ +**Version history:**\ +0.6.0 - added\ +3.5.0 - removed ## See also -* Status\#media\_attachments -* /api/v1/media - -{{< page-ref page="status.md" >}} - -{{< page-ref page="methods/statuses/media.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/media_attachment_serializer.rb" caption="app/serializers/rest/media\_attachment\_serializer.rb" >}} - - - +{{< page-relref ref="entities/Status#media_attachments" caption="Status (`media_attachments` attribute)" >}} +{{< page-relref ref="methods/media" caption="media API methods" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/media_attachment_serializer.rb" caption="app/serializers/rest/media_attachment_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/notification.md b/content/en/entities/Notification.md similarity index 55% rename from content/en/entities/notification.md rename to content/en/entities/Notification.md index 37eda90a..57076b39 100644 --- a/content/en/entities/notification.md +++ b/content/en/entities/Notification.md @@ -4,13 +4,81 @@ description: Represents a notification of an event relevant to the user. menu: docs: parent: entities +aliases: [ + "/entities/notification", + "/entities/Notification", + "/entities/notification", + "/entities/Notification", +] --- -## Example -{{< code title="excerpt from GET notifications" >}} -```javascript -[ + +## Attributes + +### `id` {#id} + +**Description:** The id of the notification in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +0.9.9 - added + +### `type` {#type} + +**Description:** The type of event that resulted in the notification.\ +**Type:** String (Enumerable oneOf)\ +`mention` = Someone mentioned you in their status\ +`status` = Someone you enabled notifications for has posted a status\ +`reblog` = Someone boosted one of your statuses\ +`follow` = Someone followed you\ +`follow_request` = Someone requested to follow you\ +`favourite` = Someone favourited one of your statuses\ +`poll` = A poll you have voted in or created has ended\ +`update` = A status you interacted with has been edited\ +`admin.sign_up` = Someone signed up (optionally sent to admins)\ +`admin.report` = A new report has been filed\ +**Version history:**\ +0.9.9 - added\ +2.8.0 - added `poll`\ +3.1.0 - added `follow_request`\ +3.3.0 - added `status`\ +3.5.0 - added `update` and `admin.sign_up`\ +4.0.0 - added `admin.report` + +### `created_at` {#created_at} + +**Description:** The timestamp of the notification.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +0.9.9 - added + +### `account` {#account} + +**Description:** The account that performed the action that generated the notification.\ +**Type:** [Account]({{< relref "entities/Account" >}})\ +**Version history:**\ +0.9.9 - added + +### `status` {{%optional%}} {#status} + +**Description:** Status that was the object of the notification. Attached when `type` of the notification is `favourite`, `reblog`, `status`, `mention`, `poll`, or `update`.\ +**Type:** [Status]({{< relref "entities/Status" >}})\ +**Version history:**\ +0.9.9 - added + +### `report` {{%optional%}} {#report} + +**Description:** Report that was the object of the notification. Attached when `type` of the notification is `admin.report`.\ +**Type:** [Report]({{< relref "entities/Report" >}})\ +**Version history:**\ +4.0.0 - added + +## Examples + +### Mention + +```json + { "id": "34975861", "type": "mention", @@ -19,16 +87,21 @@ menu: "id": "971724", "username": "zsc", "acct": "zsc", - ... + // ... }, "status": { "id": "103186126728896492", "created_at": "2019-11-23T07:49:01.940Z", "in_reply_to_id": "103186038209478945", "in_reply_to_account_id": "14715", - ... + // ... } - }, + } +``` + +### Favourite + +```json { "id": "34975535", "type": "favourite", @@ -37,85 +110,28 @@ menu: "id": "297420", "username": "haskal", "acct": "haskal@cybre.space", - ... + // ... }, "status": { "id": "103186046267791694", "created_at": "2019-11-23T07:28:34.210Z", - ... - }, + // ... "account": { "id": "14715", "username": "trwnh", "acct": "trwnh", - ... + // ... }, - ... + // ... } - }, - ... -] + } ``` -{{< /code >}} - -## Required attributes - -### `id` {#id} - -**Description:** The id of the notification in the database.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:**\ -0.9.9 - added - -### `type` {#type} - -**Description:** The type of event that resulted in the notification.\ -**Type:** String \(Enumerable oneOf\)\ -`follow` = Someone followed you\ -`follow_request` = Someone requested to follow you\ -`mention` = Someone mentioned you in their status\ -`reblog` = Someone boosted one of your statuses\ -`favourite` = Someone favourited one of your statuses\ -`poll` = A poll you have voted in or created has ended\ -`status` = Someone you enabled notifications for has posted a status\ -**Version history:**\ -0.9.9 - added\ -2.8.0 - added `poll`\ -3.1.0 - added `follow_request`\ -3.3.0 - added `status` - -### `created_at` {#created_at} - -**Description:** The timestamp of the notification.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -0.9.9 - added - -### `account` {#account} - -**Description:** The account that performed the action that generated the notification.\ -**Type:** [Account]({{< relref "account.md" >}})\ -**Version history:**\ -0.9.9 - added - -## Optional attributes - -### `status` {#status} - -**Description:** Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.\ -**Type:** [Status]({{< relref "status.md" >}})\ -**Version history:**\ -0.9.9 - added ## See also -{{< page-ref page="account.md" >}} +{{< page-relref ref="methods/notifications" caption="notifications API methods" >}} -{{< page-ref page="status.md" >}} - -{{< page-ref page="methods/notifications.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/notification_serializer.rb" caption="app/serializers/rest/notification\_serializer.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_serializer.rb" caption="app/serializers/rest/notification_serializer.rb" >}} diff --git a/content/en/entities/Poll.md b/content/en/entities/Poll.md new file mode 100644 index 00000000..6d6d84d1 --- /dev/null +++ b/content/en/entities/Poll.md @@ -0,0 +1,142 @@ +--- +title: Poll +description: Represents a poll attached to a status. +menu: + docs: + parent: entities +aliases: [ + "/entities/poll", + "/entities/Poll", + "/api/entities/poll", + "/api/entities/Poll", +] +--- + +## Example + +```json +{ + "id": "34830", + "expires_at": "2019-12-05T04:05:08.302Z", + "expired": true, + "multiple": false, + "votes_count": 10, + "voters_count": null, + "voted": true, + "own_votes": [ + 1 + ], + "options": [ + { + "title": "accept", + "votes_count": 6 + }, + { + "title": "deny", + "votes_count": 4 + } + ], + "emojis": [] +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the poll in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +2.8.0 - added + +### `expires_at` {#expires_at} + +**Description:** When the poll ends.\ +**Type:** {{}} String (ISO 8601 Datetime), or null if the poll does not end\ +**Version history:**\ +2.8.0 - added + +### `expired` {#expired} + +**Description:** Is the poll currently expired?\ +**Type:** Boolean\ +**Version history:**\ +2.8.0 - added + +### `multiple` {#multiple} + +**Description:** Does the poll allow multiple-choice answers?\ +**Type:** Boolean\ +**Version history:**\ +2.8.0 - added + +### `votes_count` {#votes_count} + +**Description:** How many votes have been received.\ +**Type:** Integer\ +**Version history:**\ +2.8.0 - added + +### `voters_count` {#voters_count} + +**Description:** How many unique accounts have voted on a multiple-choice poll.\ +**Type:** {{}} Integer, or null if `multiple` is false.\ +**Version history:**\ +2.8.0 - added + +### `options` {#options} + +**Description:** Possible answers for the poll.\ +**Type:** Array of [Poll::Option](#Option)\ +**Version history:**\ +2.8.0 - added + +### `emojis` {#emojis} + +**Description:** Custom emoji to be used for rendering poll options.\ +**Type:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\ +**Version history:**\ +2.8.0 - added + +### `voted` {{%optional%}} {#voted} + +**Description:** When called with a user token, has the authorized user voted?\ +**Type:** Boolean\ +**Version history:**\ +2.8.0 - added + +### `own_votes` {{%optional%}} {#own_votes} + +**Description:** When called with a user token, which options has the authorized user chosen? Contains an array of index values for `options`.\ +**Type:** Array of Integer\ +**Version history:**\ +2.8.0 - added + +## Poll::Option attributes {#Option} + +### `title` {#option-title} + +**Description:** The text value of the poll option.\ +**Type:** String\ +**Version history:**\ +2.8.0 - added + +#### `votes_count` {#option-votes_count} + +**Description:** The total number of received votes for this option.\ +**Type:** {{}} Integer, or null if results are not published yet.\ +**Version history:**\ +2.8.0 - added + +## See also + +{{< page-relref ref="entities/Status#poll" caption="Status (`poll` attribute)" >}} + +{{< page-relref ref="methods/polls" caption="polls API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/poll_serializer.rb" caption="app/serializers/rest/poll_serializer.rb" >}} + + + + + diff --git a/content/en/entities/Preferences.md b/content/en/entities/Preferences.md new file mode 100644 index 00000000..1fe69ae4 --- /dev/null +++ b/content/en/entities/Preferences.md @@ -0,0 +1,78 @@ +--- +title: Preferences +description: Represents a user's preferences. +menu: + docs: + parent: entities +aliases: [ + "/entities/preferences", + "/entities/Preferences", + "/api/entities/preferences", + "/api/entities/Preferences", +] +--- + +## Example + +```json +{ + "posting:default:visibility": "public", + "posting:default:sensitive": false, + "posting:default:language": null, + "reading:expand:media": "default", + "reading:expand:spoilers": false +} +``` + +## Attributes + +### `posting:default:visibility` {#posting-default-visibility} + +**Description:** Default visibility for new posts. Equivalent to [CredentialAccount#source\[privacy\]]({{< relref "entities/Account#source-privacy" >}}).\ +**Type:** String (Enumerable, oneOf)\ +`public` = Public post\ +`unlisted` = Unlisted post\ +`private` = Followers-only post\ +`direct` = Direct post\ +**Version history:**\ +2.8.0 - added + +### `posting:default:sensitive` {#posting-default-sensitive} + +**Description:** Default sensitivity flag for new posts. Equivalent to [CredentialAccount#source\[sensitive\]]({{< relref "entities/Account#source-sensitive" >}}).\ +**Type:** Boolean\ +**Version history:**\ +2.8.0 - added + +### `posting:default:language` {#posting-default-language} + +**Description:** Default language for new posts. Equivalent to [CredentialAccount#source\[language\]]({{< relref "entities/Account#source-language" >}})\ +**Type:** {{}} String (ISO 639-1 language two-letter code), or null\ +**Version history:**\ +2.8.0 - added + +### `reading:expand:media` {#reading-expand-media} + +**Description:** Whether media attachments should be automatically displayed or blurred/hidden.\ +**Type:** String (Enumerable, oneOf)\ +`default` = Hide media marked as sensitive\ +`show_all` = Always show all media by default, regardless of sensitivity\ +`hide_all` = Always hide all media by default, regardless of sensitivity\ +**Version history:**\ +2.8.0 - added + +### `reading:expand:spoilers` {#reading-expand-spoilers} + +**Description:** Whether CWs should be expanded by default.\ +**Type:** Boolean\ +**Version history:**\ +2.8.0 - added + +## See also + +{{< page-relref ref="methods/preferences" caption="preferences API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preferences_serializer.rb" caption="app/serializers/rest/preferences_serializer.rb" >}} + + + diff --git a/content/en/entities/card.md b/content/en/entities/PreviewCard.md similarity index 78% rename from content/en/entities/card.md rename to content/en/entities/PreviewCard.md index b06656dc..94a21409 100644 --- a/content/en/entities/card.md +++ b/content/en/entities/PreviewCard.md @@ -1,14 +1,26 @@ --- -title: Card +title: PreviewCard description: Represents a rich preview card that is generated using OpenGraph tags from a URL. menu: docs: parent: entities +aliases: [ + "/entities/card", + "/entities/Card", + "/entities/previewcard", + "/entities/PreviewCard", + "/api/entities/card", + "/api/entities/Card", + "/api/entities/previewcard", + "/api/entities/PreviewCard", +] --- -{{< tabs >}} -{{< tab title="video" >}} -```javascript +## Examples + +### Video + +```json { "url": "https://www.youtube.com/watch?v=OMv_EPMED8Y", "title": "♪ Brand New Friend (Christmas Song!)", @@ -26,10 +38,10 @@ menu: "blurhash": "UvK0HNkV,:s9xBR%njog0fo2W=WBS5ozofV@" } ``` -{{< endtab >}} -{{< tab title="photo" >}} -```javascript +### Photo + +```json { "url": "https://www.flickr.com/photos/tomfenskephotography/49088768431/", "title": "Oregon", @@ -47,10 +59,10 @@ menu: "blurhash": "UnE{@jt6M_oIAhjYs+ayT2WBf9ayRkkDXAj[" } ``` -{{< endtab >}} -{{< tab title="link" >}} -```javascript +### Link + +```json { "url": "https://www.theguardian.com/money/2019/dec/07/i-lost-my-193000-inheritance-with-one-wrong-digit-on-my-sort-code", "title": "‘I lost my £193,000 inheritance – with one wrong digit on my sort code’", @@ -68,36 +80,34 @@ menu: "blurhash": null } ``` -{{< endtab >}} -{{< endtabs >}} -## Base attributes +## Attributes -### `url` +### `url` {#url} **Description:** Location of linked resource.\ -**Type:** String \(URL\)\ +**Type:** String (URL)\ **Version history:**\ 1.0.0 - added -### `title` +### `title` {#title} **Description:** Title of linked resource.\ **Type:** String\ **Version history:**\ 1.0.0 - added -### `description` +### `description` {#description} **Description:** Description of preview.\ **Type:** String\ **Version history:**\ 1.0.0 - added -### `type` +### `type` {#type} **Description:** The type of the preview card.\ -**Type:** String \(Enumerable, oneOf\)\ +**Type:** String (Enumerable, oneOf)\ `link` = Link OEmbed\ `photo` = Photo OEmbed\ `video` = Video OEmbed\ @@ -105,8 +115,6 @@ menu: **Version history:**\ 1.3.0 - added -## Optional attributes - ### `author_name` {#author_name} **Description:** The author of the original resource.\ @@ -117,7 +125,7 @@ menu: ### `author_url` {#author_url} **Description:** A link to the author of the original resource.\ -**Type:** String \(URL\)\ +**Type:** String (URL)\ **Version history:**\ 1.3.0 - added @@ -131,55 +139,55 @@ menu: ### `provider_url` {#provider_url} **Description:** A link to the provider of the original resource.\ -**Type:** String \(URL\)\ +**Type:** String (URL)\ **Version history:**\ 1.3.0 - added -### `html` +### `html` {#html} **Description:** HTML to be used for generating the preview card.\ -**Type:** String \(HTML\)\ +**Type:** String (HTML)\ **Version history:**\ 1.3.0 - added -### `width` +### `width` {#height} **Description:** Width of preview, in pixels.\ -**Type:** Number\ +**Type:** Integer\ **Version history:**\ 1.3.0 - added -### `height` +### `height` {#height} **Description:** Height of preview, in pixels.\ -**Type:** Number\ +**Type:** Integer\ **Version history:**\ 1.3.0 - added -### `image` +### `image` {#image} **Description:** Preview thumbnail.\ -**Type:** String \(URL\)\ +**Type:** {{}} String (URL)\ **Version history:**\ 1.0.0 - added ### `embed_url` {#embed_url} **Description:** Used for photo embeds, instead of custom `html`.\ -**Type:** String \(URL\)\ +**Type:** String (URL)\ **Version history:**\ 2.1.0 - added -### `blurhash` +### `blurhash` {#blurhash} + **Description:** A hash computed by [the BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet.\ -**Type:** String\ +**Type:** {{}} String\ **Version history:**\ 3.2.0 - added - ## See also -{{< page-ref page="status.md" >}} +{{< page-relref ref="entities/Status#card" caption="Status (`card` attribute)" >}} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview\_card\_serializer.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/preview_card_serializer.rb" caption="app/serializers/rest/preview_card_serializer.rb" >}} diff --git a/content/en/entities/Reaction.md b/content/en/entities/Reaction.md new file mode 100644 index 00000000..455cec85 --- /dev/null +++ b/content/en/entities/Reaction.md @@ -0,0 +1,79 @@ +--- +title: Reaction +description: Represents an emoji reaction to an Announcement. +menu: + docs: + parent: entities +aliases: [ + "/entities/announcementreaction", + "/entities/AnnouncementReaction", + "/entities/reaction", + "/entities/Reaction", + "/api/entities/announcementreaction", + "/api/entities/AnnouncementReaction", + "/api/entities/reaction", + "/api/entities/Reaction", +] +--- + +## Example + +```json +{ + "name": "bongoCat", + "count": 9, + "me": false, + "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png", + "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png" +}, +{ + "name": "🤔", + "count": 1, + "me": true +} +``` + +## Attributes + +### `name` {#name} + +**Description:** The emoji used for the reaction. Either a unicode emoji, or a custom emoji's shortcode.\ +**Type:** String\ +**Version history:**\ +3.1.0 - added + +### `count` {#count} + +**Description:** The total number of users who have added this reaction.\ +**Type:** Integer\ +**Version history:**\ +3.1.0 - added + +### `me` {{%optional%}} {#me} + +**Description:** If there is a currently authorized user: Have you added this reaction?\ +**Type:** Boolean\ +**Version history:**\ +3.1.0 - added + +### `url` {{%optional%}} {#url} + +**Description:** If the reaction is a custom emoji: A link to the custom emoji.\ +**Type:** String (URL)\ +**Version history:**\ +3.1.0 - added + +### `static_url` {{%optional%}} {#static_url} + +**Description:** If the reaction is a custom emoji: A link to a non-animated version of the custom emoji.\ +**Type:** String (URL)\ +**Version history:**\ +3.1.0 - added + +## See also + +{{< page-relref ref="methods/announcements#put-reactions" caption="Add a reaction to an announcement" >}} + +{{< page-relref ref="methods/announcements#delete-reactions" caption="Delete a reaction from an announcement" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/reaction_serializer.rb" caption="app/serializers/rest/reaction_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/relationship.md b/content/en/entities/Relationship.md similarity index 68% rename from content/en/entities/relationship.md rename to content/en/entities/Relationship.md index 76219099..592248fe 100644 --- a/content/en/entities/relationship.md +++ b/content/en/entities/Relationship.md @@ -4,11 +4,17 @@ description: Represents the relationship between accounts, such as following / b menu: docs: parent: entities +aliases: [ + "/entities/relationship", + "/entities/Relationship", + "/api/entities/relationship", + "/api/entities/Relationship", +] --- ## Example -```javascript +```json { "id": "1", "following": true, @@ -26,56 +32,22 @@ menu: } ``` -## Required attributes +## Attributes -### `id` +### `id` {#id} -**Description:** The account id.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ +**Description:** The account ID.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ **Version history:**\ 0.6.0 - added -### `following` +### `following` {#following} **Description:** Are you following this user?\ **Type:** Boolean\ **Version history:**\ 0.6.0 - added -### `requested` - -**Description:** Do you have a pending follow request for this user?\ -**Type:** Boolean\ -**Version history:**\ -0.9.9 - added - -### `endorsed` - -**Description:** Are you featuring this user on your profile?\ -**Type:** Boolean\ -**Version history:**\ -2.5.0 - added - -### `followed_by` {#followed_by} - -**Description:** Are you followed by this user?\ -**Type:** Boolean\ -**Version history:**\ -0.6.0 - added - -### `muting` - -**Description:** Are you muting this user?\ -**Type:** Boolean\ -**Version history:** Added in 1.1.0 - -### `muting_notifications` {#muting_notifications} - -**Description:** Are you muting notifications from this user?\ -**Type:** Boolean\ -**Version history:**\ -2.1.0 - added - ### `showing_reblogs` {#showing_reblogs} **Description:** Are you receiving this user's boosts in your home timeline?\ @@ -90,20 +62,27 @@ menu: **Version history:**\ 3.3.0 - added -### `blocking` +### `languages` {#languages} + +**Description:** Which languages are you following from this user?\ +**Type:** Array of String (ISO 639-1 language two-letter code)\ +**Version history:**\ +4.0.0 - added + +### `followed_by` {#followed_by} + +**Description:** Are you followed by this user?\ +**Type:** Boolean\ +**Version history:**\ +0.6.0 - added + +### `blocking` {#blocking} **Description:** Are you blocking this user?\ **Type:** Boolean\ **Version history:**\ 0.6.0 - added -### `domain_blocking` {#domain_blocking} - -**Description:** Are you blocking this user's domain?\ -**Type:** Boolean\ -**Version history:**\ -1.4.0 - added - ### `blocked_by` {#blocked_by} **Description:** Is this user blocking you?\ @@ -111,7 +90,42 @@ menu: **Version history:**\ 2.8.0 - added -### `note` +### `muting` {#muting} + +**Description:** Are you muting this user?\ +**Type:** Boolean\ +**Version history:**\ +1.1.0 - added + +### `muting_notifications` {#muting_notifications} + +**Description:** Are you muting notifications from this user?\ +**Type:** Boolean\ +**Version history:**\ +2.1.0 - added + +### `requested` {#requested} + +**Description:** Do you have a pending follow request for this user?\ +**Type:** Boolean\ +**Version history:**\ +0.9.9 - added + +### `domain_blocking` {#domain_blocking} + +**Description:** Are you blocking this user's domain?\ +**Type:** Boolean\ +**Version history:**\ +1.4.0 - added + +### `endorsed` {#endorsed} + +**Description:** Are you featuring this user on your profile?\ +**Type:** Boolean\ +**Version history:**\ +2.5.0 - added + +### `note` {#note} **Description:** This user's profile bio\ **Type:** String\ @@ -120,6 +134,6 @@ menu: ## See also -* [GET /api/v1/accounts/relationships]({{< relref "../methods/accounts.md#check-relationships-to-other-accounts" >}}) +{{< page-relref ref="methods/accounts#relationships" caption="POST /api/v1/accounts/relationships" >}} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/relationship_serializer.rb" caption="app/serializers/rest/relationship\_serializer.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/relationship_serializer.rb" caption="app/serializers/rest/relationship_serializer.rb" >}} diff --git a/content/en/entities/Report.md b/content/en/entities/Report.md new file mode 100644 index 00000000..00fec01c --- /dev/null +++ b/content/en/entities/Report.md @@ -0,0 +1,140 @@ +--- +title: Report +description: Reports filed against users and/or statuses, to be taken action on by moderators. +menu: + docs: + parent: entities +aliases: [ + "/entities/report", + "/entities/Report", + "/api/entities/report", + "/api/entities/Report", +] +--- + +## Example + +```json +{ + "id": "48914", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "Spam account", + "forwarded": false, + "created_at": "2022-08-25T09:56:16.763Z", + "status_ids": [ + "108882889550545820" + ], + "rule_ids": null, + "target_account": { + "id": "108366849347798387", + "username": "Baluke", + "acct": "Baluke", + "display_name": "Baluke Dental Studios", + "locked": false, + "bot": false, + "discoverable": false, + "group": false, + "created_at": "2022-05-26T00:00:00.000Z", + "note": "

Baluke Dental Studios is a full service dental lab offering fabrication, staining, and digital services. Advanced technologies and a meticulous process ensure reduced chair time, lower costs, and better patient outcomes with beautiful smiles. Talk to a representative today.

https://baluke.com/

", + "url": "https://mastodon.social/@Baluke", + "avatar": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png", + "avatar_static": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png", + "header": "https://static-cdn.mastodon.social/headers/original/missing.png", + "header_static": "https://static-cdn.mastodon.social/headers/original/missing.png", + "followers_count": 0, + "following_count": 0, + "statuses_count": 38, + "last_status_at": "2022-08-25", + "emojis": [], + "fields": [] + } +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the report in the database.\ +**Type:** String (cast from integer)\ +**Version history:**\ +1.1.0 - added + +### `action_taken` {#action_taken} + +**Description:** Whether an action was taken yet.\ +**Type:** Boolean\ +**Version history:**\ +1.1.0 - added + +### `action_taken_at` {#action_taken_at} + +**Description:** When an action was taken against the report.\ +**Type:** {{}} String (ISO 8601 Datetime) or null\ +**Version history:**\ +4.0.0 - added + +### `category` {#category} + +**Description:** The generic reason for the report.\ +**Type:** String (Enumerable oneOf)\ +`spam` = Unwanted or repetitive content\ +`violation` = A specific rule was violated\ +`other` = Some other reason\ +**Version history:**\ +4.0.0 - added + +### `comment` {#comment} + +**Description:** The reason for the report.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `forwarded` {#forwarded} + +**Description:** Whether the report was forwarded to a remote domain.\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +### `created_at` {#created_at} + +**Description:** When the report was created.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +### `status_ids` {#status_ids} + +**Description:** The domain name of the instance.\ +**Type:** {{}} Array of String (cast from integer), or null\ +**Version history:**\ +4.0.0 - added + +### `rule_ids` {#rule_ids} + +**Description:** The domain name of the instance.\ +**Type:** {{}} Array of String (cast from integer), or null\ +**Version history:**\ +4.0.0 - added + +### `target_account` {#target_account} + +**Description:** The account that was reported.\ +**Type:** [Account]({{< relref "entities/account" >}})\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="methods/reports" caption="reports API methods" >}} + +{{< page-relref ref="entities/Notification#report" caption="Notification (`report` attribute)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/report_serializer.rb" caption="app/serializers/rest/report_serializer.rb" >}} + + + diff --git a/content/en/entities/Role.md b/content/en/entities/Role.md new file mode 100644 index 00000000..381dde8d --- /dev/null +++ b/content/en/entities/Role.md @@ -0,0 +1,154 @@ +--- +title: Role +description: Represents a custom user role that grants permissions. +menu: + docs: + parent: entities +aliases: [ + "/entities/role", + "/entities/Role", + "/api/entities/role", + "/api/entities/Role", +] +--- + +## Example + +```json +{ + "id": 3, + "name": "Owner", + "color": "#ff3838", + "position": 1000, + "permissions": 1, + "highlighted": true, + "created_at": "2022-09-08T22:48:07.983Z", + "updated_at": "2022-09-08T22:48:07.983Z" +}, +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the Role in the database.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +### `name` {#name} + +**Description:** The name of the role.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `color` {#color} + +**Description:** The hex code assigned to this role. If no hex code is assigned, the string will be empty.\ +**Type:** String\ +**Version history:**\ +4.0.0 - added + +### `position` {#position} + +**Description:** An index for the role's position. The higher the position, the more priority the role has over other roles.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +### `permissions` {#permissions} + +**Description:** A bitmask that represents the sum of all permissions granted to the role.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +### `highlighted` {#highlighted} + +**Description:** Whether the role is publicly visible as a badge on user profiles.\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +### `created_at` {#created_at} + +**Description:** The date that the role was created.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +### `updated_at` {#created_at} + +**Description:** The date that the role was updated.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +4.0.0 - added + +## Permission flags + +To determine the permissions available to a certain role, convert the `permissions` attribute to binary and compare from the least significant bit upwards. For convenience (and to prevent the terms from growing too long), permissions will be presented below using hexadecimal values. + +0x1 +: **Administrator**. Users with this permission bypass all permissions. + +0x2 +: **Devops**. Allows users to access Sidekiq and pgHero dashboards. + +0x4 +: **View Audit Log**. Allows users to see history of admin actions. + +0x8 +: **View Dashboard**. Allows users to access the dashboard and various metrics. + +0x10 +: **Manage Reports**. Allows users to review reports and perform moderation actions against them. + +0x20 +: **Manage Federation**. Allows users to block or allow federation with other domains, and control deliverability. + +0x40 +: **Manage Settings**. Allows users to change site settings. + +0x80 +: **Manage Blocks**. Allows users to block e-mail providers and IP addresses. + +0x100 +: **Manage Taxonomies**. Allows users to review trending content and update hashtag settings. + +0x200 +: **Manage Appeals**. Allows users to review appeals against moderation actions. + +0x400 +: **Manage Users**. Allows users to view other users' details and perform moderation actions against them. + +0x800 +: **Manage Invites**. Allows users to browse and deactivate invite links. + +0x1000 +: **Manage Rules**. Allows users to change server rules. + +0x2000 +: **Manage Announcements**. Allows users to manage announcements on the server. + +0x4000 +: **Manage Custom Emojis**. Allows users to manage custom emojis on the server. + +0x8000 +: **Manage Webhooks**. Allows users to set up webhooks for administrative events. + +0x10000 +: **Invite Users**. Allows users to invite new people to the server. + +0x20000 +: **Manage Roles**. Allows users to manage and assign roles below theirs. + +0x40000 +: **Manage User Access**. Allows users to disable other users' two-factor authentication, change their e-mail address, and reset their password. + +0x80000 +: **Delete User Data**. Allows users to delete other users' data without delay. + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/role_serializer.rb" caption="app/serializers/rest/role_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Rule.md b/content/en/entities/Rule.md new file mode 100644 index 00000000..f7b3facc --- /dev/null +++ b/content/en/entities/Rule.md @@ -0,0 +1,50 @@ +--- +title: Rule +description: Represents a rule that server users should follow. +menu: + docs: + parent: entities +aliases: [ + "/entities/rule", + "/entities/Rule", + "/api/entities/rule", + "/api/entities/Rule", +] +--- + +## Example + +```json +{ + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" +} +``` + +## Base attributes + +### `id` {#name} + +**Description:** An identifier for the rule.\ +**Type:** String (cast from integer, but not guaranteed to be a number)\ +**Version history:**\ +3.4.0 - added + +### `text` {#url} + +**Description:** The rule to be followed.\ +**Type:** String \ +**Version history:**\ +3.4.0 - added + +## See also + +{{< page-relref ref="methods/instance#rules" caption="GET /api/v1/instance/rules" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/rule.rb" caption="app/models/rule.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/rule_serializer.rb" caption="app/serializers/rest/rule_serializer.rb" >}} + + + + diff --git a/content/en/entities/ScheduledStatus.md b/content/en/entities/ScheduledStatus.md new file mode 100644 index 00000000..b5aaa14c --- /dev/null +++ b/content/en/entities/ScheduledStatus.md @@ -0,0 +1,108 @@ +--- +title: ScheduledStatus +description: Represents a status that will be published at a future scheduled date. +menu: + docs: + parent: entities +aliases: [ + "/entities/scheduledstatus", + "/entities/ScheduledStatus", + "/api/entities/scheduledstatus", + "/api/entities/ScheduledStatus", +] +--- + +## Example + + + +Returned from `POST /api/v1/statuses?status=test post&scheduled_at=2022-09-29` + +```json +{ + "id": "1", + "scheduled_at": "2022-09-29T00:00:00.000Z", + "params": { + "text": "test post", + "media_ids": null, + "sensitive": null, + "spoiler_text": null, + "visibility": null, + "language": null, + "scheduled_at": null, + "poll": null, + "idempotency": null, + "with_rate_limit": false, + "in_reply_to_id": null, + "application_id": 3 + }, + "media_attachments": [] +} +``` + +Returned from `GET /api/v1/scheduled_statuses`: + +```json +{ + "id": "1", + "scheduled_at": "2022-09-29T00:00:00.000Z", + "params": { + "poll": null, + "text": "test post", + "language": null, + "media_ids": null, + "sensitive": null, + "visibility": null, + "idempotency": null, + "scheduled_at": null, + "spoiler_text": null, + "application_id": 3, + "in_reply_to_id": null, + "with_rate_limit": false + }, + "media_attachments": [] +} +``` + +## Required attributes + +### `id` {#id} + +**Description:** ID of the scheduled status in the database.\ +**Type:** String (cast from an integer but not guaranteed to be a number)\ +**Version history:**\ +2.7.0 - added + +### `scheduled_at` {#scheduled_at} + +**Description:** ID of the status in the database.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +2.7.0 - added + +### `params` {#params} + +**Description:** The parameters to be used when the status is posted.\ +**Type:** Hash\ +**Version history:**\ +2.7.0 - added + +### `media_attachments` {#media_attachments} + +**Description:** Media that will be attached when the status is posted.\ +**Type:** Array of [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\ +**Version history:**\ +2.7.0 - added + +## See also + +{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (with `scheduled_at` parameter)" >}} + +{{< page-relref ref="methods/scheduled_statuses" caption="scheduled_statuses API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/scheduled_status_serializer.rb" caption="app/serializers/rest/scheduled_status_serializer.rb" >}} + + + diff --git a/content/en/entities/results.md b/content/en/entities/Search.md similarity index 63% rename from content/en/entities/results.md rename to content/en/entities/Search.md index 23c75da1..13bc13cb 100644 --- a/content/en/entities/results.md +++ b/content/en/entities/Search.md @@ -1,15 +1,26 @@ --- -title: Results +title: Search description: Represents the results of a search. menu: docs: parent: entities +aliases: [ + "/entities/results", + "/entities/Results", + "/entities/search", + "/entities/Search", + "/api/entities/results", + "/api/entities/Results", + "/api/entities/search", + "/api/entities/Search", +] --- ## Example -{{< code title="Truncated sample search for q=cats limit=2" >}} -```javascript +Truncated sample search for q=cats limit=2 + +```json { "accounts": [ { @@ -17,39 +28,34 @@ menu: "username": "catstar", "acct": "catstar@catgram.jp", "display_name": "catstar", - ... - + // ... }, { "id": "214293", "username": "catsareweird", "acct": "catsareweird", "display_name": "Cats Are Weird", - ... - + // ... } ], "statuses": [ { "id": "103085519055545958", "created_at": "2019-11-05T13:23:09.000Z", - ... - + // ... "content": "

cats
cats never change

", - ... - + // ... }, { "id": "101068121469614510", "created_at": "2018-11-14T06:31:48.000Z", - ... - + // ... "spoiler_text": "Cats", - ... - + // ... "content": "

Cats are inherently good at self-care.

#cats", - ... - + // ... + }, + // ... ], "hashtags": [ { @@ -61,8 +67,7 @@ menu: "uses": "10", "accounts": "9" }, - ... - + // ... ] }, { @@ -74,40 +79,41 @@ menu: "uses": "6", "accounts": "5" }, - ... - + // ... ] } ] } ``` -{{< /code >}} -## Required attributes +## Attributes ### `accounts` {#accounts} **Description:** Accounts which match the given query\ -**Type:** Array of [Account]({{< relref "account.md" >}})\ +**Type:** Array of [Account]({{< relref "entities/Account" >}})\ **Version history:** Added in x.x.x ### `statuses` {#statuses} **Description:** Statuses which match the given query\ -**Type:** Array of [Status]({{< relref "status.md" >}})\ +**Type:** Array of [Status]({{< relref "entities/Status" >}})\ **Version history:** Added in x.x.x ### `hashtags` {#hashtags} **Description:** Hashtags which match the given query\ -**Type:** Array of [Tag]({{< relref "tag.md" >}}) \(v2\). Array of String \(v1\).\ -**Version history:** v1 added in 1.1.0 and deprecated in 3.0.0. v2 added in 2.4.1 and replaced v1 in 3.0.0. +**Type:** Array of [Tag]({{< relref "entities/Tag" >}})\ +**Version history:**\ +1.1.0 - added\ +2.4.1 - v1 deprecated because it returns Array of String. v2 added which returns Array of Tag.\ +3.0.0 - v1 removed ## See also -{{< page-ref page="methods/search.md" >}} +{{< page-relref ref="methods/search" caption="search API methods" >}} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/search_serializer.rb" caption="app/serializers/rest/search\_serializer.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/search_serializer.rb" caption="app/serializers/rest/search_serializer.rb" >}} diff --git a/content/en/entities/status.md b/content/en/entities/Status.md similarity index 52% rename from content/en/entities/status.md rename to content/en/entities/Status.md index 7ae2eb0b..4ed96a5e 100644 --- a/content/en/entities/status.md +++ b/content/en/entities/Status.md @@ -4,11 +4,21 @@ description: Represents a status posted by an account. menu: docs: parent: entities +aliases: [ + "/entities/mention", + "/entities/Mention", + "/entities/status", + "/entities/Status", + "/api/entities/mention", + "/api/entities/Mention", + "/api/entities/status", + "/api/entities/Status", +] --- ## Example -```javascript +```json { "id": "103270115826048975", "created_at": "2019-12-08T03:48:33.901Z", @@ -90,202 +100,296 @@ menu: } ``` -## Base attributes +## Attributes ### `id` {#id} **Description:** ID of the status in the database.\ -**Type:** String \(cast from an integer but not guaranteed to be a number\)\ -**Version history:** Added in 0.1.0 +**Type:** String (cast from an integer but not guaranteed to be a number)\ +**Version history:**\ +0.1.0 - added ### `uri` {#uri} **Description:** URI of the status used for federation.\ **Type:** String\ -**Version history:** Added in 0.1.0 +**Version history:**\ +0.1.0 - added ### `created_at` {#created_at} **Description:** The date when this status was created.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:** Added in 0.1.0 +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +0.1.0 - added ### `account` {#account} **Description:** The account that authored this status.\ -**Type:** [Account]({{< relref "account.md" >}})\ -**Version history:** Added in 0.1.0 +**Type:** [Account]({{< relref "entities/Account" >}})\ +**Version history:**\ +0.1.0 - added ### `content` {#content} **Description:** HTML-encoded status content.\ -**Type:** String \(HTML\)\ -**Version history:** Added in 0.1.0 +**Type:** String (HTML)\ +**Version history:**\ +0.1.0 - added ### `visibility` {#visibility} **Description:** Visibility of this status.\ -**Type:** String \(Enumerable oneOf\)\ +**Type:** String (Enumerable oneOf)\ `public` = Visible to everyone, shown in public timelines.\ `unlisted` = Visible to public, but not included in public timelines.\ `private` = Visible to followers only, and to any mentioned users.\ `direct` = Visible only to mentioned users.\ -**Version history:** Added in 0.9.9 +**Version history:**\ +0.9.9 - added ### `sensitive` {#sensitive} **Description:** Is this status marked as sensitive content?\ **Type:** Boolean\ -**Version history:** Added in 0.9.9 +**Version history:**\ +0.9.9 - added ### `spoiler_text` {#spoiler_text} **Description:** Subject or summary line, below which status content is collapsed until expanded.\ **Type:** String\ -**Version history:** Added in 1.0.0 +**Version history:**\ +1.0.0 - added ### `media_attachments` {#media_attachments} **Description:** Media that is attached to this status.\ -**Type:** Array of [Attachment]({{< relref "attachment.md" >}})\ -**Version history:** Added in 0.6.0 +**Type:** Array of [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\ +**Version history:**\ +0.6.0 - added -### `application` {#application} +### `application` {{%optional%}} {#application} **Description:** The application used to post this status.\ -**Type:** [Application]({{< relref "application.md" >}})\ -**Version history:** Added in 0.9.9 +**Type:** Hash\ +**Version history:**\ +0.9.9 - added -## Rendering attributes +#### `application[name]` {#application-name} + +**Description:** The name of the application that posted this status.\ +**Type:** String\ +**Version history:**\ +0.9.9 - added + +#### `application[website]` {#application-website} + +**Description:** The website associated with the application that posted this status.\ +**Type:** {{}} String (URL) or null\ +**Version history:**\ +0.9.9 - added +3.5.1 - this property is now nullable ### `mentions` {#mentions} **Description:** Mentions of users within the status content.\ -**Type:** Array of [Mention]({{< relref "mention.md" >}})\ -**Version history:** Added in 0.6.0 +**Type:** Array of [Status::Mention](#Mention)\ +**Version history:**\ +0.6.0 - added ### `tags` {#tags} **Description:** Hashtags used within the status content.\ -**Type:** Array of [Tag]({{< relref "tag.md" >}})\ -**Version history:** Added in 0.9.0 +**Type:** Array of [Status::Tag](#Tag)\ +**Version history:**\ +0.6.0 - added ### `emojis` {#emojis} **Description:** Custom emoji to be used when rendering status content.\ -**Type:** Array of [Emoji]({{< relref "emoji.md" >}})\ -**Version history:** Added in 2.0.0 - -## Informational attributes +**Type:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\ +**Version history:**\ +2.0.0 - added ### `reblogs_count` {#reblogs_count} **Description:** How many boosts this status has received.\ -**Type:** Number\ -**Version history:** Added in 0.1.0 +**Type:** Integer\ +**Version history:**\ +0.1.0 - added ### `favourites_count` {#favorites_count} **Description:** How many favourites this status has received.\ -**Type:** Number\ -**Version history:** Added in 0.1.0 +**Type:** Integer\ +**Version history:**\ +0.1.0 - added ### `replies_count` {#replies_count} **Description:** How many replies this status has received.\ -**Type:** Number\ -**Version history:** Added in 2.5.0 - -## Nullable attributes +**Type:** Integer\ +**Version history:**\ +2.5.0 - added ### `url` {#url} **Description:** A link to the status's HTML representation.\ -**Type:** String \(URL\)\ -**Version history:** Added in 0.1.0 +**Type:** {{}} String (URL) or null\ +**Version history:**\ +0.1.0 - added ### `in_reply_to_id` {#in_reply_to_id} -**Description:** ID of the status being replied.\ -**Type:** String \(cast from an integer but not guaranteed to be a number\)\ -**Version history:** Added in 0.1.0 +**Description:** ID of the status being replied to.\ +**Type:** {{}} String (cast from an integer but not guaranteed to be a number) or null\ +**Version history:**\ +0.1.0 - added ### `in_reply_to_account_id` {#in_reply_to_account_id} -**Description:** ID of the account being replied to.\ -**Type:** String \(cast from an integer but not guaranteed to be a number\)\ -**Version history:** Added in 1.0.0 +**Description:** ID of the account that authored the status being replied to.\ +**Type:** {{}} String (cast from an integer but not guaranteed to be a number) or null\ +**Version history:**\ +0.1.0 - added ### `reblog` {#reblog} **Description:** The status being reblogged.\ -**Type:** [Status]({{< relref "status.md" >}})\ -**Version history:** Added in 0.1.0 +**Type:** {{}} [Status](#) or null\ +**Version history:**\ +0.1.0 - added ### `poll` {#poll} **Description:** The poll attached to the status.\ -**Type:** [Poll]({{< relref "poll.md" >}})\ -**Version history:** Added in 2.8.0 +**Type:** {{}} [Poll]({{< relref "entities/Poll" >}}) or null\ +**Version history:**\ +2.8.0 - added ### `card` {#card} **Description:** Preview card for links included within status content.\ -**Type:** [Card]({{< relref "card.md" >}})\ -**Version history:** Added in 2.6.0 +**Type:** {{}} [PreviewCard]({{< relref "entities/PreviewCard" >}}) or null\ +**Version history:**\ +2.6.0 - added ### `language` {#language} **Description:** Primary language of this status.\ -**Type:** String \(ISO 639 Part 1 two-letter language code\)\ -**Version history:** Added in 1.4.0 +**Type:** {{}} String (ISO 639 Part 1 two-letter language code) or null\ +**Version history:**\ +1.4.0 - added ### `text` {#text} **Description:** Plain-text source of a status. Returned instead of `content` when status is deleted, so the user may redraft from the source text without the client having to reverse-engineer the original text from the HTML content.\ +**Type:** {{}} String or null\ +**Version history:**\ +2.9.0 - added + +### `edited_at` {#edited_at} + +**Description:** Timestamp of when the status was last edited.\ +**Type:** {{}} String (ISO 8601 Datetime)\ +**Version history:**\ +3.5.0 - added + +### `favourited` {{%optional%}} {#favourited} + +**Description:** If the current token has an authorized user: Have you favourited this status?\ +**Type:** Boolean\ +**Version history:**\ +0.1.0 - added + +### `reblogged` {{%optional%}} {#reblogged} + +**Description:** If the current token has an authorized user: Have you boosted this status?\ +**Type:** Boolean\ +**Version history:**\ +0.1.0 - added + +### `muted` {{%optional%}} {#muted} + +**Description:** If the current token has an authorized user: Have you muted notifications for this status's conversation?\ +**Type:** Boolean\ +**Version history:**\ +1.4.0 - added + +### `bookmarked` {{%optional%}} {#bookmarked} + +**Description:** If the current token has an authorized user: Have you bookmarked this status?\ +**Type:** Boolean\ +**Version history:**\ +3.1.0 - added + +### `pinned` {{%optional%}} {#pinned} + +**Description:** If the current token has an authorized user: Have you pinned this status? Only appears if the status is pinnable.\ +**Type:** Boolean\ +**Version history:**\ +1.6.0 - added + +### `filtered` {{%optional%}} {#filtered} + +**Description:** If the current token has an authorized user: The filter and keywords that matched this status.\ +**Type:** Array of [FilterResult]({{ relref "entities/FilterResult" }})\ +**Version history:**\ +4.0.0 - added + +## Status::Mention attributes {#Mention} + +### `id` {#Mention-id} + +**Description:** The account ID of the mentioned user.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +0.6.0 - added + +### `username` {#Mention-username} + +**Description:** The username of the mentioned user.\ **Type:** String\ -**Version history:** Added in 2.9.0 +**Version history:**\ +0.6.0 - added -## Authorized user attributes +### `url` {#Mention-url} -### `favourited` {#favourited} +**Description:** The location of the mentioned user's profile.\ +**Type:** String (URL)\ +**Version history:**\ +0.6.0 - added -**Description:** Have you favourited this status?\ -**Type:** Boolean\ -**Version history:** Added in 0.1.0 +### `acct` {#Mention-acct} -### `reblogged` {#reblogged} +**Description:** The webfinger acct: URI of the mentioned user. Equivalent to `username` for local users, or `username@domain` for remote users.\ +**Type:** String\ +**Version history:**\ +0.6.0 - added -**Description:** Have you boosted this status?\ -**Type:** Boolean\ -**Version history:** Added in 0.1.0 +## Status::Tag attributes {#Tag} -### `muted` {#muted} +### `name` {#Tag-name} -**Description:** Have you muted notifications for this status's conversation?\ -**Type:** Boolean\ -**Version history:** Added in 1.4.0 +**Description:** The value of the hashtag after the # sign.\ +**Type:** String\ +**Version history:**\ +0.9.0 - added -### `bookmarked` {#bookmarked} +### `url` {#Tag-url} -**Description:** Have you bookmarked this status?\ -**Type:** Boolean\ -**Version history:** Added in 3.1.0 - -### `pinned` {#pinned} - -**Description:** Have you pinned this status? Only appears if the status is pinnable.\ -**Type:** Boolean\ -**Version history:** Added in 1.6.0 +**Description:** A link to the hashtag on the instance.\ +**Type:** String (URL)\ +**Version history:**\ +0.9.0 - added ## See also -* GET accounts/:id/statuses -* GET /api/v2/search - -{{< page-ref page="methods/statuses.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/status_serializer.rb" caption="app/serializers/rest/status\_serializer.rb" >}} +{{< page-relref ref="methods/accounts#statuses" caption="GET /api/v1/accounts/:id/statuses" >}} +{{< page-relref ref="methods/search#v2" caption="POST /api/v2/search/" >}} +{{< page-relref ref="methods/statuses" caption="statuses methods" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_serializer.rb" caption="app/serializers/rest/status_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/StatusEdit.md b/content/en/entities/StatusEdit.md new file mode 100644 index 00000000..5c06afb9 --- /dev/null +++ b/content/en/entities/StatusEdit.md @@ -0,0 +1,111 @@ +--- +title: StatusEdit +description: Represents a revision of a status that has been edited. +menu: + docs: + parent: entities +aliases: [ + "/entities/statusedit", + "/entities/StatusEdit", + "/api/entities/statusedit", + "/api/entities/StatusEdit", +] +--- + +## Example + +```json +{ + "content": "

this is a status that has been edited three times. this time a poll has been added.

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-05T00:03:32.480Z", + "poll": { + "options": [ + { + "title": "cool" + }, + { + "title": "uncool" + }, + { + "title": "spiderman (this option has been changed)" + } + ] + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] +} +``` + +## Attributes + +### `content` {#content} + +**Description:** The content of the status at this revision.\ +**Type:** String (HTML)\ +**Version history:**\ +3.5.0 - added + +### `spoiler_text` {#spoiler_text} + +**Description:** The content of the subject or content warning at this revision.\ +**Type:** String (HTML)\ +**Version history:**\ +3.5.0 - added + +### `sensitive` {#sensitive} + +**Description:** Whether the status was marked sensitive at this revision.\ +**Type:** Boolean\ +**Version history:**\ +3.5.0 - added + +### `created_at` {#created_at} + +**Description:** The timestamp of when the revision was published.\ +**Type:** String (ISO 8601 Datetime)\ +**Version history:**\ +3.5.0 - added + +### `account` {#account} + +**Description:** The account that published this revision.\ +**Type:** Account\ +**Version history:**\ +3.5.0 - added + +### `poll` {{%optional%}} {#poll} + +**Description:** The current state of the poll options at this revision. Note that edits changing the poll options will be collapsed together into one edit, since this action resets the poll.\ +**Type:** Hash with `options` (Array of Hash with `title`)\ +**Version history:**\ +3.5.0 - added + +### `media_attachments` {#media_attachments} + +**Description:** The current state of the poll options at this revision. Note that edits changing the poll options will be collapsed together into one edit, since this action resets the poll.\ +**Type:** Array of [MediaAttachment]({{}})\ +**Version history:**\ +3.5.0 - added + +### `emojis` {#emojis} + +**Description:** Any custom emoji that are used in the current revision.\ +**Type:** Array of [CustomEmoji]({{}})\ +**Version history:**\ +3.5.0 - added + +## See also + +{{< page-relref ref="methods/statuses#history" caption="GET /api/v1/statuses/:id/history" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_edit_serializer.rb" caption="app/serializers/rest/status_edit_serializer.rb" >}} + diff --git a/content/en/entities/StatusSource.md b/content/en/entities/StatusSource.md new file mode 100644 index 00000000..5dcb611b --- /dev/null +++ b/content/en/entities/StatusSource.md @@ -0,0 +1,52 @@ +--- +title: StatusSource +description: Represents a status's source as plain text. +menu: + docs: + parent: entities +aliases: [ + "/entities/statussource", + "/entities/StatusSource", + "/api/entities/statussource", + "/api/entities/StatusSource", +] +--- + +## Example + +```json +{ + "id": "108942703571991143", + "text": "this is a status that will be edited", + "spoiler_text": "" +} +``` + +## Attributes + +### `id` {#id} + +**Description:** ID of the status in the database.\ +**Type:** String (cast from an integer but not guaranteed to be a number)\ +**Version history:**\ +3.5.0 - added + +### `text` {#text} + +**Description:** The plain text used to compose the status.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +### `spoiler_text` {#spoiler_text} + +**Description:** The plain text used to compose the status's subject or content warning.\ +**Type:** String\ +**Version history:**\ +3.5.0 - added + +## See also + +{{< page-relref ref="methods/statuses#source" caption="GET /api/v1/statuses/:id/source" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/status_source_serializer.rb" caption="app/serializers/rest/status_source_serializer.rb" >}} \ No newline at end of file diff --git a/content/en/entities/Suggestion.md b/content/en/entities/Suggestion.md new file mode 100644 index 00000000..d0dec34d --- /dev/null +++ b/content/en/entities/Suggestion.md @@ -0,0 +1,57 @@ +--- +title: Suggestion +description: Represents a suggested account to follow and an associated reason for the suggestion. +menu: + docs: + parent: entities +aliases: [ + "/entities/suggestion", + "/entities/Suggestion", + "/api/entities/suggestion", + "/api/entities/Suggestion", +] +--- + +## Example + +```json +{ + "source": "staff", + "account": { + "id": "109031732217496096", + "username": "alice", + "acct": "alice", + // ... + } +} +``` + +## Attributes + +### `source` {#source} + +**Description:** The reason this account is being suggested.\ +**Type:** String (Enumerable oneOf)\ +`staff` = This account was manually recommended by your administration team\ +`past_interactions` = You have interacted with this account previously\ +`global` = This account has many reblogs, favourites, and active local followers within the last 30 days +**Version history:**\ +3.4.0 - added + +### `account` {#account} + +**Description:** The account being recommended to follow.\ +**Type:** [Account]({{< relref "entities/Account" >}})\ +**Version history:**\ +3.4.0 - added + +## See also + +{{< page-relref ref="methods/suggestions#v2" caption="GET /api/v2/suggestions" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/suggestion_serializer.rb" caption="app/serializers/rest/suggestion_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_suggestions.rb" caption="app/models/account_suggestions.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_suggestions/" caption="app/models/account_suggestions/" >}} + diff --git a/content/en/entities/Tag.md b/content/en/entities/Tag.md new file mode 100644 index 00000000..1cb4f3dd --- /dev/null +++ b/content/en/entities/Tag.md @@ -0,0 +1,132 @@ +--- +title: Tag +description: Represents a hashtag used within the content of a status. +menu: + docs: + parent: entities +aliases: [ + "/entities/history", + "/entities/History", + "/entities/tag", + "/entities/Tag", + "/api/entities/history", + "/api/entities/History", + "/api/entities/tag", + "/api/entities/Tag", +] +--- + +## Example + +```json +{ + "name": "nowplaying", + "url": "https://mastodon.social/tags/nowplaying", + "history": [ + { + "day": "1574553600", + "uses": "200", + "accounts": "31" + }, + { + "day": "1574467200", + "uses": "272", + "accounts": "39" + }, + { + "day": "1574380800", + "uses": "345", + "accounts": "40" + }, + { + "day": "1574294400", + "uses": "366", + "accounts": "46" + }, + { + "day": "1574208000", + "uses": "226", + "accounts": "32" + }, + { + "day": "1574121600", + "uses": "217", + "accounts": "42" + }, + { + "day": "1574035200", + "uses": "214", + "accounts": "34" + } + ], + "following": false +} +``` + +## Attributes + +### `name` {#name} + +**Description:** The value of the hashtag after the \# sign.\ +**Type:** String\ +**Version history:**\ +0.9.0 - added + +### `url` {#url} + +**Description:** A link to the hashtag on the instance.\ +**Type:** String (URL)\ +**Version history:**\ +0.9.0 - added + +### `history` {#history} + +**Description:** Usage statistics for given days (typically the past week).\ +**Type:** Array of Hash\ +**Version history:**\ +2.4.1 - added + +#### `history[][day]` {#history-day} + +**Description:** UNIX timestamp on midnight of the given day.\ +**Type:** String (UNIX timestamp)\ +**Version history:**\ +2.4.1 - added + +#### `history[][uses]` {#history-uses} + +**Description:** The counted usage of the tag within that day.\ +**Type:** String (cast from an integer)\ +**Version history:**\ +2.4.1 - added + +#### `history[][accounts]` {#history-accounts} + +**Description:** The total of accounts using the tag within that day.\ +**Type:** String (cast from an integer)\ +**Version history:**\ +2.4.1 - added + +### `following` {{%optional%}} {#following} + +**Description:** Whether the current token's authorized user is following this tag.\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="entities/Search#tags" caption="Search (`tags` attribute)" >}} + +{{< page-relref ref="methods/tags" caption="tags API methods" >}} + + +{{< page-relref ref="methods/featured_tags#suggestions" caption="GET /api/v1/featured_tags/suggestions" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/tag_serializer.rb" caption="app/serializers/rest/tag_serializer.rb" >}} + + + diff --git a/content/en/entities/token.md b/content/en/entities/Token.md similarity index 61% rename from content/en/entities/token.md rename to content/en/entities/Token.md index 1e4883ad..4905b41b 100644 --- a/content/en/entities/token.md +++ b/content/en/entities/Token.md @@ -4,11 +4,17 @@ description: Represents an OAuth token used for authenticating with the API and menu: docs: parent: entities +aliases: [ + "/entities/token", + "/entities/Token", + "/api/entities/token", + "/api/entities/Token", +] --- ## Example -```javascript +```json { "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0", "token_type": "Bearer", @@ -23,33 +29,36 @@ menu: **Description:** An OAuth token to be used for authorization.\ **Type:** String\ -**Version history:** Added in 0.1.0 +**Version history:**\ +0.1.0 - added ### `token_type` {#token_type} **Description:** The OAuth token type. Mastodon uses `Bearer` tokens.\ **Type:** String\ -**Version history:** Added in 0.1.0 +**Version history:**\ +0.1.0 - added ### `scope` {#scope} **Description:** The OAuth scopes granted by this token, space-separated.\ **Type:** String\ -**Version history:** Added in 0.1.0 +**Version history:**\ +0.1.0 - added ### `created_at` {#created_at} **Description:** When the token was generated.\ -**Type:** Number \(UNIX Timestamp\)\ -**Version history:** Added in 0.1.0 +**Type:** Number (UNIX Timestamp)\ +**Version history:**\ +0.1.0 - added ## See also -* [Example authorization code flow]({{< relref "../client/token.md#example-authorization-code-flow" >}}) -* [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) -* [POST /oauth/token]({{< relref "../methods/apps/oauth.md#obtain-a-token" >}}) - -{{< page-ref page="methods/apps/oauth.md" >}} +{{< page-relref ref="oauth-scopes" caption="OAuth Scopes" >}} +{{< page-relref ref="methods/oauth" caption="oauth methods" >}} +{{< page-ref page="client/token" >}} +{{< page-ref page="client/authorized" >}} \ No newline at end of file diff --git a/content/en/entities/V1_Filter.md b/content/en/entities/V1_Filter.md new file mode 100644 index 00000000..000c444f --- /dev/null +++ b/content/en/entities/V1_Filter.md @@ -0,0 +1,92 @@ +--- +title: V1::Filter +description: Represents a user-defined filter for determining which statuses should not be shown to the user. Contains a single keyword or phrase. +menu: + docs: + parent: entities +aliases: [ + "/entities/v1_filter/", + "/entities/V1_Filter", + "/api/entities/v1_filter/", + "/api/entities/V1_Filter", +] +--- + +## Example + +```json +{ + "id": "8449", + "phrase": "test", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": "2019-11-26T09:08:06.254Z", + "irreversible": true +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the filter in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +2.4.3 - added + +### `phrase` {#phrase} + +**Description:** The text to be filtered.\ +**Type:** String\ +**Version history:**\ +2.4.3 - added + +### `context` {#context} + +**Description:** The contexts in which the filter should be applied.\ +**Type:** Array of String (Enumerable anyOf)\ +`home` = home timeline and lists\ +`notifications` = notifications timeline\ +`public` = public timelines\ +`thread` = expanded thread of a detailed status\ +`account` = when viewing a profile\ +**Version history:**\ +2.4.3 - added\ +3.1.0 - added `account` + +### `expires_at` {#expires_at} + +**Description:** When the filter should no longer be applied.\ +**Type:** {{}} String (ISO 8601 Datetime), or null if the filter does not expire\ +**Version history:**\ +2.4.3 - added + +### `irreversible` {#irreversible} + +**Description:** Should matching entities in home and notifications be dropped by the server? See [implementation guidelines for filters]({{< relref "api/guidelines#filters" >}}).\ +**Type:** Boolean\ +**Version history:**\ +2.4.3 - added + +### `whole_word` {#whole_word} + +**Description:** Should the filter consider word boundaries? See [implementation guidelines for filters]({{< relref "api/guidelines#filters" >}}).\ +**Type:** Boolean\ +**Version history:**\ +2.4.3 - added + +## See also + +{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}} + +{{< page-relref ref="methods/filters#v1" caption="v1 filters API" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/filter_serializer.rb" caption="app/serializers/rest/v1/filter_serializer.rb" >}} + + + diff --git a/content/en/entities/V1_Instance.md b/content/en/entities/V1_Instance.md new file mode 100644 index 00000000..276afc85 --- /dev/null +++ b/content/en/entities/V1_Instance.md @@ -0,0 +1,422 @@ +--- +title: V1::Instance +description: Represents the software instance of Mastodon running on this domain. +menu: + docs: + parent: entities +aliases: [ + "/entities/v1_instance", + "/entities/V1_Instance", + "/api/entities/v1_instance", + "/api/entities/V1_Instance", +] +--- + +## Example + +```json +{ + "uri":"mastodon.social", + "title":"Mastodon", + "short_description":"The original server operated by the Mastodon gGmbH non-profit", + "description":"", + "email":"staff@mastodon.social", + "version":"3.5.3", + "urls":{ + "streaming_api":"wss://mastodon.social" + }, + "stats":{ + "user_count":812303, + "status_count":38151616, + "domain_count":25255 + }, + "thumbnail":"https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png", + "languages":[ + "en" + ], + "registrations":false, + "approval_required":false, + "invites_enabled":true, + "configuration":{ + "statuses":{ + "max_characters":500, + "max_media_attachments":4, + "characters_reserved_per_url":23 + }, + "media_attachments":{ + "supported_mime_types":[ + "image/jpeg", + "image/png", + "image/gif", + "image/webp", + "video/webm", + "video/mp4", + "video/quicktime", + "video/ogg", + "audio/wave", + "audio/wav", + "audio/x-wav", + "audio/x-pn-wave", + "audio/vnd.wave", + "audio/ogg", + "audio/vorbis", + "audio/mpeg", + "audio/mp3", + "audio/webm", + "audio/flac", + "audio/aac", + "audio/m4a", + "audio/x-m4a", + "audio/mp4", + "audio/3gpp", + "video/x-ms-asf" + ], + "image_size_limit":10485760, + "image_matrix_limit":16777216, + "video_size_limit":41943040, + "video_frame_rate_limit":60, + "video_matrix_limit":2304000 + }, + "polls":{ + "max_options":4, + "max_characters_per_option":50, + "min_expiration":300, + "max_expiration":2629746 + } + }, + "contact_account":{ + "id":"1", + "username":"Gargron", + "acct":"Gargron", + "display_name":"Eugen", + "locked":false, + "bot":false, + "discoverable":true, + "group":false, + "created_at":"2016-03-16T00:00:00.000Z", + "note":"\u003cp\u003eFounder, CEO and lead developer \u003cspan class=\"h-card\"\u003e\u003ca href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\"\u003e@\u003cspan\u003eMastodon\u003c/span\u003e\u003c/a\u003e\u003c/span\u003e, Germany.\u003c/p\u003e", + "url":"https://mastodon.social/@Gargron", + "avatar":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count":118944, + "following_count":305, + "statuses_count":72309, + "last_status_at":"2022-08-24", + "emojis":[ + + ], + "fields":[ + { + "name":"Patreon", + "value":"\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e", + "verified_at":null + } + ] + }, + "rules":[ + { + "id":"1", + "text":"Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id":"2", + "text":"No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id":"3", + "text":"No incitement of violence or promotion of violent ideologies" + }, + { + "id":"4", + "text":"No harassment, dogpiling or doxxing of other users" + }, + { + "id":"5", + "text":"No content illegal in Germany" + }, + { + "id":"7", + "text":"Do not share intentionally false or misleading information" + } + ] +} +``` + +## Attributes + +### `uri` {#uri} + +**Description:** The domain name of the instance.\ +**Type:** String\ +**Version history:**\ +1.1.0 - added + +### `title` {#title} + +**Description:** The title of the website.\ +**Type:** String\ +**Version history:**\ +1.1.0 - added + +### `short_description` {#short_description} + +**Description:** A short, plain-text description defined by the admin.\ +**Type:** String\ +**Version history:**\ +2.9.2 - added + +### `description` {#description} + +**Description:** An HTML-permitted description of the Mastodon site.\ +**Type:** String\ +**Version history:**\ +1.1.0 - added + +### `email` {#email} + +**Description:** An email that may be contacted for any inquiries.\ +**Type:** String\ +**Version history:**\ +1.1.0 - added + +### `version` {#version} + +**Description:** The version of Mastodon installed on the instance.\ +**Type:** String\ +**Version history:**\ +1.3.0 - added + +### `urls` {#urls} + +**Description:** URLs of interest for clients apps.\ +**Type:** Hash\ +**Version history:**\ +1.4.2 - added + +#### `urls[streaming_api]` {#streaming_api} + +**Description:** The Websockets URL for connecting to the streaming API.\ +**Type:** String (URL)\ +**Version history:**\ +1.4.2 - added + +### `stats` {#stats} + +**Description:** Statistics about how much information the instance contains.\ +**Type:** Hash\ +**Version history:**\ +1.6.0 - added + +#### `stats[user_count]` {#user_count} + +**Description:** Total users on this instance.\ +**Type:** Integer\ +**Version history:**\ +1.6.0 - added + +#### `stats[status_count]` {#status_count} + +**Description:** Total statuses on this instance.\ +**Type:** Integer\ +**Version history:**\ +1.6.0 - added + +#### `stats[domain_count]` {#domain_count} + +**Description:** Total domains discovered by this instance.\ +**Type:** Integer\ +**Version history:**\ +1.6.0 - added + +### `thumbnail` {#thumbnail} + +**Description:** Banner image for the website.\ +**Type:** {{}} String (URL)\ +**Version history:**\ +1.6.1 - added + +### `languages` {#languages} + +**Description:** Primary languages of the website and its staff.\ +**Type:** Array of String (ISO 639-1 two-letter code)\ +**Version history:**\ +2.3.0 - added + +### `registrations` {#registrations} + +**Description:** Whether registrations are enabled.\ +**Type:** Boolean\ +**Version history:**\ +2.7.2 - added + +### `approval_required` {#approval_required} + +**Description:** Whether registrations require moderator approval.\ +**Type:** Boolean\ +**Version history:**\ +2.9.2 - added + +### `invites_enabled` {#invites_enabled} + +**Description:** Whether invites are enabled.\ +**Type:** Boolean\ +**Version history:**\ +3.1.4 - added + +### `configuration` {#configuration} + +**Description:** Configured values and limits for this website.\ +**Type:** Hash\ +**Version history:**\ +3.4.2 - added + +#### `configuration[accounts]` {#accounts} + +**Description:** Limits related to accounts.\ +**Type:** Hash\ +**Version history:**\ +4.0.0 - added + +##### `configuration[accounts][max_featured_tags]` {#max_featured_tags} + +**Description:** The maximum number of featured tags allowed for each account.\ +**Type:** Integer\ +**Version history:**\ +4.0.0 - added + +#### `configuration[statuses]` {#statuses} + +**Description:** Limits related to authoring statuses.\ +**Type:** Hash\ +**Version history:**\ +3.4.2 - added + +##### `configuration[statuses][max_characters]` {#max_characters} + +**Description:** The maximum number of allowed characters per status.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[statuses][max_media_attachments]` {#max_media_attachments} + +**Description:** The maximum number of media attachments that can be added to a status.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[statuses][characters_reserved_per_url]` {#characters_reserved_per_url} + +**Description:** Each URL in a status will be assumed to be exactly this many characters.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +#### `configuration[media_attachments]` {#media_attachments} + +**Description:** Hints for which attachments will be accepted.\ +**Type:** Hash\ +**Version history:**\ +3.4.2 - added + +##### `configuration[media_attachments][supported_mime_types]` {#supported_mime_types} + +**Description:** Contains MIME types that can be uploaded.\ +**Type:** Array of String\ +**Version history:**\ +3.4.2 - added + +##### `configuration[media_attachments][image_size_limit]` {#image_size_limit} + +**Description:** The maximum size of any uploaded image, in bytes.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[media_attachments][image_matrix_limit]` {#image_matrix_limit} + +**Description:** The maximum number of pixels (width times height) for image uploads.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[media_attachments][video_size_limit]` {#video_size_limit} + +**Description:** The maximum size of any uploaded video, in bytes.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[media_attachments][video_frame_rate_limit]` {#video_frame_rate_limit} + +**Description:** The maximum frame rate for any uploaded video.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[media_attachments][video_matrix_limit]` {#video_matrix_limit} + +**Description:** The maximum number of pixels (width times height) for video uploads.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +#### `configuration[polls]` {#polls} + +**Description:** Limits related to polls.\ +**Type:** Hash\ +**Version history:**\ +3.4.2 - added + +##### `configuration[polls][max_options]` {#max_options} + +**Description:** Each poll is allowed to have up to this many options.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[polls][max_characters_per_option]` {#max_characters_per_option} + +**Description:** Each poll option is allowed to have this many characters.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[polls][min_expiration]` {#min_expiration} + +**Description:** The shortest allowed poll duration, in seconds.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +##### `configuration[polls][max_expiration]` {#max_expiration} + +**Description:** The longest allowed poll duration, in seconds.\ +**Type:** Integer\ +**Version history:**\ +3.4.2 - added + +### `contact_account` {#contact_account} + +**Description:** A user that can be contacted, as an alternative to `email`.\ +**Type:** [Account]({{< relref "entities/Account" >}})\ +**Version history:**\ +2.3.0 - added + +### `rules` {#rules} + +**Description:** An itemized list of rules for this website.\ +**Type:** Array of [Rule]({{< relref "entities/Rule" >}})\ +**Version history:**\ +3.4.0 - added + +## See also + +{{< page-relref ref="methods/instance#v1" caption="GET /api/v1/instance" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/instance_serializer.rb" caption="app/serializers/rest/v1/instance_serializer.rb" >}} + + + diff --git a/content/en/entities/WebPushSubscription.md b/content/en/entities/WebPushSubscription.md new file mode 100644 index 00000000..f639c726 --- /dev/null +++ b/content/en/entities/WebPushSubscription.md @@ -0,0 +1,148 @@ +--- +title: WebPushSubscription +description: Represents a subscription to the push streaming server. +menu: + docs: + parent: entities +aliases: [ + "/entities/pushsubscription", + "/entities/PushSubscription", + "/entities/webpushsubscription", + "/entities/WebPushSubscription", + "/api/entities/pushsubscription", + "/api/entities/PushSubscription", + "/api/entities/webpushsubscription", + "/api/entities/WebPushSubscription", +] +--- + +## Example + +```json +{ + "id": 328183, + "endpoint": "https://yourdomain.example/listener", + "alerts": { + "follow": false, + "favourite": false, + "reblog": false, + "mention": true, + "poll": false + }, + "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +## Attributes + +### `id` {#id} + +**Description:** The ID of the Web Push subscription in the database.\ +**Type:** String (cast from an integer, but not guaranteed to be a number)\ +**Version history:**\ +2.4.0 - added + +### `endpoint` {#endpoint} + +**Description:** Where push alerts will be sent to.\ +**Type:** String (URL)\ +**Version history:**\ +2.4.0 - added + +### `server_key` {#server_key} + +**Description:** The streaming server's VAPID key.\ +**Type:** String\ +**Version history:**\ +2.4.0 - added + +### `alerts` {#alerts} + +**Description:** Which alerts should be delivered to the `endpoint`.\ +**Type:** Hash\ +**Version history:**\ +2.4.0 - added\ +2.8.0 - added `alerts[poll]`\ +3.1.0 - added `alerts[follow_request]`\ +3.3.0 - added `alerts[status]`\ +3.5.0 - added `alerts[update]` and `alerts[admin.sign_up]`\ +4.0.0 - added `alerts[admin.report]` + +#### `alerts[mention]` {#mention} + +**Description:** Receive a push notification when someone else has mentioned you in a status?\ +**Type:** Boolean\ +**Version history:**\ +2.4.0 - added + +#### `alerts[status]` {#status} + +**Description:** Receive a push notification when a subscribed account posts a status?\ +**Type:** Boolean\ +**Version history:**\ +3.3.0 - added + +#### `alerts[reblog]` {#reblog} + +**Description:** Receive a push notification when a status you created has been boosted by someone else?\ +**Type:** Boolean\ +**Version history:**\ +2.4.0 - added + +#### `alerts[follow]` {#follow} + +**Description:** Receive a push notification when someone has followed you?\ +**Type:** Boolean\ +**Version history:**\ +2.4.0 - added + +#### `alerts[follow_request]` {#follow_request} + +**Description:** Receive a push notification when someone has requested to followed you?\ +**Type:** Boolean\ +**Version history:**\ +3.1.0 - added + +#### `alerts[favourite]` {#favourite} + +**Description:** Receive a push notification when a status you created has been favourited by someone else?\ +**Type:** Boolean\ +**Version history:**\ +2.4.0 - added + +#### `alerts[poll]` {#poll} + +**Description:** Receive a push notification when a poll you voted in or created has ended?\ +**Type:** Boolean\ +**Version history:**\ +2.8.0 - added + +#### `alerts[update]` {#update} + +**Description:** Receive a push notification when a status you interacted with has been edited?\ +**Type:** Boolean\ +**Version history:**\ +3.5.0 - added + +#### `alerts[admin.sign_up]` {#admin-sign_up} + +**Description:** Receive a push notification when a new user has signed up?\ +**Type:** Boolean\ +**Version history:**\ +3.5.0 - added + +#### `alerts[admin.report]` {#admin-report} + +**Description:** Receive a push notification when a new report has been filed?\ +**Type:** Boolean\ +**Version history:**\ +4.0.0 - added + +## See also + +{{< page-relref ref="methods/push" caption="push API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/web_push_subscription_serializer.rb" caption="app/serializers/rest/web_push_subscription_serializer.rb" >}} + + + diff --git a/content/en/entities/account.md b/content/en/entities/account.md deleted file mode 100644 index f6fa0c07..00000000 --- a/content/en/entities/account.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: Account -description: Represents a user of Mastodon and their associated profile. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "id": "23634", - "username": "noiob", - "acct": "noiob@awoo.space", - "display_name": "ikea shark fan account", - "locked": false, - "bot": false, - "created_at": "2017-02-08T02:00:53.274Z", - "note": "

:ms_rainbow_flag:​ :ms_bisexual_flagweb:​ :ms_nonbinary_flag:​ #awoo#admin#bi#nonbinary#games@dzuk

", - "url": "https://awoo.space/@noiob", - "avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png", - "header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png", - "header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png", - "followers_count": 547, - "following_count": 404, - "statuses_count": 28468, - "last_status_at": "2019-11-17T00:02:23.693Z", - "emojis": [ - { - "shortcode": "ms_rainbow_flag", - "url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png", - "visible_in_picker": true - }, - { - "shortcode": "ms_bisexual_flag", - "url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png", - "visible_in_picker": true - }, - { - "shortcode": "ms_nonbinary_flag", - "url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png", - "visible_in_picker": true - } - ], - "fields": [ - { - "name": "Pronouns", - "value": "they/them", - "verified_at": null - }, - { - "name": "Alt", - "value": "@noiob", - "verified_at": null - }, - { - "name": "Bots", - "value": "@darksouls, @nierautomata, @fedi, code for @awoobot", - "verified_at": null - }, - { - "name": "Website", - "value": "http://shork.xyz}})\ -**Version history:**\ -2.4.0 - added - -### `discoverable` {#discoverable} - -**Description:** Whether the account has opted into discovery features such as the profile directory.\ -**Type:** Boolean\ -**Version history:**\ -3.1.0 - added - -## Statistical attributes - -### `created_at` {#created_at} - -**Description:** When the account was created.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -0.1.0 - added - -### `last_status_at` {#last_status_at} - -**Description:** When the most recent status was posted.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -3.0.0 - added\ -3.1.0 - now returns date only, no time - - -### `statuses_count` {#statuses_count} - -**Description:** How many statuses are attached to this account.\ -**Type:** Number\ -**Version history:**\ -0.1.0 - added - -### `followers_count` {#followers_count} - -**Description:** The reported followers of this profile.\ -**Type:** Number\ -**Version history:**\ -0.1.0 - added - -### `following_count` {#following_count} - -**Description:** The reported follows of this profile.\ -**Type:** Number\ -**Version history:**\ -0.1.0 - added - -## Optional attributes - -### `moved` {#moved} - -**Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\ -**Type:** [Account]({{< relref "account.md" >}})\ -**Version history:**\ -2.1.0 - added - -### `fields` {#fields} - -**Description:** Additional metadata attached to a profile as name-value pairs.\ -**Type:** Array of [Field]({{< relref "field.md" >}})\ -**Version history:**\ -2.4.0 - added - -### `bot` {#bot} - -**Description:** A presentational flag. Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.\ -**Type:** Boolean\ -**Version history:**\ -2.4.0 - added - -### `source` {#source} - -**Description:** An extra entity to be used with API methods to [verify credentials]({{< relref "../methods/accounts/#verify-account-credentials" >}}) and [update credentials]({{< relref "../methods/accounts/#update-account-credentials" >}}).\ -**Type:** [Source]({{< relref "source.md" >}})\ -**Version history:**\ -2.4.0 - added - -### `suspended` {#suspended} - -**Description:** An extra entity returned when an account is suspended.\ -**Type:** Boolean\ -**Version history:**\ -3.3.0 - added - -### `mute_expires_at` {#mute_expires_at} - -**Description:** When a timed mute will expire, if applicable.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -3.3.0 - added - -## See also - -{{< page-ref page="methods/accounts.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/account_serializer.rb" caption="app/serializers/rest/account\_serializer.rb" >}} - - - - - diff --git a/content/en/entities/activity.md b/content/en/entities/activity.md deleted file mode 100644 index e2ebaacf..00000000 --- a/content/en/entities/activity.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Activity -description: Represents a weekly bucket of instance activity. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "week": "1574640000", - "statuses": "37125", - "logins": "14239", - "registrations": "542" -} -``` - -## Attributes - -### `week` {#week} - -**Description:** Midnight at the first day of the week.\ -**Type:** String \(UNIX Timestamp\)\ -**Version history:** Added in 2.1.2 - -### `statuses` {#statuses} - -**Description:** Statuses created since the week began.\ -**Type:** String \(cast from an integer\)\ -**Version history:** Added in 2.1.2 - -### `logins` {#logins} - -**Description:** User logins since the week began.\ -**Type:** String \(cast from an integer\)\ -**Version history:** Added in 2.1.2 - -### `registrations` {#registrations} - -**Description:** User registrations since the week began.\ -**Type:** String \(cast from an integer\)\ -**Version history:** Added in 2.1.2 - -## See also - -* [GET /api/v1/instance/activity]({{< relref "../methods/instance/#weekly-activity" >}}) - -{{< page-ref page="methods/instance.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/controllers/api/v1/instances/activity_controller.rb" caption="app/controllers/api/v1/instances/activity\_controller.rb" >}} - - - diff --git a/content/en/entities/admin-account.md b/content/en/entities/admin-account.md deleted file mode 100644 index b145f13f..00000000 --- a/content/en/entities/admin-account.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Admin::Account -description: Admin-level information about a given account. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{} -``` - -## Attributes - -### `id` {#id} - -**Description:** The ID of the account in the database.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 2.9.1 - -### `username` {#username} - -**Description:** The username of the account.\ -**Type:** String\ -**Version history:** Added in 2.9.1 - -### `domain` {#domain} - -**Description:** The domain of the account.\ -**Type:** String\ -**Version history:** Added in 2.9.1 - -### `created_at` {#created_at} - -**Description:** When the account was first discovered.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:** Added in 2.9.1 - -### `email` {#email} - -**Description:** The email address associated with the account.\ -**Type:** String\ -**Version history:** Added in 2.9.1 - -### `ip` {#ip} - -**Description:** The IP address last used to login to this account.\ -**Type:** String\ -**Version history:** Added in 2.9.1 - -### `locale` {#locale} - -**Description:** The locale of the account.\ -**Type:** String \(ISO 639 Part 1 two-letter language code\)\ -**Version history:** Added in 2.9.1 - -### `invite_request` {#invite_request} - -**Description:** Invite request text ???\ -**Type:** String\ -**Version history:** Added in 2.9.1 - -## State attributes - -### `role` {#role} - -**Description:** The current role of the account.\ -**Type:** String \(Enumerable oneOf\)\ -**Version history:** Added in 2.9.1 - -### `confirmed` {#confirmed} - -**Description:** Whether the account has confirmed their email address.\ -**Type:** Boolean\ -**Version history:** Added in 2.9.1 - -### `approved` {#approved} - -**Description:** Whether the account is currently approved.\ -**Type:** Boolean\ -**Version history:** Added in 2.9.1 - -### `disabled` {#disabled} - -**Description:** Whether the account is currently disabled.\ -**Type:** Boolean\ -**Version history:** Added in 2.9.1 - -### `silenced` {#silenced} - -**Description:** Whether the account is currently silenced. -**Type:** Boolean\ -**Version history:** Added in 2.9.1 - -### `suspended` {#suspended} - -**Description:** Whether the account is currently suspended.\ -**Type:** Boolean\ -**Version history:** Added in 2.9.1 - -### `account` {#account} - -**Description:** User-level information about the account.\ -**Type:** Account\ -**Version history:** Added in 2.9.1 - -## Nullable attributes - -### `created_by_application_id` {#created_by_application_id} - -**Description:** The ID of the application that created this account.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 2.9.1 - -### `invited_by_account_id` {#invited_by_account_id} - -**Description:** The ID of the account that invited this user\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 2.9.1 - -## See also - -{{< page-ref page="methods/admin.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/admin/account_serializer.rb" caption="app/serializers/rest/admin/account\_serializer.rb" >}} - - - diff --git a/content/en/entities/admin-report.md b/content/en/entities/admin-report.md deleted file mode 100644 index 4b9f3e56..00000000 --- a/content/en/entities/admin-report.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Admin::Report -description: Admin-level information about a filed report. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{} -``` - -## Attributes - -### `id` {#id} - -**Description:** The ID of the report in the database.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 2.9.1 - -### `action_taken` {#action_taken} - -**Description:** The action taken to resolve this report.\ -**Type:** String \(Enumerable oneOf\)\ -**Version history:** Added in 2.9.1 - -### `comment` {#comment} - -**Description:** An optional reason for reporting.\ -**Type:** String\ -**Version history:** Added in 2.9.1 - -### `created_at` {#created_at} - -**Description:** The time the report was filed.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:** Added in 2.9.1 - -### `updated_at` {#updated_at} - -**Description:** The time of last action on this report.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:** Added in 2.9.1 - -### `account` {#account} - -**Description:** The account which filed the report.\ -**Type:** [Account]({{< relref "account.md" >}})\ -**Version history:** Added in 2.9.1 - -### `target_account` {#target_account} - -**Description:** The account being reported.\ -**Type:** [Account]({{< relref "account.md" >}})\ -**Version history:** Added in 2.9.1 - -### `assigned_account` {#assigned_account} - -**Description:** The account of the moderator assigned to this report.\ -**Type:** [Account]({{< relref "account.md" >}})\ -**Version history:** Added in 2.9.1 - -### `action_taken_by_account` {#action_taken_by_account} - -**Description:** The action taken by the moderator who handled the report.\ -**Type:** String \(Enumerable oneOf\)\ -**Version history:** Added in 2.9.1 - -### `statuses` {#statuses} - -**Description:** Statuses attached to the report, for context.\ -**Type:** Array of [Status]({{< relref "status.md" >}})\ -**Version history:** Added in 2.9.1 - -## See also - -{{< page-ref page="methods/admin.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/admin/report_serializer.rb" caption="app/serializers/rest/admin/report\_serializer.rb" >}} - - - diff --git a/content/en/entities/announcement.md b/content/en/entities/announcement.md deleted file mode 100644 index 9a1e0147..00000000 --- a/content/en/entities/announcement.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Announcement -description: Represents an announcement set by an administrator. -menu: - docs: - parent: entities ---- - -## Example -```javascript -{ - "id": "8", - "content": "

Looks like there was an issue processing audio attachments without embedded art since yesterday due to an experimental new feature. That issue has now been fixed, so you may see older posts with audio from other servers pop up in your feeds now as they are being finally properly processed. Sorry!

", - "starts_at": null, - "ends_at": null, - "all_day": false, - "published_at": "2020-07-03T01:27:38.726Z", - "updated_at": "2020-07-03T01:27:38.752Z", - "read": true, - "mentions": [], - "statuses": [], - "tags": [], - "emojis": [], - "reactions": [ - { - "name": "bongoCat", - "count": 9, - "me": false, - "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png" - }, - { - "name": "thonking", - "count": 1, - "me": false, - "url": "https://files.mastodon.social/custom_emojis/images/000/098/690/original/a8d36edc4a7032e8.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/098/690/static/a8d36edc4a7032e8.png" - }, - { - "name": "AAAAAA", - "count": 1, - "me": false, - "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png" - }, - { - "name": "🤔", - "count": 1, - "me": true - } - ] -} -``` - -## Base attributes - -### `id` - -**Description:** The announcement id.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:**\ -3.1.0 - added - -### `text` - -**Description:** The content of the announcement.\ -**Type:** String\ -**Version history:**\ -3.1.0 - added - -### `published` - -**Description:** Whether the announcement is currently active.\ -**Type:** Boolean\ -**Version history:**\ -3.1.0 - added - -### `all_day` {#all_day} - -**Description:** Whether the announcement has a start/end time.\ -**Type:** Boolean\ -**Version history:**\ -3.1.0 - added - -### `created_at` {#created_at} - -**Description:** When the announcement was created.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -3.1.0 - added - -### `updated_at` {#updated_at} - -**Description:** When the announcement was last updated.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -3.1.0 - added - -### `read` - -**Description:** Whether the announcement has been read by the user.\ -**Type:** Boolean\ -**Version history:**\ -3.1.0 - added - -### `reactions` - -**Description:** Emoji reactions attached to the announcement.\ -**Type:** Array of AnnouncementReaction\ -**Version history:**\ -3.1.0 - added - - -## Optional attributes - -### `scheduled_at` {#scheduled_at} - -**Description:** When the future announcement was scheduled.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -3.1.0 - added - -### `starts_at` {#starts_at} - -**Description:** When the future announcement will start.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -3.1.0 - added - -### `ends_at` {#ends_at} - -**Description:** When the future announcement will end.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:**\ -3.1.0 - added \ No newline at end of file diff --git a/content/en/entities/announcementReaction.md b/content/en/entities/announcementReaction.md deleted file mode 100644 index 585078d3..00000000 --- a/content/en/entities/announcementReaction.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: AnnouncementReaction -description: Represents an emoji reaction to an Announcement. -menu: - docs: - parent: entities ---- - -## Example -```javascript -{ - "name": "bongoCat", - "count": 9, - "me": false, - "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png" -}, -{ - "name": "🤔", - "count": 1, - "me": true -} -``` - -## Base attributes - -### `name` - -**Description:** The emoji used for the reaction. Either a unicode emoji, or a custom emoji's shortcode.\ -**Type:** String\ -**Version history:**\ -3.1.0 - added - -### `count` - -**Description:** The total number of users who have added this reaction.\ -**Type:** Number\ -**Version history:**\ -3.1.0 - added - -### `me` - -**Description:** Whether the authorized user has added this reaction to the announcement.\ -**Type:** Boolean\ -**Version history:**\ -3.1.0 - added - -## Custom emoji attributes - -### `url` - -**Description:** A link to the custom emoji.\ -**Type:** String \(URL\)\ -**Version history:**\ -3.1.0 - added - -### `static_url` {#static_url} - -**Description:** A link to a non-animated version of the custom emoji.\ -**Type:** String \(URL\)\ -**Version history:**\ -3.1.0 - added \ No newline at end of file diff --git a/content/en/entities/application.md b/content/en/entities/application.md deleted file mode 100644 index 3223fe3b..00000000 --- a/content/en/entities/application.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Application -description: Represents an application that interfaces with the REST API to access accounts or post statuses. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "name": "test app", - "website": null, - "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" -} -``` - -## Required attributes - -### `name` {#name} - -**Description:** The name of your application.\ -**Type:** String\ -**Version history:** Added in 0.9.9 - -## Optional attributes - -### `website` {#website} - -**Description:** The website associated with your application.\ -**Type:** String \(URL\)\ -**Version history:** Added in 0.9.9 - -### `vapid_key` {#vapid_key} - -**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps]({{< relref "../methods/apps/#create-an-application" >}}). Equivalent to [PushSubscription\#server\_key]({{< relref "pushsubscription.md#server_key" >}})\ -**Type:** String\ -**Version history:** Added in 2.8.0 - -## Client attributes - -### `client_id` {#client_id} - -**Description:** Client ID key, to be used for obtaining OAuth tokens\ -**Type:** String\ -**Version history:** Added in 0.9.9 - -### `client_secret` {#client_secret} - -**Description:** Client secret key, to be used for obtaining OAuth tokens\ -**Type:** String\ -**Version history:** Added in 0.9.9 - -## See also - -* [Status\#application]({{< relref "status.md#application" >}}) -* [Create an application \(POST /api/v1/apps\)]({{< relref "../methods/apps/#create-an-application" >}}) - -{{< page-ref page="status.md" >}} - -{{< page-ref page="methods/apps.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/application_serializer.rb" caption="app/serializers/rest/application\_serializer.rb" >}} - - - diff --git a/content/en/entities/conversation.md b/content/en/entities/conversation.md deleted file mode 100644 index cf5b9b07..00000000 --- a/content/en/entities/conversation.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Conversation -description: Represents a conversation with "direct message" visibility. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "id": "418450", - "unread": true, - "accounts": [ - { - "id": "482403", - "username": "amic", - "acct": "amic@nulled.red", - ... - } - ], - "last_status": { - "id": "103196583826321184", - "created_at": "2019-11-25T04:08:24.000Z", - "in_reply_to_id": "103196540587943467", - "in_reply_to_account_id": "14715", - ... - } -} -``` - -## Required attributes - -### `id` {#id} - -**Description:** Local database ID of the conversation.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 2.6.0 - -### `accounts` {#accounts} - -**Description:** Participants in the conversation.\ -**Type:** Array of [Account]({{< relref "account.md" >}})\ -**Version history:** Added in 2.6.0 - -### `unread` {#unread} - -**Description:** Is the conversation currently marked as unread?\ -**Type:** Boolean\ -**Version history:** Added in 2.6.0 - -## Optional attributes - -### `last_status` {#last_status} - -**Description:** The last status in the conversation, to be used for optional display.\ -**Type:** [Status]({{< relref "status.md" >}})\ -**Version history:** Added in 2.6.0 - -## See also - -{{< page-ref page="methods/timelines/conversations.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/conversation_serializer.rb" caption="app/serializers/rest/conversation\_serializer.rb" >}} - - - - - diff --git a/content/en/entities/emoji.md b/content/en/entities/emoji.md deleted file mode 100644 index dd37a45a..00000000 --- a/content/en/entities/emoji.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Emoji -description: Represents a custom emoji. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "shortcode": "blobaww", - "url": "https://files.mastodon.social/custom_emojis/images/000/011/739/original/blobaww.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/011/739/static/blobaww.png", - "visible_in_picker": true, - "category": "Blobs" -} -``` - -## Required attributes - -### `shortcode` {#shortcode} - -**Description:** The name of the custom emoji.\ -**Type:** String\ -**Version history:** Added in 2.0.0 - -### `url` {#url} - -**Description:** A link to the custom emoji.\ -**Type:** String \(URL\)\ -**Version history:** Added in 2.0.0 - -### `static_url` {#static_url} - -**Description:** A link to a static copy of the custom emoji.\ -**Type:** String \(URL\)\ -**Version history:** Added in 2.0.0 - -### `visible_in_picker` {#visible_in_picker} - -**Description:** Whether this Emoji should be visible in the picker or unlisted.\ -**Type:** Boolean\ -**Version history:** Added in 2.0.0 - -## Optional attributes - -### `category` {#category} - -**Description:** Used for sorting custom emoji in the picker.\ -**Type:** String\ -**Version history:** Added in 3.0.0 - -## See also - -* [Status\#emojis]({{< relref "status.md#emojis" >}}) - -{{< page-ref page="status.md" >}} - -{{< page-ref page="methods/instance/custom_emojis.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/custom_emoji_serializer.rb" caption="app/serializers/rest/custom\_emoji\_serializer.rb" >}} - - - - - diff --git a/content/en/entities/error.md b/content/en/entities/error.md deleted file mode 100644 index ef3ea515..00000000 --- a/content/en/entities/error.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Error -description: Represents an error message. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "error": "invalid_grant", - "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." -} -``` - -{{< hint style="info" >}} -**The most important part of an error response is the HTTP status code.** Standard semantics are followed. The body of an error is a JSON object containing more information, if available. -{{< /hint >}} - -## Required attributes - -### `error` {#error} - -**Description:** The error message.\ -**Type:** String\ -**Version history:** Added in 0.6.0 - -## Optional attributes - -### `error_description` {#error_description} - -**Description:** A longer description of the error, mainly provided with the OAuth API.\ -**Type:** String\ -**Version history:** Added in 0.6.0 - -## Possible reasons {#reasons} - -### 401 - Unauthorized {#401} - -#### require\_authenticated\_user! {#auth} - -Error: This API requires an authenticated user. Appears when the instance is in secure mode, which disables all public use of API methods. - -### 403 - Forbidden {#403} - -#### current\_user.disabled? {#disabled} - -Error: Your login is currently disabled. Appears when the OAuth token's authorized user has had their account disabled by a moderator. - -#### !current\_user.confirmed? {#unconfirmed} - -Error: Your login is missing a confirmed e-mail address. Appears when the email address associated with the OAuth token's authorized user's account has not yet been confirmed. - -#### !current\_user.approved? {#unapproved} - -Error: Your login is currently pending approval. Appears when the OAuth token's authorized user has signed up on an instance with approval-required registrations, and the user has not yet had their account approved by a moderator. - -### 404 - Not Found {#404} - -#### RecordNotFound {#not-found} - -Error: Record not found. Appears when an entity record does not exist, or the authorized user is not within the audience of a private entity.operates on a user. - -### 422 - Unprocessable Entity {#422} - -#### RecordInvalid {#invalid} - -Error: {string}. May appear when entity creation failed. - -#### RecordNotUnique {#not-unique} - -Error: Duplicate record. Appears when you are trying to pin an account or status that is already pinned. - -#### !current\_user {#user-required} - -Error: This method requires an authenticated user. Appears when using an OAuth token without an authorized user \(or no token at all\), while trying to call an API method that requires a user to be processed. - -## See also - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/controllers/api/base_controller.rb" caption="app/controllers/api/base\_controller.rb" >}} - - - - - diff --git a/content/en/entities/featuredtag.md b/content/en/entities/featuredtag.md deleted file mode 100644 index 4f9d378f..00000000 --- a/content/en/entities/featuredtag.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: FeaturedTag -description: Represents a hashtag that is featured on a profile. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "id": "627", - "name": "nowplaying", - "statuses_count": 36, - "last_status_at": "2019-11-15T07:14:43.524Z" -} -``` - -## Attributes - -### `id` {#id} - -**Description:** The internal ID of the featured tag in the database.\ -**Type:** String \(cast from integer but not guaranteed to be a number\)\ -**Version history:** Added in 3.0.0 - -### `name` {#name} - -**Description:** The name of the hashtag being featured.\ -**Type:** String\ -**Version history:** Added in 3.0.0 - -### `url` {#url} - -**Description:** A link to all statuses by a user that contain this hashtag.\ -**Type:** String (URL)\ -**Version history:** Added in 3.3.0 - -### `statuses_count` {#statuses_count} - -**Description:** The number of authored statuses containing this hashtag.\ -**Type:** Number\ -**Version history:** Added in 3.0.0 - -### `last_status_at` {#last_status_at} - -**Description:** The timestamp of the last authored status containing this hashtag.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:** Added in 3.0.0 - -## See also - -{{< page-ref page="methods/accounts/featured_tags.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/featured_tag_serializer.rb" caption="app/serializers/rest/featured\_tag\_serializer.rb" >}} - - - - - diff --git a/content/en/entities/field.md b/content/en/entities/field.md deleted file mode 100644 index 0e2b050a..00000000 --- a/content/en/entities/field.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Field -description: Represents a profile field as a name-value pair with optional verification. -menu: - docs: - parent: entities ---- - -## Example - -{{< code title="Excerpt from Account\[source\]" >}} -```javascript - "fields": [ - { - "name": "Website", - "value": "https://trwnh.com", - "verified_at": "2019-08-29T04:14:55.571+00:00" - }, - { - "name": "Sponsor", - "value": "https://liberapay.com/at", - "verified_at": "2019-11-15T10:06:15.557+00:00" - }, - { - "name": "Fan of:", - "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)", - "verified_at": null - }, - { - "name": "Main topics:", - "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!", - "verified_at": null - } - ], -``` -{{< /code >}} - -## Required attributes - -### `name` {#name} - -**Description:** The key of a given field's key-value pair.\ -**Type:** String\ -**Version history:** Added in 2.4.0 - -### `value` {#value} - -**Description:** The value associated with the `name` key.\ -**Type:** String \(HTML\)\ -**Version history:** Added in 2.4.0 - -## Optional attributes - -### `verified_at` {#verified_at} - -**Description:** Timestamp of when the server verified a URL value for a rel="me" link.\ -**Type:** String \(ISO 8601 Datetime\) if `value` is a verified URL. Otherwise, null\ -**Version history:** Added in 2.6.0 - -## See also - -* [Account\#fields]({{< relref "account.md#fields" >}}) -* [Source\#fields]({{< relref "source.md#fields" >}}) - -{{< page-ref page="account.md" >}} - -{{< page-ref page="source.md" >}} - - - diff --git a/content/en/entities/filter.md b/content/en/entities/filter.md deleted file mode 100644 index 1815a315..00000000 --- a/content/en/entities/filter.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Filter -description: Represents a user-defined filter for determining which statuses should not be shown to the user. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "id": "8449", - "phrase": "test", - "context": [ - "home", - "notifications", - "public", - "thread" - ], - "whole_word": false, - "expires_at": "2019-11-26T09:08:06.254Z", - "irreversible": true -} -``` - -## Attributes - -### `id` {#id} - -**Description:** The ID of the filter in the database.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 2.4.3 - -### `phrase` {#phrase} - -**Description:** The text to be filtered.\ -**Type:** String\ -**Version history:** Added in 2.4.3 - -### `context` {#context} - -**Description:** The contexts in which the filter should be applied.\ -**Type:** Array of String \(Enumerable anyOf\)\ -`home` = home timeline and lists\ -`notifications` = notifications timeline\ -`public` = public timelines\ -`thread` = expanded thread of a detailed status\ -**Version history:** Added in 2.4.3 - -### `expires_at` {#expires_at} - -**Description:** When the filter should no longer be applied\ -**Type:** String \(ISO 8601 Datetime\), or null if the filter does not expire\ -**Version history:** Added in 2.4.3 - -### `irreversible` {#irreversible} - -**Description:** Should matching entities in home and notifications be dropped by the server?\ -**Type:** Boolean\ -**Version history:** Added in 2.4.3 - -### `whole_word` {#whole_word} - -**Description:** Should the filter consider word boundaries?\ -**Type:** Boolean\ -**Version history:** Added in 2.4.3 - -## Implementation notes - -If `whole_word` is true , client app should do: - -* Define ‘word constituent character’ for your app. In the official implementation, it’s `[A-Za-z0-9_]` in JavaScript, and `[[:word:]]` in Ruby. Ruby uses the POSIX character class \(Letter \| Mark \| Decimal\_Number \| Connector\_Punctuation\). -* If the phrase starts with a word character, and if the previous character before matched range is a word character, its matched range should be treated to not match. -* If the phrase ends with a word character, and if the next character after matched range is a word character, its matched range should be treated to not match. - -Please check `app/javascript/mastodon/selectors/index.js` and `app/lib/feed_manager.rb` in the Mastodon source code for more details. - -## See also - -{{< page-ref page="methods/accounts/filters.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/feed_manager.rb" caption="app/lib/feed\_manager.rb" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/javascript/mastodon/selectors/index.js" caption="app/javascript/mastodon/selectors/index.js" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/filter_serializer.rb" caption="app/serializers/rest/filter\_serializer.rb" >}} - - - diff --git a/content/en/entities/history.md b/content/en/entities/history.md deleted file mode 100644 index 10561d18..00000000 --- a/content/en/entities/history.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: History -description: Represents daily usage history of a hashtag. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "day": "1574553600", - "uses": "200", - "accounts": "31" -} -``` - -## Required attributes - -### `day` {#day} - -**Description:** UNIX timestamp on midnight of the given day.\ -**Type:** String \(UNIX timestamp\)\ -**Version history:** Added in 2.4.1 - -### `uses` {#uses} - -**Description:** the counted usage of the tag within that day.\ -**Type:** String \(cast from an integer\)\ -**Version history:** Added in 2.4.1 - -### `accounts` {#accounts} - -**Description:** the total of accounts using the tag within that day.\ -**Type:** String \(cast from an integer\)\ -**Version history:** Added in 2.4.1 - -## See also - -* [Tag\#history]({{< relref "tag.md#history" >}}) - -{{< page-ref page="tag.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/17159625b3e2c6d94509c0c2879ca80efbac6846/app/models/tag.rb\#L101-L115" caption="app/models/tag.rb L101-115 -- history days\[\]" >}} - - - diff --git a/content/en/entities/instance.md b/content/en/entities/instance.md deleted file mode 100644 index 39f4280a..00000000 --- a/content/en/entities/instance.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Instance -description: Represents the software instance of Mastodon running on this domain. -menu: - docs: - parent: entities ---- - -## Example - -```javascript - - "uri": "mastodon.social", - "title": "Mastodon", - "short_description": "Server run by the main developers of the project \"🐘\" It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!", - "description": "Server run by the main developers of the project \"🐘\" It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!", - "email": "staff@mastodon.social", - "version": "3.0.1", - "urls": { - "streaming_api": "wss://mastodon.social" - }, - "stats": { - "user_count": 415526, - "status_count": 17085754, - "domain_count": 11834 - }, - "thumbnail": "https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png", - "languages": [ - "en" - ], - "registrations": true, - "approval_required": false, - "contact_account": { - "id": "1", - "username": "Gargron", - "acct": "Gargron", - "display_name": "Eugen", - "locked": false, - "bot": false, - "created_at": "2016-03-16T14:34:26.392Z", - "note": "

Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.

", - "url": "https://mastodon.social/@Gargron", - "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg", - "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png", - "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png", - "followers_count": 317112, - "following_count": 453, - "statuses_count": 60903, - "last_status_at": "2019-11-26T21:14:44.522Z", - "emojis": [], - "fields": [ - { - "name": "Patreon", - "value": "https://www.patreon.com/mastodonhttps://zeonfederated.com}}) or null\ -**Version history:** Added in 2.3.0 - -## See also - -{{< page-ref page="methods/instance.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/instance_serializer.rb" caption="app/serializers/rest/instance\_serializer.rb" >}} - - - diff --git a/content/en/entities/marker.md b/content/en/entities/marker.md deleted file mode 100644 index 5c239bbb..00000000 --- a/content/en/entities/marker.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Marker -description: Represents the last read position within a user's timelines. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "home": { - "last_read_id": "103194548672408537", - "version": 462, - "updated_at": "2019-11-24T19:39:39.337Z" - }, - "notifications": { - "last_read_id": "35050107", - "version": 356, - "updated_at": "2019-11-25T13:47:31.333Z" - } -} -``` - -## Base attributes - -### `home` {#home} - -**Description:** Information about the user's position in the home timeline.\ -**Type:** Hash\ -**Version history:** Added in 3.0.0 - -### `notifications` {#notifications} - -**Description:** Information about the user's position in their notifications.\ -**Type:** Hash\ -**Version history:** Added in 3.0.0 - -## Nested attributes - -### `last_read_id` {#last_read_id} - -**Description:** The ID of the most recently viewed entity.\ -**Type:** String \(cast from integer but not guaranteed to be a number\)\ -**Version history:** Added in 3.0.0 - -### `updated_at` {#updated_at} - -**Description:** The timestamp of when the marker was set.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:** Added in 3.0.0 - -### `version` {#version} - -**Description:** Used for locking to prevent write conflicts.\ -**Type:** Number\ -**Version history:** Added in 3.0.0 - -## See also - -{{< page-ref page="methods/timelines/markers.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/marker_serializer.rb" caption="app/serializers/rest/marker\_serializer.rb" >}} - - - diff --git a/content/en/entities/mention.md b/content/en/entities/mention.md deleted file mode 100644 index 3f3a51d6..00000000 --- a/content/en/entities/mention.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Mention -description: Represents a mention of a user within the content of a status. -menu: - docs: - parent: entities ---- - -## Example - -{{< code title="excerpt from GET status:" >}} -```javascript -{ - "mentions": [ - { - "id": "952529", - "username": "alayna", - "url": "https://desvox.es/users/alayna", - "acct": "alayna@desvox.es" - }, - { - "id": "14715", - "username": "trwnh", - "url": "https://mastodon.social/@trwnh", - "acct": "trwnh" - } - ] -} -``` -{{< /code >}} - -## Required attributes - -### `id` {#id} - -**Description:** The account id of the mentioned user.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 0.6.0 - -### `username` {#username} - -**Description:** The username of the mentioned user.\ -**Type:** String\ -**Version history:** Added in 0.6.0 - -### `acct` {#acct} - -**Description:** The webfinger acct: URI of the mentioned user. Equivalent to `username` for local users, or `username@domain` for remote users.\ -**Type:** String\ -**Version history:** Added in 0.6.0 - -### `url` {#url} - -**Description:** The location of the mentioned user's profile.\ -**Type:** String \(URL\)\ -**Version history:** Added in 0.6.0 - -## See also - -* [GET /api/v1/statuses/:id]({{< relref "../methods/statuses/#view-specific-status" >}}) -* [Status\#mentions]({{< relref "status.md#mentions" >}}) - -{{< page-ref page="status.md" >}} - - - diff --git a/content/en/entities/poll.md b/content/en/entities/poll.md deleted file mode 100644 index 82470f05..00000000 --- a/content/en/entities/poll.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Poll -description: Represents a poll attached to a status. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "id": "34830", - "expires_at": "2019-12-05T04:05:08.302Z", - "expired": true, - "multiple": false, - "votes_count": 10, - "voters_count": null, - "voted": true, - "own_votes": [ - 1 - ], - "options": [ - { - "title": "accept", - "votes_count": 6 - }, - { - "title": "deny", - "votes_count": 4 - } - ], - "emojis": [] -} -``` - -## Attributes - -### `id` {#id} - -**Description:** The ID of the poll in the database.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 2.8.0 - -### `expires_at` {#expires_at} - -**Description:** When the poll ends.\ -**Type:** String \(ISO 8601 Datetime\), or null if the poll does not end\ -**Version history:** Added in 2.8.0 - -### `expired` {#expired} - -**Description:** Is the poll currently expired?\ -**Type:** Boolean\ -**Version history:** Added in 2.8.0 - -### `multiple` {#multiple} - -**Description:** Does the poll allow multiple-choice answers?\ -**Type:** Boolean\ -**Version history:** Added in 2.8.0 - -### `votes_count` {#votes_count} - -**Description:** How many votes have been received.\ -**Type:** Number\ -**Version history:** Added in 2.8.0 - -### `voters_count` {#voters_count} - -**Description:** How many unique accounts have voted on a multiple-choice poll.\ -**Type:** Number, or null if `multiple` is false.\ -**Version history:** Added in 2.8.0 - -### `voted` {#voted} - -**Description:** When called with a user token, has the authorized user voted?\ -**Type:** Boolean, or null if no current user\ -**Version history:** Added in 2.8.0 - -### `own_votes` {#own_votes} - -**Description:** When called with a user token, which options has the authorized user chosen? Contains an array of index values for `options`.\ -**Type:** Array of Number, or null if no current user\ -**Version history:** Added in 2.8.0 - -### `options[]` {#options} - -**Description:** Possible answers for the poll.\ -**Type:** Array of Hash\ -**Version history:** Added in 2.8.0 - -#### `options[][title]` - -The text value of the poll option. String. - -#### `options[][votes_count]` - -The number of received votes for this option. Number, or null if results are not published yet. - -### `emojis` {#emojis} - -**Description:** Custom emoji to be used for rendering poll options.\ -**Type:** Array of Emoji\ -**Version history:** Added in 2.8.0 - -## See also - -* [Status\#poll]({{< relref "status.md#poll" >}}) -* [/api/v1/polls]({{< relref "../methods/statuses/polls.md" >}}) - -{{< page-ref page="status.md" >}} - -{{< page-ref page="methods/statuses/polls.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/poll_serializer.rb" caption="app/serializers/rest/poll\_serializer.rb" >}} - - - - - diff --git a/content/en/entities/preferences.md b/content/en/entities/preferences.md deleted file mode 100644 index 7623bdb3..00000000 --- a/content/en/entities/preferences.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Preferences -description: Represents a user's preferences. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "posting:default:visibility": "public", - "posting:default:sensitive": false, - "posting:default:language": null, - "reading:expand:media": "default", - "reading:expand:spoilers": false -} -``` - -## Attributes - -### `posting:default:visibility` {#visibility} - -**Description:** Default visibility for new posts. Equivalent to [Source\#privacy]({{< relref "source.md#privacy" >}}).\ -**Type:** String \(Enumerable, oneOf\)\ -`public` = Public post\ -`unlisted` = Unlisted post\ -`private` = Followers-only post\ -`direct` = Direct post\ -**Version history:** Added in 2.8.0 - -### `posting:default:sensitive` {#sensitive} - -**Description:** Default sensitivity flag for new posts. Equivalent to [Source\#sensitive]({{< relref "source.md#sensitive" >}}).\ -**Type:** Boolean\ -**Version history:** Added in 2.8.0 - -### `posting:default:language` {#language} - -**Description:** Default language for new posts. Equivalent to [Source\#language]({{< relref "source.md#language" >}})\ -**Type:** String \(ISO 639-1 language two-letter code\), or null\ -**Version history:** Added in 2.8.0 - -### `reading:expand:media` {#media} - -**Description:** Whether media attachments should be automatically displayed or blurred/hidden.\ -**Type:** String \(Enumerable, oneOf\)\ -`default` = Hide media marked as sensitive\ -`show_all` = Always show all media by default, regardless of sensitivity\ -`hide_all` = Always hide all media by default, regardless of sensitivity\ -**Version history:** Added in 2.8.0 - -### `reading:expand:spoilers` {#cw} - -**Description:** Whether CWs should be expanded by default.\ -**Type:** Boolean\ -**Version history:** Added in 2.8.0 - -## See also - -* [GET /api/v1/accounts/verify\_credentials]({{< relref "../methods/accounts.md#verify-account-credentials" >}}) -* [PATCH /api/v1/accounts/update\_credentials]({{< relref "../methods/accounts.md#update-account-credentials" >}}) -* [GET /api/v1/preferences]({{< relref "../methods/accounts/preferences.md#view-user-preferences" >}}) - -{{< page-ref page="methods/accounts/preferences.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/preferences_serializer.rb" caption="app/serializers/rest/preferences\_serializer.rb" >}} - - - diff --git a/content/en/entities/pushsubscription.md b/content/en/entities/pushsubscription.md deleted file mode 100644 index c85f8c2c..00000000 --- a/content/en/entities/pushsubscription.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: PushSubscription -description: Represents a subscription to the push streaming server. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "id": 328183, - "endpoint": "https://yourdomain.example/listener", - "alerts": { - "follow": false, - "favourite": false, - "reblog": false, - "mention": true, - "poll": false - }, - "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" -} -``` - -## Required attributes {#push-subscription} - -### `id` {#id} - -**Description:** The id of the push subscription in the database.\ -**Type:** String \(cast from an integer, but not guaranteed to be a number\)\ -**Version history:** Added in 2.4.0 - -### `endpoint` {#endpoint} - -**Description:** Where push alerts will be sent to.\ -**Type:** String \(URL\)\ -**Version history:** Added in 2.4.0 - -### `server_key` {#server_key} - -**Description:** The streaming server's VAPID key.\ -**Type:** String\ -**Version history:** Added in 2.4.0 - -### `alerts` {#alerts} - -**Description:** Which alerts should be delivered to the `endpoint`.\ -**Type:** Hash\ -**Version history:** Added in 2.4.0. `alerts[poll]` added in 2.8.0. - -#### `alerts[follow]` - -Receive a push notification when someone has followed you? Boolean. - -#### `alerts[favourite]` - -Receive a push notification when a status you created has been favourited by someone else? Boolean. - -#### `alerts[mention]` - -Receive a push notification when someone else has mentioned you in a status? Boolean. - -#### `alerts[reblog]` - -Receive a push notification when a status you created has been boosted by someone else? Boolean. - -#### `alerts[poll]` - -Receive a push notification when a poll you voted in or created has ended? Boolean. Added in 2.8.0 - -## See also - -{{< page-ref page="methods/notifications/push.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/web_push_subscription_serializer.rb" caption="app/serializers/rest/web\_push\_subscription\_serializer.rb" >}} - - - diff --git a/content/en/entities/report.md b/content/en/entities/report.md deleted file mode 100644 index 282e65a8..00000000 --- a/content/en/entities/report.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Report -description: Reports filed against users and/or statuses, to be taken action on by moderators. -menu: - docs: - parent: entities ---- - -{{< hint style="danger" >}} -This page is currently under construction. -{{< /hint >}} - -## Example - -```text - -``` - -## Attributes - -## See also - -{{< page-ref page="methods/accounts/reports.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/report_serializer.rb" caption="app/serializers/rest/report\_serializer.rb" >}} - - - diff --git a/content/en/entities/scheduledstatus.md b/content/en/entities/scheduledstatus.md deleted file mode 100644 index 684e5dcc..00000000 --- a/content/en/entities/scheduledstatus.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: ScheduledStatus -description: Represents a status that will be published at a future scheduled date. -menu: - docs: - parent: entities ---- - -{{< hint style="warning" >}} -This page is currently under construction. -{{< /hint >}} - -## Example - -```javascript -{ - "id": "3221", - "scheduled_at": "2019-12-05T12:33:01.000Z", - "params": { - "text": "test content", - "media_ids": null, - "sensitive": null, - "spoiler_text": null, - "visibility": null, - "scheduled_at": null, - "poll": null, - "idempotency": null, - "in_reply_to_id": null, - "application_id": 596551 - }, - "media_attachments": [] -} -``` - -## Required attributes - -### id {#id} - -**Description:** ID of the scheduled status in the database.\ -**Type:** String \(cast from an integer but not guaranteed to be a number\)\ -**Version history:** Added in 2.7.0 - -### scheduled\_at - -**Description:** ID of the status in the database.\ -**Type:** String \(ISO 8601 Datetime\)\ -**Version history:** Added in 2.7.0 - -### params - -#### params\[text\] - -#### params\[visibility\] - -#### params\[application\_id\] - -### media\_attachments - -## Optional attributes - -### params - -#### in\_reply\_to\_id - -#### media\_ids - -#### sensitive - -#### spoiler\_text - -#### scheduled\_at - -## ScheduledStatus {#scheduledstatus} - -| Attribute | Type | Nullable | Added in | -| :--- | :--- | :--- | :--- | -| `id` | String | No | 2.7.0 | -| `scheduled_at` | String \(Datetime\) | No | 2.7.0 | -| `params` | [StatusParams]() | No | 2.7.0 | -| `media_attachments` | Array of [Attachment]() | No | 2.7.0 | - -### StatusParams {#statusparams} - -| Attribute | Type | Nullable | Added in | -| :--- | :--- | :--- | :--- | -| `text` | String | No | 2.7.0 | -| `in_reply_to_id` | String | | 2.7.0 | -| `media_ids` | Array of String | | 2.7.0 | -| `sensitive` | Boolean | | 2.7.0 | -| `spoiler_text` | String | | 2.7.0 | -| `visibility` | [String \(Enum\)]() | No | 2.7.0 | -| `scheduled_at` | String \(Datetime\) | | 2.7.0 | -| `application_id` | String | No | 2.7.0 | - -## See also - -{{< page-ref page="methods/statuses/scheduled_statuses.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/scheduled_status_serializer.rb" caption="app/serializers/rest/scheduled\_status\_serializer.rb" >}} - - - diff --git a/content/en/entities/source.md b/content/en/entities/source.md deleted file mode 100644 index e835c005..00000000 --- a/content/en/entities/source.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Source -description: Represents display or publishing preferences of user's own account. Returned as an additional entity when verifying and updated credentials, as an attribute of Account. -menu: - docs: - parent: entities ---- - -## Example - -{{< code title="Excerpt from GET accounts/verify\_credentials" >}} -```javascript - "source": { - "privacy": "public", - "sensitive": false, - "language": "", - "note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/at or https://paypal.me/trwnh\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence\r\n- #1 ami cole fan account\r\n\r\n:fatyoshi:", - "fields": [ - { - "name": "Website", - "value": "https://trwnh.com", - "verified_at": "2019-08-29T04:14:55.571+00:00" - }, - { - "name": "Sponsor", - "value": "https://liberapay.com/at", - "verified_at": "2019-11-15T10:06:15.557+00:00" - }, - { - "name": "Fan of:", - "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)", - "verified_at": null - }, - { - "name": "Main topics:", - "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!", - "verified_at": null - } - ], - "follow_requests_count": 0 - } -``` -{{< /code >}} - -## Base attributes - -### `note` {#note} - -**Description:** Profile bio.\ -**Type:** String\ -**Version history:** Added in 1.5.0 - -### `fields` {#fields} - -**Description:** Metadata about the account.\ -**Type:** Array of [Field]({{< relref "field.md" >}})\ -**Version history:** Added in 2.4.0 - -## Nullable attributes - -### `privacy` {#privacy} - -**Description:** The default post privacy to be used for new statuses.\ -**Type:** String \(Enumerable, oneOf\)\ -`public` = Public post\ -`unlisted` = Unlisted post\ -`private` = Followers-only post\ -`direct` = Direct post\ -**Version history:** Added in 1.5.0 - -### `sensitive` {#sensitive} - -**Description:** Whether new statuses should be marked sensitive by default.\ -**Type:** Boolean\ -**Version history:** Added in 1.5.0 - -### `language` {#language} - -**Description:** The default posting language for new statuses.\ -**Type:** String \(ISO 639-1 language two-letter code\)\ -**Version history:** Added in 2.4.2 - -### `follow_requests_count` {#follow_requests_count} - -**Description:** The number of pending follow requests.\ -**Type:** Number\ -**Version history:** Added in 3.0.0 - -## See also - -* [Account\#source]({{< relref "account.md#source" >}}) -* [POST /api/v1/accounts/verify\_credentials]({{< relref "../methods/accounts.md#verify-account-credentials" >}}) -* [PATCH /api/v1/accounts/update\_credentials]({{< relref "../methods/accounts.md#update-account-credentials" >}}) - -{{< page-ref page="account.md" >}} - - - diff --git a/content/en/entities/tag.md b/content/en/entities/tag.md deleted file mode 100644 index 951da20e..00000000 --- a/content/en/entities/tag.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Tag -description: Represents a hashtag used within the content of a status. -menu: - docs: - parent: entities ---- - -## Example - -```javascript -{ - "name": "nowplaying", - "url": "https://mastodon.social/tags/nowplaying", - "history": [ - { - "day": "1574553600", - "uses": "200", - "accounts": "31" - }, - { - "day": "1574467200", - "uses": "272", - "accounts": "39" - }, - { - "day": "1574380800", - "uses": "345", - "accounts": "40" - }, - { - "day": "1574294400", - "uses": "366", - "accounts": "46" - }, - { - "day": "1574208000", - "uses": "226", - "accounts": "32" - }, - { - "day": "1574121600", - "uses": "217", - "accounts": "42" - }, - { - "day": "1574035200", - "uses": "214", - "accounts": "34" - } - ] -} -``` - -## Base attributes - -### `name` {#name} - -**Description:** The value of the hashtag after the \# sign.\ -**Type:** String\ -**Version history:** Added in 0.9.0 - -### `url` {#url} - -**Description:** A link to the hashtag on the instance.\ -**Type:** String \(URL\)\ -**Version history:** Added in 0.9.0 - -## Optional attributes - -### `history` {#history} - -**Description:** Usage statistics for given days.\ -**Type:** Array of [History]({{< relref "history.md" >}})\ -**Version history:** Added in 2.4.1 - -## See also - -* [Status\#tags]({{< relref "status.md#tags" >}}) -* [GET /api/v1/featured\_tags/suggestions]({{< relref "../methods/accounts/featured_tags.md#suggested-tags-to-feature" >}}) - -{{< page-ref page="status.md" >}} - -{{< page-ref page="methods/search.md" >}} - -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/tag_serializer.rb" caption="app/serializers/rest/tag\_serializer.rb" >}} - - - diff --git a/content/en/methods/accounts.md b/content/en/methods/accounts.md index 394f6a1e..49e20af7 100644 --- a/content/en/methods/accounts.md +++ b/content/en/methods/accounts.md @@ -1,105 +1,180 @@ --- -title: accounts -description: Methods concerning user accounts and related information. +title: accounts API methods +description: Methods concerning accounts and profiles. menu: docs: weight: 20 + name: accounts parent: methods identifier: methods-accounts +aliases: [ + "/methods/accounts", + "/api/methods/accounts" +] --- -## Account credentials + -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts" title="Register an account" >}} -{{< api-method-description >}} +## Register an account {#create} + +```http +POST https://mastodon.example/api/v1/accounts HTTP/1.1 +``` Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox. -**Returns:** Token\ +**Returns:** [Token]({{< relref "entities/token" >}})\ **OAuth:** App token + `write:accounts`\ **Version history:**\ 2.7.0 - added\ -3.0.0 - added `reason` parameter +3.0.0 - added `reason` parameter\ +3.4.0 - added `details` to failure response -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <app token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="username" type="string" required=true >}} -The desired username for the account -{{< endapi-method-parameter >}} -{{< api-method-parameter name="email" type="string" required=true >}} -The email address to be used for login -{{< endapi-method-parameter >}} -{{< api-method-parameter name="password" type="string" required=true >}} -The password to be used for login -{{< endapi-method-parameter >}} -{{< api-method-parameter name="agreement" type="boolean" required=true >}} -Whether the user agrees to the local rules, terms, and policies. These should be presented to the user in order to allow them to consent before setting this parameter to TRUE. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="locale" type="string" required=true >}} -The language of the confirmation email that will be sent -{{< endapi-method-parameter >}} -{{< api-method-parameter name="reason" type="string" required=false >}} -Text that will be reviewed by moderators if registrations require manual approval. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Headers +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +username +: {{}} String. The desired username for the account + +email +: {{}} String. The email address to be used for login + +password +: {{}} String. The password to be used for login + +agreement +: {{}} Boolean. Whether the user agrees to the local rules, terms, and policies. These should be presented to the user in order to allow them to consent before setting this parameter to TRUE. + +locale +: {{}} String. The language of the confirmation email that will be sent. + +reason +: String. If registrations require manual approval, this text will be reviewed by moderators. + +#### Response + +##### 200: OK + +```json ``` -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - +##### 401: Unauthorized +```json +{ + "error": "The access token is invalid" +} ``` +##### 422: Unprocessable entity + +The `details` parameter contains all detected errors. Its structure is a Hash with the key being the erroneous parameter, and its value being an array of all errors found. + +Example error response: + +```json +{ + "error": "Validation failed: Password can't be blank, Username must contain only letters, numbers and underscores, Agreement must be accepted", + "details": { + "password": [ + { + "error": "ERR_BLANK", + "description": "can't be blank" + } + ], + "username": [ + { + "error": "ERR_INVALID", + "description": "must contain only letters, numbers and underscores" + } + ], + "agreement": [ + { + "error": "ERR_ACCEPTED", + "description": "must be accepted" + } + ] + } +} +``` + +You may expect the following errors: + +ERR_BLOCKED +: When e-mail provider is not allowed + +ERR_UNREACHABLE +: When e-mail address does not resolve to any IP via DNS (MX, A, AAAA) + +ERR_TAKEN +: When username or e-mail are already taken + +ERR_RESERVED +: When a username is reserved, e.g. "webmaster" or "admin" + +ERR_ACCEPTED +: When agreement has not been accepted + +ERR_BLANK +: When a required attribute is blank + +ERR_INVALID +: When an attribute is malformed, e.g. wrong characters or invalid e-mail address + +ERR_TOO_LONG +: When an attribute is over the character limit + +ERR_TOO_SHORT +: When an attribute is under the character requirement + +ERR_INCLUSION +: When an attribute is not one of the allowed values, e.g. unsupported locale + +##### 429: Rate limited + +```json +{ + "error": "Too many requests" +} +``` + +--- + +## Verify account credentials {#verify_credentials} + +```http +GET https://mastodon.example/api/v1/accounts/verify_credentials HTTP/1.1 ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/verify_credentials" title="Verify account credentials" >}} -{{< api-method-description >}} Test to make sure that the user token works. -**Returns:** the user's own Account with Source\ +**Returns:** the user's own [Account]({{< relref "entities/Account">}}) with [`source`]({{< relref "entities/Account#source">}}) attribute\ **OAuth**: User token + `read:accounts`\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response + +##### 200: OK Note the extra `source` property, which is not visible on accounts other than your own. Also note that plain-text is used within `source` and HTML is used for their corresponding properties such as `note` and `fields`. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "14715", "username": "trwnh", @@ -179,62 +254,60 @@ Note the extra `source` property, which is not visible on accounts other than yo ] } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized Your credential verification will fail if the token is invalid or incorrect. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=403 >}} -{{< api-method-response-example-description >}} + +##### 403: Forbidden Your user account is currently disabled, missing a confirmed email address, or pending approval. -{{< endapi-method-response-example-description >}} - -{{< tabs >}} -{{< tab title="disabled" >}} -```javascript +```json { "error": "Your login is currently disabled" } ``` -{{< endtab >}} -{{< tab title="unconfirmed" >}} -```javascript +```json { "error": "Your login is missing a confirmed e-mail address" } ``` -{{< endtab >}} -{{< tab title="unapproved" >}} -```javascript +```json { "error": "Your login is currently pending approval" } ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="patch" host="https://mastodon.example" path="/api/v1/accounts/update_credentials" title="Update account credentials" >}} -{{< api-method-description >}} + +##### 422: Unprocessable entity + +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Update account credentials {#update_credentials} + +```http +PATCH https://mastodon.example/api/v1/accounts/update_credentials HTTP/1.1 +``` Update the user's display and preferences. -**Returns:** the user's own Account with Source\ +**Returns:** the user's own [Account]({{< relref "entities/Account">}}) with [`source`]({{< relref "entities/Account#source">}}) attribute\ **OAuth:** User token + `write:accounts`\ **Version history:**\ 1.1.1 - added\ @@ -242,59 +315,55 @@ Update the user's display and preferences. 2.4.0 - added `source[privacy,sensitive]` parameters\ 2.7.0 - added `discoverable` parameter -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="discoverable" type="string" required=false >}} -Whether the account should be shown in the profile directory. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="bot" type="boolean" required=false >}} -Whether the account has a bot flag. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="display_name" type="string" required=false >}} -The display name to use for the profile. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="note" type="string" required=false >}} -The account bio. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="avatar" type="string" required=false >}} -Avatar image encoded using multipart/form-data -{{< endapi-method-parameter >}} -{{< api-method-parameter name="header" type="string" required=false >}} -Header image encoded using multipart/form-data -{{< endapi-method-parameter >}} -{{< api-method-parameter name="locked" type="boolean" required=false >}} -Whether manual approval of follow requests is required. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="source\[privacy\]" type="string" required=false >}} -Default post privacy for authored statuses. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="source\[sensitive\]" type="boolean" required=false >}} -Whether to mark authored statuses as sensitive by default. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="source\[language\]" type="string" required=false >}} -Default language to use for authored statuses. \(ISO 6391\) -{{< endapi-method-parameter >}} -{{< api-method-parameter name="fields_attributes" type="array" required=false >}} -Profile metadata `name` and `value`. \(By default, max 4 fields and 255 characters per property/value\) -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +discoverable +: Boolean. Whether the account should be shown in the profile directory. + +bot +: Boolean. Whether the account has a bot flag. + +display_name +: String. The display name to use for the profile. + +note +: String. The account bio. + +avatar +: Avatar image encoded using `multipart/form-data` + +header +: Header image encoded using `multipart/form-data` + +locked +: Boolean. Whether manual approval of follow requests is required. + +source[privacy] +: String. Default post privacy for authored statuses. Can be `public`, `unlisted`, or `private`. + +source[sensitive] +: Boolean. Whether to mark authored statuses as sensitive by default. + +source[language] +: String. Default language to use for authored statuses (ISO 6391) + +fields_attributes[] +: Array. Profile metadata `name` and `value`. By default, max 4 fields and 255 characters per property/value. + +#### Response + +##### 200: OK You should use accounts/verify_credentials to first obtain plaintext representations from within the `source` parameter, then allow the user to edit these plaintext representations before submitting them through this API. The server will generate the corresponding HTML. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "14715", "username": "trwnh", @@ -374,57 +443,61 @@ You should use accounts/verify_credentials to first obtain plaintext representat ] } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +##### 422: Unprocessable entity -## Retrieve information +Token does not have an authorized user -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/:id" title="Account" >}} -{{< api-method-description >}} +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Get account {#get} + +```http +GET https://mastodon.example/api/v1/accounts/:id HTTP/1.1 +``` View information about a profile. -**Returns:** Account\ +**Returns:** [Account]({{< relref "entities/Account">}})\ **OAuth:** Public\ **Version history:**\ 0.0.0 - added\ 2.4.0 - returns 410 if account is suspended\ 3.3.0 - returns an Account with `suspended: true` instead of 410 -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters -Account record will be returned. Note that `acct` of local users does not include the domain name. -{{< endapi-method-response-example-description >}} +:id +: {{}} String. The ID of the Account in the database. +##### Headers -{{< tabs >}} -{{< tab title="Local user" >}} -```javascript +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The Account record will be returned. Note that `acct` of local users does not include the domain name. + +###### Local user + +```json { "id": "1", "username": "Gargron", @@ -458,10 +531,10 @@ Account record will be returned. Note that `acct` of local users does not includ ] } ``` -{{< endtab >}} -{{< tab title="Remote user" >}} -```javascript +###### Remote user + +```json { "id": "23634", "username": "noiob", @@ -524,10 +597,10 @@ Account record will be returned. Note that `acct` of local users does not includ ] } ``` -{{< endtab >}} -{{< tab title="Suspended user" >}} -```javascript +###### Suspended user + +```json { "id": "14", "username": "stigatle", @@ -553,463 +626,371 @@ Account record will be returned. Note that `acct` of local users does not includ "fields": [] } ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} +##### 401: Unauthorized If the instance is in whitelist mode and the Authorization header is missing or invalid -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "This API requires an authenticated user" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} + +##### 404: Not found Account does not exist -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=410 >}} -{{< api-method-response-example-description >}} -Account is suspended -{{< endapi-method-response-example-description >}} +##### 410: Gone +Account is suspended (since 2.4.0 and until 3.3.0) -```markup +--- +## Get account's statuses {#statuses} + +```http +GET https://mastodon.example/api/v1/accounts/:id/statuses HTTP/1.1 ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/:id/statuses" title="Statuses" >}} -{{< api-method-description >}} Statuses posted to the given account. -**Returns:** Array of Status\ -**OAuth:** Public \(for public statuses only\), or user token + `read:statuses` \(for private statuses the user is authorized to see\)\ +**Returns:** Array of [Status]({{< relref "entities/status">}})\ +**OAuth:** Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)\ **Version history:**\ 0.0.0 - added\ 2.6.0 - add `min_id`\ 2.7.0 - add `exclude_reblogs` and allow unauthed use\ -2.8.0 - add `tagged` parameter +2.8.0 - add `tagged` parameter\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=false >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters +:id +: {{}} String. The ID of the Account in the database. +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: String. Return results older than this ID + +since_id +: String. Return results newer than this ID + +min_id +: String. Return results immediately newer than this ID + +limit +: Integer. Maximum number of results to return. Default: 20. + +exclude_reblogs +: Boolean. Whether to filter out boosts from the response. + +tagged +: String. Filter for statuses using a specific hashtag. + +#### Response +##### 200: OK + +```json +[ + { + "id": "108880211901672326", + "created_at": "2022-08-24T22:29:46.493Z", + "in_reply_to_id": "108880209317577809", + "in_reply_to_account_id": "103641", + "sensitive": false, + // ... + }, + // ... +] ``` -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} +##### 401: Unauthorized -Instance is in whitelist mode or running a version of Mastodon older than 2.7.0, and the Authorization header is invalid or missing -{{< endapi-method-response-example-description >}} +If the instance is in whitelist mode and the Authorization header is missing or invalid +Sample response for whitelist mode: -{{< tabs >}} -{{< tab title="whitelist" >}} -```javascript +```json { "error": "This API requires an authenticated user" } ``` -{{< endtab >}} -{{< tab title="pre-2.7.0" >}} -```javascript +Sample response before 2.7.0: + +```json { "error": "The access token is invalid" } ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Account is deleted or does not exist -{{< endapi-method-response-example-description >}} +##### 404: Not found +Account does not exist -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=410 >}} -{{< api-method-response-example-description >}} -Account is suspended -{{< endapi-method-response-example-description >}} +##### 410: Gone +Account is suspended (since 2.4.0 and until 3.3.0) +--- + +## Get account's followers {#followers} + +```http +GET https://mastodon.example/api/v1/accounts/:id/followers HTTP/1.1 ``` -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/:id/followers" title="Followers" >}} -{{< api-method-description >}} - Accounts which follow the given account, if network is not hidden by the account owner. -**Returns:** Array of Account\ +**Returns:** Array of [Account]({{< relref "entities/Account">}})\ **OAuth:** App token + `read:accounts`\ **Version history:**\ -0.0.0 - added +0.0.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <app token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -**Internal parameter.** Use HTTP `Link` header for pagination. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -**Internal parameter.** Use HTTP `Link` header for pagination. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="number" required=false >}} -Maximum number of results to return. Defaults to 40. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters -Sample output with limit=2. Because the ID of follow relationships is not generally used or provided with any API calls, an HTTP `Link` header is used instead to indicate next and previous pages. You will have to parse this header yourself to extract the paging URLs. -{{< endapi-method-response-example-description >}} +:id +: {{}} String. The ID of the Account in the database. +##### Headers -```javascript -Link: ; rel="next", ; rel="prev" +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +Sample output with limit=2. + +```json [ { "id": "1020382", "username": "atul13061987", "acct": "atul13061987", "display_name": "", - "locked": false, - "bot": false, - "created_at": "2019-12-04T07:17:02.745Z", - "note": "

", - "url": "https://mastodon.social/@atul13061987", - "avatar": "https://mastodon.social/avatars/original/missing.png", - "avatar_static": "https://mastodon.social/avatars/original/missing.png", - "header": "https://mastodon.social/headers/original/missing.png", - "header_static": "https://mastodon.social/headers/original/missing.png", - "followers_count": 0, - "following_count": 2, - "statuses_count": 0, - "last_status_at": null, - "emojis": [], - "fields": [] + // ... }, { "id": "1020381", "username": "linuxliner", "acct": "linuxliner", "display_name": "", - "locked": false, - "bot": false, - "created_at": "2019-12-04T07:15:56.426Z", - "note": "

", - "url": "https://mastodon.social/@linuxliner", - "avatar": "https://mastodon.social/avatars/original/missing.png", - "avatar_static": "https://mastodon.social/avatars/original/missing.png", - "header": "https://mastodon.social/headers/original/missing.png", - "header_static": "https://mastodon.social/headers/original/missing.png", - "followers_count": 0, - "following_count": 2, - "statuses_count": 0, - "last_status_at": null, - "emojis": [], - "fields": [] + // ... } ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +Because Follow IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized Invalid or missing Authorization header, or instance is in whitelist mode and your token is not authorized with a user -{{< endapi-method-response-example-description >}} +Sample response for whitelist mode: -{{< tabs >}} -{{< tab title="header" >}} -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endtab >}} - -{{< tab title="whitelist" >}} -```javascript +```json { "error": "This API requires an authenticated user" } ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Account is deleted or does not exist -{{< endapi-method-response-example-description >}} +Sample response with missing header or invalid token: +```json +{ + "error": "The access token is invalid" +} +``` -```javascript +##### 404: Not found + +Account does not exist + +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=410 >}} -{{< api-method-response-example-description >}} -Account is suspended -{{< endapi-method-response-example-description >}} +##### 410: Gone +Account is suspended (since 2.4.0 and until 3.3.0) +--- + +## Get account's following {#following} + +```http +GET https://mastodon.example/api/v1/accounts/:id/following HTTP/1.1 ``` -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/:id/following" title="Following" >}} -{{< api-method-description >}} - Accounts which the given account is following, if network is not hidden by the account owner. -**Returns:** Array of Account\ +**Returns:** Array of [Account]({{< relref "entities/Account">}})\ **OAuth:** App token + `read:accounts`\ **Version history:**\ -0.0.0 - added +0.0.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <app token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -**Internal parameter.** Use HTTP `Link` header for pagination. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -**Internal parameter.** Use HTTP `Link` header for pagination. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="number" required=false >}} -Maximum number of results to return. Defaults to 40. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters -Sample output with limit=2. Because the ID of follow relationships is not generally used or provided with any API calls, an HTTP `Link` header is used instead to indicate next and previous pages. You will have to parse this header yourself to extract the paging URLs. -{{< endapi-method-response-example-description >}} +:id +: {{}} String. The ID of the Account in the database. +##### Headers -```javascript -Link: ; rel="next", ; rel="prev" +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +Sample output with limit=2. + +```json [ { "id": "963410", "username": "gautambhatia", "acct": "gautambhatia", "display_name": "Gautam Bhatia", - "locked": false, - "bot": false, - "created_at": "2019-11-07T13:06:57.442Z", - "note": "

SF reader, editor, and writer.

", - "url": "https://mastodon.social/@gautambhatia", - "avatar": "https://files.mastodon.social/accounts/avatars/000/963/410/original/d8e0fd5cefcf9687.jpg", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/963/410/original/d8e0fd5cefcf9687.jpg", - "header": "https://mastodon.social/headers/original/missing.png", - "header_static": "https://mastodon.social/headers/original/missing.png", - "followers_count": 1900, - "following_count": 52, - "statuses_count": 183, - "last_status_at": "2019-12-02T17:52:39.463Z", - "emojis": [], - "fields": [] + // ... }, { "id": "1007400", "username": "seafrog", "acct": "seafrog@glitterkitten.co.uk", "display_name": "🐓🦃 Heck Partridge 🤠 🦆", - "locked": false, - "bot": false, - "created_at": "2019-11-19T18:46:49.977Z", - "note": "

hi im elise!! this is scribblefrog's new account

she/her, 27

", - "url": "https://glitterkitten.co.uk/@seafrog", - "avatar": "https://files.mastodon.social/accounts/avatars/001/007/400/original/306cd22c1b118693.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/001/007/400/original/306cd22c1b118693.png", - "header": "https://files.mastodon.social/accounts/headers/001/007/400/original/fd9728559f7265f5.jpeg", - "header_static": "https://files.mastodon.social/accounts/headers/001/007/400/original/fd9728559f7265f5.jpeg", - "followers_count": 168, - "following_count": 223, - "statuses_count": 944, - "last_status_at": "2019-12-04T00:44:08.603Z", - "emojis": [], - "fields": [ - { - "name": "gotdamb", - "value": "frog", - "verified_at": null - }, - { - "name": "whomst lov", - "value": "the oceane", - "verified_at": null - } - ] - } + // ... ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +Because Follow IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. -{{< tabs >}} -{{< tab title="header" >}} -```javascript -{ - "error": "The access token is invalid" -} +```http +Link: ; rel="next", ; rel="prev" ``` -{{< endtab >}} -{{< tab title="whitelist" >}} -``` +##### 401: Unauthorized + +Invalid or missing Authorization header, or instance is in whitelist mode and your token is not authorized with a user + +Sample response for whitelist mode: + +```json { "error": "This API requires an authenticated user" } ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Account is deleted or does not exist -{{< endapi-method-response-example-description >}} +Sample response with missing header or invalid token: +```json +{ + "error": "The access token is invalid" +} +``` -```javascript +##### 404: Not found + +Account does not exist + +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=410 >}} -{{< api-method-response-example-description >}} -Account is suspended -{{< endapi-method-response-example-description >}} +##### 410: Gone +Account is suspended (since 2.4.0 and until 3.3.0) +--- + +## Get account's featured tags {#featured_tags} + +```http +GET https://mastodon.example/api/v1/accounts/:id/featured_tags HTTP/1.1 ``` -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/:id/featured_tags" title="Featured tags" >}} -{{< api-method-description >}} - Tags featured by this account. -**Returns:** Array of FeaturedTag\ -**OAuth:** User token + `read:accounts`\ +**Returns:** Array of [FeaturedTag]({{< relref "entities/featuredtag">}})\ +**OAuth:** Public\ **Version history:**\ 3.3.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters +:id +: {{}} String. The ID of the Account in the database. -```javascript +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json [ { "id": "627", @@ -1019,59 +1000,39 @@ Bearer <user token> } ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +--- +## Get lists containing this account {#lists} -```javascript -{ - "error": "The access token is invalid" -} +```http +GET https://mastodon.example/api/v1/accounts/:id/lists HTTP/1.1 ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/:id/lists" title="Lists containing this account" >}} -{{< api-method-description >}} User lists that you have added this account to. -**Returns:** Array of List\ +**Returns:** Array of [List]({{< relref "entities/list">}})\ **OAuth:** User token + `read:lists`\ **Version history:**\ 2.1.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK If the account is part of any lists, those entities will be returned. If the account is not part of any of your lists, then an empty array will be returned. -{{< endapi-method-response-example-description >}} - -{{< tabs >}} -{{< tab title="part of lists" >}} -```javascript +```json [ { "id": "13694", @@ -1079,174 +1040,101 @@ If the account is part of any lists, those entities will be returned. If the acc } ] ``` -{{< endtab >}} -{{< tab title="not in any lists" >}} -```javascript +```json [] ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header, or instance is in whitelist mode and your token is not authorized with a user -```javascript +Sample response for whitelist mode: + +```json +{ + "error": "This API requires an authenticated user" +} +``` + +Sample response with missing header or invalid token: + +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Account with given id does not exist or is deleted -{{< endapi-method-response-example-description >}} +##### 404: Not found +Account does not exist -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=410 >}} -{{< api-method-response-example-description >}} -Account with given id is suspended -{{< endapi-method-response-example-description >}} +##### 410: Gone +Account is suspended (since 2.4.0 and until 3.3.0) -``` +##### 422: Unprocessable entity -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/:id/identity_proofs" title="Identity proofs" >}} -{{< api-method-description >}} +Token does not have an authorized user -**Returns:** Array of IdentityProof\ -**OAuth:** User token\ -**Version history:**\ -2.8.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "provider": "Keybase", - "provider_username": "gargron", - "updated_at": "2019-07-21T20:14:39.596Z", - "proof_url": "https://keybase.io/gargron/sigchain#5cfc20c7018f2beefb42a68836da59a792e55daa4d118498c9b1898de7e845690f", - "profile_url": "https://keybase.io/gargron" - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -Account with given id is deleted or does not exist -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=410 >}} -{{< api-method-response-example-description >}} - -Account with given id is suspended -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript +```json { "error": "This method requires an authenticated user" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- -## Perform actions on an account +## Follow account {#follow} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/follow" title="Follow" >}} -{{< api-method-description >}} +```http +POST https://mastodon.example/api/v1/accounts/:id/follow HTTP/1.1 +``` Follow the given account. Can also be used to update whether to show reblogs or enable notifications. -**Returns:** Relationship\ -**OAuth:** User token + `write:follows` or `follow`\ +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ +**OAuth:** User token + `write:follows`\ **Version history:**\ 0.0.0 - added\ -3.3.0 - added `notify` +3.3.0 - added `notify`\ +3.5.0 - deprecated `follow` scope. now additionally accepts `write`\ +4.0.0 - added `languages` -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="reblogs" type="boolean" required=false >}} -Receive this account's reblogs in home timeline? Defaults to true. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="notify" type="boolean" required=false >}} -Receive notifications when this account posts a status? Defaults to false. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +reblogs +: Boolean. Receive this account's reblogs in home timeline? Defaults to true. + +notify +: Boolean. Receive notifications when this account posts a status? Defaults to false. + +languages +: Array of String (ISO 639-1 language two-letter code). Filter received statuses for these languages. If not provided, you will receive this account's posts in all languages. + +#### Response +##### 200: OK Successfully followed, or account was already followed -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "3", "following": true, @@ -1262,56 +1150,60 @@ Successfully followed, or account was already followed "endorsed": false } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=403 >}} -{{< api-method-response-example-description >}} + +##### 403: Forbidden Trying to follow someone that you block or that blocks you -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "This action is not allowed" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/unfollow" title="Unfollow" >}} -{{< api-method-description >}} + +##### 422: Unprocessable entity + +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Unfollow account {#unfollow} + +```http +POST https://mastodon.example/api/v1/accounts/:id/unfollow HTTP/1.1 +``` Unfollow the given account. -**Returns:** Relationship\ -**OAuth:** User token + `write:follows` or `follow`\ +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ +**OAuth:** User token + `write:follows`\ **Version history:**\ -0.0.0 - added +0.0.0 - added\ +3.5.0 - deprecated `follow` scope. now additionally accepts `write` -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Successfully unfollowed, or account was already not followed -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "3", "following": false, @@ -1327,56 +1219,128 @@ Successfully unfollowed, or account was already not followed "endorsed": false } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/block" title="Block" >}} -{{< api-method-description >}} -Block the given account. Clients should filter statuses from this account if received \(e.g. due to a boost in the Home timeline\) +##### 422: Unprocessable entity -**Returns:** Relationship\ -**OAuth:** User token + `write:blocks` or `follow`\ +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Remove account from followers {#remove_from_followers} + +```http +POST https://mastodon.example/api/v1/accounts/:id/remove_from_followers HTTP/1.1 +``` + +Remove the given account from your followers. + +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ +**OAuth:** User token + `write:follows`\ **Version history:**\ -0.0.0 - added +3.5.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Successfully removed from followers, or account was already not following you + +```json +{ + "id": "3", + "following": false, + "showing_reblogs": false, + "notifying": false, + "followed_by": false, + "blocking": false, + "blocked_by": false, + "muting": false, + "muting_notifications": false, + "requested": false, + "domain_blocking": false, + "endorsed": false +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Block account {#block} + +```http +POST https://mastodon.example/api/v1/accounts/:id/block HTTP/1.1 +``` + +Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline) + +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ +**OAuth:** User token + `write:blocks`\ +**Version history:**\ +0.0.0 - added\ +3.5.0 - deprecated `follow` scope. now additionally accepts `write` + +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Successfully blocked, or account was already blocked -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "3", "following": false, @@ -1392,56 +1356,60 @@ Successfully blocked, or account was already blocked "endorsed": false } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/unblock" title="Unblock" >}} -{{< api-method-description >}} + +##### 422: Unprocessable entity + +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Unblock account {#unblock} + +```http +POST https://mastodon.example/api/v1/accounts/:id/unblock HTTP/1.1 +``` Unblock the given account. -**Returns:** Relationship\ -**OAuth:** User token + `write:blocks` or `follow`\ +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ +**OAuth:** User token + `write:blocks`\ **Version history:**\ -0.0.0 - added +0.0.0 - added\ +3.5.0 - deprecated `follow` scope. now additionally accepts `write` -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Successfully unblocked, or account was already not blocked -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "3", "following": false, @@ -1457,64 +1425,69 @@ Successfully unblocked, or account was already not blocked "endorsed": false } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/mute" title="Mute" >}} -{{< api-method-description >}} -Mute the given account. Clients should filter statuses and notifications from this account, if received \(e.g. due to a boost in the Home timeline\). +##### 422: Unprocessable entity -**Returns:** Relationship\ -**OAuth:** User token + `write:mutes` or `follow`\ +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Mute account {#mute} + +```http +POST https://mastodon.example/api/v1/accounts/:id/mute HTTP/1.1 +``` + +Mute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline). + +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ +**OAuth:** User token + `write:mutes`\ **Version history:**\ -0.0.0 - added +0.0.0 - added\ +3.3.0 - added `duration`\ +3.5.0 - deprecated `follow` scope. now additionally accepts `write` -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="notifications" type="boolean" required=false >}} -Mute notifications in addition to statuses? Defaults to true. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="duration" type="number" required=false >}} -How long the mute should last, in seconds. Defaults to 0 (indefinite). -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +notifications +: Boolean. Mute notifications in addition to statuses? Defaults to true. + +duration +: Number. How long the mute should last, in seconds. Defaults to 0 (indefinite). + +#### Response +##### 200: OK Successfully muted, or account was already muted. Note that you can call this API method again with notifications=false to update the relationship so that only statuses are muted. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "3", "following": false, @@ -1530,56 +1503,60 @@ Successfully muted, or account was already muted. Note that you can call this AP "endorsed": false } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/unmute" title="Unmute" >}} -{{< api-method-description >}} + +##### 422: Unprocessable entity + +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Unmute account {#unmute} + +```http +POST https://mastodon.example/api/v1/accounts/:id/unmute HTTP/1.1 +``` Unmute the given account. -**Returns:** Relationship\ -**OAuth:** User token + `write:mutes` or `follow`\ +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ +**OAuth:** User token + `write:mutes`\ **Version history:**\ -0.0.0 - added +0.0.0 - added\ +3.5.0 - deprecated `follow` scope. now additionally accepts `write` -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Successfully unmuted, or account was already unmuted -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "3", "following": false, @@ -1595,56 +1572,60 @@ Successfully unmuted, or account was already unmuted "endorsed": false } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/pin" title="Feature on profile" >}} -{{< api-method-description >}} -Add the given account to the user's featured profiles. \(Featured profiles are currently shown on the user's own public profile.\) +##### 422: Unprocessable entity -**Returns:** Relationship\ +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Feature account on your profile {#pin} + +```http +POST https://mastodon.example/api/v1/accounts/:id/pin HTTP/1.1 +``` + +Add the given account to the user's featured profiles. (Featured profiles are currently shown on the user's own public profile.) + +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ **OAuth:** User token + `write:accounts`\ **Version history:**\ -2.5.0 - added +2.5.0 - added\ +4.0.0 - calling this method is now idempotent -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters -Successfully endorsed. -{{< endapi-method-response-example-description >}} +:id +: {{}} String. The ID of the Account in the database. +##### Headers -```javascript +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Successfully endorsed, or was already endorsing. + +```json { "id": "1", "following": true, @@ -1660,93 +1641,89 @@ Successfully endorsed. "endorsed": true } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=403 >}} -{{< api-method-response-example-description >}} -Token is not authorized with a valid user or is missing a required scope -{{< endapi-method-response-example-description >}} +##### 403: Forbidden +Token is missing a required scope -```javascript +```json { "error": "This action is outside the authorized scopes" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} + +##### 422: Unprocessable entity You are not following this account -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "Validation failed: You must be already following the person you want to endorse" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=500 >}} -{{< api-method-response-example-description >}} - -Account already endorsed -{{< endapi-method-response-example-description >}} +Alternatively, the token is not authorized with a user +```json +{ + "error": "This method requires an authenticated user" +} ``` +Alternatively (prior to 4.0), the account may already be endorsed + +```json +{ + "error": "Duplicate record" +} +``` + +##### 500: Server error + +Can sometimes be returned if the account already endorsed. + +--- + +## Unfeature account from profile {#unpin} + +```http +POST https://mastodon.example/api/v1/accounts/:id/unpin HTTP/1.1 ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/unpin" title="Unfeature on profile" >}} -{{< api-method-description >}} Remove the given account from the user's featured profiles. -**Returns:** Relationship\ +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ **OAuth:** User + `write:accounts`\ **Version history:**\ 2.5.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Successfully unendorsed, or account was already not endorsed -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "1", "following": true, @@ -1762,68 +1739,64 @@ Successfully unendorsed, or account was already not endorsed "endorsed": false } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized -```javascript +Invalid or missing Authorization header + +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 422: Unprocessable entity +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} ``` +--- + +## Set private note on profile {#note} + +```http +POST https://mastodon.example/api/v1/accounts/:id/note HTTP/1.1 ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/accounts/:id/note" title="User note" >}} -{{< api-method-description >}} Sets a private note on a user. -**Returns:** Relationship\ +**Returns:** [Relationship]({{< relref "entities/relationship">}})\ **OAuth:** User + `write:accounts`\ **Version history:**\ 3.2.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="comment" type="string" required=false >}} -The comment to be set on that user. Provide an empty string or leave out this parameter to clear the currently set note. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Path parameters -Successfully updated user note -{{< endapi-method-response-example-description >}} +:id +: {{}} String. The ID of the Account in the database. +##### Headers -```javascript +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +comment +: String. The comment to be set on that user. Provide an empty string or leave out this parameter to clear the currently set note. + +#### Response +##### 200: OK + +Successfully updated profile note + +```json { "id": "1", "following": true, @@ -1840,67 +1813,79 @@ Successfully updated user note "note": "this is a comment" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +Successfully removed profile note -```javascript +```json +{ + "id": "1", + "following": true, + "showing_reblogs": true, + "notifying": false, + "followed_by": true, + "blocking": false, + "blocked_by": false, + "muting": false, + "muting_notifications": false, + "requested": false, + "domain_blocking": false, + "endorsed": false, + "note": "" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header + +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 422: Unprocessable entity +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} ``` +--- + +## Check relationships to other accounts {#relationships} + +```http +GET https://mastodon.example/api/v1/accounts/relationships HTTP/1.1 ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - -## General account actions - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/relationships" title="Check relationships to other accounts" >}} -{{< api-method-description >}} Find out whether a given account is followed, blocked, muted, etc. -**Returns:** Array of Relationship\ +**Returns:** Array of [Relationship]({{< relref "entities/relationship">}})\ **OAuth:** User token + `read:follows`\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="id\[\]" type="array" required=true >}} -Array of account IDs to check -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Headers -Sample call with id\[\]=1&id\[\]=2 -{{< endapi-method-response-example-description >}} +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +##### Query parameters -```javascript +id[] +: Array. Check relationships for the provided account IDs. + +#### Response +##### 200: OK + +Sample call with `id[]=1&id[]=2` + +```json [ { "id": "1", @@ -1932,119 +1917,333 @@ Sample call with id\[\]=1&id\[\]=2 } ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} + +##### 422: Unprocessable entity Token does not have an authorized user -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "This method requires an authenticated user" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/accounts/search" title="Search for matching accounts" >}} -{{< api-method-description >}} + +--- + +## Find familiar followers {#familiar_followers} + +```http +GET https://mastodon.example/api/v1/accounts/familiar_followers HTTP/1.1 +``` + +Obtain a list of all accounts that follow a given account, filtered for accounts you follow. + +**Returns:** Array of [FamiliarFollowers]({{< relref "entities/FamiliarFollowers">}})\ +**OAuth:** User token + `read:follows`\ +**Version history:**\ +3.5.0 - added + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +id[] +: Array of String. Find familiar followers for the provided account IDs. + +#### Response +##### 200: OK + +Sample call with `id[]=1&id[]=2` + +```json +[ + { + "id":"1", + "accounts":[ + { + "id":"1087990", + "username":"moss", + "acct":"moss@goblin.camp", + // ... + }, + { + "id":"1092723", + "username":"vivianrose", + "acct":"vivianrose", + // ... + }, + // ... + ] + }, + { + "id":"2", + "accounts":[] + } +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## Search for matching accounts {#search} + +```http +GET https://mastodon.example/api/v1/accounts/search HTTP/1.1 +``` Search for matching accounts by username or display name. -**Returns:** Array of Account\ +**Returns:** Array of [Account]({{< relref "entities/Account">}})\ **OAuth:** User token + `read:accounts`\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="q" type="string" required=true >}} -What to search for -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="number" required=false >}} -Maximum number of results. Defaults to 40. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="resolve" type="string" required=false >}} -Attempt WebFinger lookup. Defaults to false. Use this when `q` is an exact address. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="following" type="string" required=false >}} -Only who the user is following. Defaults to false. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +q +: {{}} String. Search query for accounts. + +limit +: Maximum number of results. Defaults to 40. + +resolve +: Boolean. Attempt WebFinger lookup. Defaults to false. Use this when `q` is an exact address. + +following +: Boolean. Limit the search to users you are following. Defaults to false. + +#### Response +##### 200: OK Accounts matching "trwnh" in username or display name -{{< endapi-method-response-example-description >}} - -```javascript +```json [ { "id": "14715", "username": "trwnh", "acct": "trwnh", "display_name": "infinite love ⴳ", - ... + // ... }, { "id": "418714", "username": "trwnh", "acct": "trwnh@pixelfed.social", "display_name": "Abdullah Tarawneh", - ... + // ... }, { "id": "419674", "username": "trwnh", "acct": "trwnh@write.as", "display_name": "trwnh", - ... + // ... }, - ... + // ... ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=503 >}} -{{< api-method-response-example-description >}} + +##### 503: Service Unavailable resolve=true, but the domain part of the user@domain address is not a currently live website -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "Remote data could not be fetched" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## Lookup account ID from Webfinger address {#lookup} + +```http +GET https://mastodon.example/api/v1/accounts/lookup HTTP/1.1 +``` + +Quickly lookup a username to see if it is available, or quickly resolve a Webfinger address to an account ID. + +**Returns:** [Account]({{< relref "entities/Account">}})\ +**OAuth:** Public\ +**Version history:**\ +3.4.0 - added + +#### Request +##### Query parameters + +acct +: {{}} String. The username or Webfinger address to lookup. + +skip_webfinger +: Boolean. Whether to use the locally cached result instead of performing full Webfinger resolution. Defaults to true. + +#### Response +##### 200: OK + +Sample call with `?acct=trwnh` + +```json +{ + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + "locked": false, + // ... +} +``` + +Sample call with `?acct=trwnh@pixelfed.social` + +```json +{ + "id": "418714", + "username": "trwnh", + "acct": "trwnh@pixelfed.social", + "display_name": "Abdullah Tarawneh", + "locked": false, + // ... +} +``` + +##### 404: Not found + +Username or address does not map to an account + +```json +{ + "error": "Record not found" +} +``` + +--- + +## (DEPRECATED) Identity proofs {#identity_proofs} + +```http +GET https://mastodon.example/api/v1/accounts/:id/identity_proofs HTTP/1.1 +``` + +**Returns:** Array of [IdentityProof]({{< relref "entities/identityproof">}})\ +**OAuth:** User token\ +**Version history:**\ +2.8.0 - added\ +3.5.0 - deprecated. now returns an empty array. + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +#### Response +##### 200: OK + +```json +[ + { + "provider": "Keybase", + "provider_username": "gargron", + "updated_at": "2019-07-21T20:14:39.596Z", + "proof_url": "https://keybase.io/gargron/sigchain#5cfc20c7018f2beefb42a68836da59a792e55daa4d118498c9b1898de7e845690f", + "profile_url": "https://keybase.io/gargron" + } +] +``` + +##### 404: Not found + +Account does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 410: Gone + +Account is suspended (since 2.4.0 and until 3.3.0) + +##### 422: Unprocessable entity + +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts_controller.rb" caption="app/controllers/api/v1/accounts_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/credentials_controller.rb" caption="app/controllers/api/v1/accounts/credentials_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/familiar_followers_controller.rb" caption="app/controllers/api/v1/accounts/familiar_followers_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/featured_tags_controller.rb" caption="app/controllers/api/v1/accounts/featured_tags_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/follower_accounts_controller.rb" caption="app/controllers/api/v1/accounts/follower_accounts_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/following_accounts_controller.rb" caption="app/controllers/api/v1/accounts/following_accounts_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/identity_proofs_controller.rb" caption="app/controllers/api/v1/accounts/identity_proofs_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/lists_controller.rb" caption="app/controllers/api/v1/accounts/lists_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/lookup_controller.rb" caption="app/controllers/api/v1/accounts/lookup_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/notes_controller.rb" caption="app/controllers/api/v1/accounts/notes_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/pins_controller.rb" caption="app/controllers/api/v1/accounts/pins_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/relationships_controller.rb" caption="app/controllers/api/v1/accounts/relationships_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/search_controller.rb" caption="app/controllers/api/v1/accounts/search_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/statuses_controller.rb" caption="app/controllers/api/v1/accounts/statuses_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/accounts/blocks.md b/content/en/methods/accounts/blocks.md deleted file mode 100644 index d4ea6c10..00000000 --- a/content/en/methods/accounts/blocks.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: blocks -description: 'View your blocks. See also accounts/:id/{block,unblock}' -menu: - docs: - weight: 40 - parent: methods-accounts ---- - -{{< api-method method="get" host="" path="/api/v1/blocks" title="Blocked users" >}} -{{< api-method-description >}} - -**Returns:** Array of Account\ -**OAuth:** User token + `read:blocks`\ -**Version history:**\ -0.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -**Internal parameter.** Use HTTP Link header for pagination instead. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -**Internal parameter.** Use HTTP Link header for pagination instead. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results. Defaults to 40. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Sample call with limit=2. Because block ids are private, you must parse the HTTP `Link` header to find next and previous pages. -{{< endapi-method-response-example-description >}} - - -```javascript -Link: ; rel="next", ; rel="prev" - -[ - { - "id": "585315", - "username": "admin", - "acct": "admin@happylittle.cloudns.cc", - "display_name": "☁️ ⛅ Happy Little Clouds ⛅ ☁️", - "locked": false, - "bot": false, - "created_at": "2018-11-09T21:37:50.982Z", - "note": "Novice programmer. Freedom lover. Distributed network software enthusiast.", - "url": "https://happylittle.cloudns.cc/users/admin", - "avatar": "https://files.mastodon.social/accounts/avatars/000/585/315/original/5a2d62acfe7f6e7d.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/585/315/original/5a2d62acfe7f6e7d.png", - "header": "https://files.mastodon.social/accounts/headers/000/585/315/original/122940e256a42ac8.png", - "header_static": "https://files.mastodon.social/accounts/headers/000/585/315/original/122940e256a42ac8.png", - "followers_count": 25, - "following_count": 41, - "statuses_count": 173, - "last_status_at": "2019-11-21T14:59:07.345Z", - "emojis": [], - "fields": [] - }, - { - "id": "650568", - "username": "Nikolai_Kingsley", - "acct": "Nikolai_Kingsley@dobbs.town", - "display_name": "Rev.Dr. Nikolai Kingsley", - "locked": false, - "bot": false, - "created_at": "2018-12-15T02:25:57.424Z", - "note": "

Justifiability is in the hands of the beholder
And you just don't know what people will do next
- todd rundgren, \"Zen Archer\"

", - "url": "https://dobbs.town/@Nikolai_Kingsley", - "avatar": "https://files.mastodon.social/accounts/avatars/000/650/568/original/2e80c95aab9f8071.gif", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/650/568/static/2e80c95aab9f8071.png", - "header": "https://files.mastodon.social/accounts/headers/000/650/568/original/10c19760ca5bbae5.jpeg", - "header_static": "https://files.mastodon.social/accounts/headers/000/650/568/original/10c19760ca5bbae5.jpeg", - "followers_count": 135, - "following_count": 130, - "statuses_count": 10807, - "last_status_at": "2019-11-23T08:07:34.745Z", - "emojis": [], - "fields": [] - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -If the Authorization header contains an invalid token, is malformed, or is not present, an error will be returned indicating an authorization failure. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/bookmarks.md b/content/en/methods/accounts/bookmarks.md deleted file mode 100644 index eef7e81e..00000000 --- a/content/en/methods/accounts/bookmarks.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: bookmarks -description: 'View your bookmarks. See also statuses/:id/{bookmark,unbookmark}' -menu: - docs: - weight: 10 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/bookmarks" title="Bookmarked statuses" >}} -{{< api-method-description >}} - -Statuses the user has bookmarked. - -**Returns:** Array of Status\ -**OAuth:** User token + `read:bookmarks`\ -**Version history:**\ -3.1.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/domain_blocks.md b/content/en/methods/accounts/domain_blocks.md deleted file mode 100644 index adde5b3a..00000000 --- a/content/en/methods/accounts/domain_blocks.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: domain_blocks -description: View and update domain blocks. -menu: - docs: - weight: 50 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/domain_blocks" title="Fetch domain blocks" >}} -{{< api-method-description >}} - -View domains the user has blocked. - -**Returns:** Array of strings\ -**OAuth:** User token + `read:blocks` or `follow`\ -**Version:**\ -1.4.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -**Internal parameter.** Use HTTP Link header from response for pagination. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -**Internal parameter.** Use HTTP Link header from response for pagination. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results to return per page. Defaults to 40. NOTE: Pagination is done with the Link header from the response. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Sample call with limit=2. Because domain ids are not public, you must parse the HTTP Link header to access next and previous pages. -{{< endapi-method-response-example-description >}} - - -```javascript -Link: ; rel="next", ; rel="prev" - -["nsfw.social","artalley.social"] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Incorrect Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/domain_blocks" title="Block a domain" >}} -{{< api-method-description >}} - -Block a domain to: -- hide all public posts from it -- hide all notifications from it -- remove all followers from it -- prevent following new users from it \(but does not remove existing follows\) - -**Returns:** n/a\ -**OAuth:** User token + ****`write:blocks` or `follow`\ -**Version:**\ -1.4.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="domain" type="string" required=true >}} -Domain to block. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -If the call was successful, an empty object will be returned. Note that the call will be successful even if the domain is already blocked or if the domain does not exist or if the domain is not a domain. -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Incorrect Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -If `domain` is not provided or contains spaces, the request will fail. -{{< endapi-method-response-example-description >}} - - -{{< tabs >}} -{{< tab title="empty" >}} -```javascript -{ - "error": "Validation failed: Domain can't be blank" -} -``` -{{< endtab >}} - -{{< tab title="invalid" >}} -```javascript -{ - "error": "Validation failed: Domain is not a valid domain name" -} -``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/domain_blocks" title="Unblock a domain" >}} -{{< api-method-description >}} - -Remove a domain block, if it exists in the user's array of blocked domains. - -**Returns:** n/a\ -**OAuth:** User token + `write:blocks` or `follow`\ -**Version history:**\ -1.4.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="domain" type="string" required=true >}} -Domain to unblock. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -If the call was successful, an empty object will be returned. Note that the call will be successful even if the domain was not previously blocked. -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Incorrect Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -If `domain` is not provided or contains spaces, the request will fail. -{{< endapi-method-response-example-description >}} - - -{{< tabs >}} -{{< tab title="empty" >}} -```javascript -{ - "error": "Validation failed: Domain can't be blank" -} -``` -{{< endtab >}} - -{{< tab title="invalid domain" >}} -```javascript -{ - "error": "Validation failed: Domain is not a valid domain name" -} -``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/favourites.md b/content/en/methods/accounts/favourites.md deleted file mode 100644 index 20702cdf..00000000 --- a/content/en/methods/accounts/favourites.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: favourites -description: 'View your favourites. See also statuses/:id/{favourite,unfavourite}' -menu: - docs: - weight: 20 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/favourites" title="Favourited statuses" >}} -{{< api-method-description >}} - -Statuses the user has favourited. - -**Returns:** Array of Status\ -**OAuth:** User token + `read:favourites`\ -**Version:**\ -0.0.0 - added\ -2.6.0 - `min_id` added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Internal parameter. Use HTTP `Link` header for pagination instead. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Internal parameter. Use HTTP `Link` header for pagination instead. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -An example call with limit=2. Results will be returned as a Status entity with embedded Account entity. Because the id of a favourite is not public, an HTTP `Link` header can be parsed for next and previous pages.Internal -{{< endapi-method-response-example-description >}} - - -```javascript -Link: ; rel="next", ; rel="prev" - -[ - "id": "103186075217296344", - "created_at": "2019-11-23T07:35:52.000Z", - "in_reply_to_id": null, - "in_reply_to_account_id": null, - "sensitive": false, - "spoiler_text": "", - "visibility": "unlisted", - "language": "enCy", - "uri": "https://cybre.space/users/haskal/statuses/103186075002013902", - "url": "https://cybre.space/@haskal/103186075002013902", - "replies_count": 0, - "reblogs_count": 1, - "favourites_count": 1, - "favourited": true, - "reblogged": false, - "muted": false, - "bookmarked": false, - "content": "

the pirate gay

", - "reblog": null, - "account": { - "id": "297420", - "username": "haskal", - "acct": "haskal@cybre.space", - "display_name": "soft nb friend :blobcatsleep:", - "locked": false, - "bot": false, - "created_at": "2018-03-16T00:47:36.470Z", - "note": "

a very distinctive nya

systems hecker, -1x engineer, server maid, professional yak shaver
free software | digital rights | rhythm games | cyberponk | homelab | ham radio | electronics

🇺🇸/🇭🇺/🏴‍☠️
21; they/them

b618ac8ac69b6ac7bae267acb1a81e

", - "url": "https://cybre.space/@haskal", - "avatar": "https://files.mastodon.social/accounts/avatars/000/297/420/original/5e2def6e305cecee.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/297/420/original/5e2def6e305cecee.png", - "header": "https://files.mastodon.social/accounts/headers/000/297/420/original/2df598299cc677db.png", - "header_static": "https://files.mastodon.social/accounts/headers/000/297/420/original/2df598299cc677db.png", - "followers_count": 268, - "following_count": 258, - "statuses_count": 8743, - "last_status_at": "2019-11-23T07:49:39.880Z", - "emojis": [ - { - "shortcode": "blobcatsleep", - "url": "https://files.mastodon.social/custom_emojis/images/000/077/451/original/fc39ac6778d2ca02.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/077/451/static/fc39ac6778d2ca02.png", - "visible_in_picker": true - } - ], - "fields": [ - { - "name": "web", - "value": "https://tilde.town/~haskal", - "verified_at": "2019-11-22T21:16:30.009+00:00" - }, - { - "name": "other web", - "value": "https://awoo.systems", - "verified_at": "2019-11-22T21:16:30.578+00:00" - }, - { - "name": "xmpp", - "value": "haskal@lain.faith", - "verified_at": null - }, - { - "name": "matrix", - "value": "@haskal:matrix.org", - "verified_at": null - } - ] - }, - "media_attachments": [], - "mentions": [], - "tags": [], - "emojis": [], - "card": null, - "poll": null - }, - { - "id": "103186044372624124", - "created_at": "2019-11-23T07:28:03.000Z", - "in_reply_to_id": null, - "in_reply_to_account_id": null, - "sensitive": true, - "spoiler_text": "no context", - "visibility": "unlisted", - "language": "enCy", - "uri": "https://cybre.space/users/haskal/statuses/103186044253681902", - "url": "https://cybre.space/@haskal/103186044253681902", - "replies_count": 1, - "reblogs_count": 0, - "favourites_count": 1, - "favourited": true, - "reblogged": false, - "muted": false, - "bookmarked": false, - "content": "

cute,,,

", - "reblog": null, - "account": { - "id": "297420", - "username": "haskal", - "acct": "haskal@cybre.space", - "display_name": "soft nb friend :blobcatsleep:", - "locked": false, - "bot": false, - "created_at": "2018-03-16T00:47:36.470Z", - "note": "

a very distinctive nya

systems hecker, -1x engineer, server maid, professional yak shaver
free software | digital rights | rhythm games | cyberponk | homelab | ham radio | electronics

🇺🇸/🇭🇺/🏴‍☠️
21; they/them

b618ac8ac69b6ac7bae267acb1a81e

", - "url": "https://cybre.space/@haskal", - "avatar": "https://files.mastodon.social/accounts/avatars/000/297/420/original/5e2def6e305cecee.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/297/420/original/5e2def6e305cecee.png", - "header": "https://files.mastodon.social/accounts/headers/000/297/420/original/2df598299cc677db.png", - "header_static": "https://files.mastodon.social/accounts/headers/000/297/420/original/2df598299cc677db.png", - "followers_count": 268, - "following_count": 258, - "statuses_count": 8743, - "last_status_at": "2019-11-23T07:49:39.880Z", - "emojis": [ - { - "shortcode": "blobcatsleep", - "url": "https://files.mastodon.social/custom_emojis/images/000/077/451/original/fc39ac6778d2ca02.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/077/451/static/fc39ac6778d2ca02.png", - "visible_in_picker": true - } - ], - "fields": [ - { - "name": "web", - "value": "https://tilde.town/~haskal", - "verified_at": "2019-11-22T21:16:30.009+00:00" - }, - { - "name": "other web", - "value": "https://awoo.systems", - "verified_at": "2019-11-22T21:16:30.578+00:00" - }, - { - "name": "xmpp", - "value": "haskal@lain.faith", - "verified_at": null - }, - { - "name": "matrix", - "value": "@haskal:matrix.org", - "verified_at": null - } - ] - }, - "media_attachments": [], - "mentions": [], - "tags": [], - "emojis": [], - "card": null, - "poll": null - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -If a user token is not provided or is incorrect, the request will fail. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/featured_tags.md b/content/en/methods/accounts/featured_tags.md deleted file mode 100644 index 547e6cd7..00000000 --- a/content/en/methods/accounts/featured_tags.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -title: featured_tags -description: Feature tags that you use frequently. -menu: - docs: - weight: 100 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/featured_tags" title="View your featured tags" >}} -{{< api-method-description >}} - -**Returns:** Array of FeaturedTag\ -**OAuth:** User token + `read:accounts`\ -**Version history:**\ -3.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "id": "627", - "name": "nowplaying", - "statuses_count": 36, - "last_status_at": "2019-11-15T07:14:43.524Z" - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/featured_tags" title="Feature a tag" >}} -{{< api-method-description >}} - -**Returns:** FeaturedTag\ -**OAuth:** User token + `write:accounts`\ -**Version history:**\ -3.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="name" type="string" required=true >}} -The hashtag to be featured. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -A FeaturedTag will be created with the specified `name`. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "13174", - "name": "circasurvive", - "statuses_count": 11, - "last_status_at": "2019-11-15T06:20:32.769Z" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -If `name` is not a valid hashtag, e.g. contains illegal characters or only numbers -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Validation failed: Tag is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/featured_tags/:id" title="Unfeature a tag" >}} -{{< api-method-description >}} - -**Returns:** empty object\ -**OAuth:** User token + `write:accounts`\ -**Version history:**\ -3.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the FeaturedTag to be unfeatured. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -An empty object will be returned if the featured tag was successfully deleted. -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -If the ID does not exist or is not owned by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/featured_tags/suggestions" title="Suggested tags to feature" >}} -{{< api-method-description >}} - -Shows your 10 most-used tags, with usage history for the past week. - -**Returns:** Array of Tag with History\ -**OAuth:** User token + `read:accounts`\ -**Version history:**\ -3.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Truncated results to first and last tag. -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "name": "nowplaying", - "url": "https://mastodon.social/tags/nowplaying", - "history": [ - { - "day": "1574553600", - "uses": "200", - "accounts": "31" - }, - { - "day": "1574467200", - "uses": "272", - "accounts": "39" - }, - { - "day": "1574380800", - "uses": "345", - "accounts": "40" - }, - { - "day": "1574294400", - "uses": "366", - "accounts": "46" - }, - { - "day": "1574208000", - "uses": "226", - "accounts": "32" - }, - { - "day": "1574121600", - "uses": "217", - "accounts": "42" - }, - { - "day": "1574035200", - "uses": "214", - "accounts": "34" - } - ] - }, - ... - { - "name": "mastothemes", - "url": "https://mastodon.social/tags/mastothemes", - "history": [ - { - "day": "1574553600", - "uses": "0", - "accounts": "0" - }, - { - "day": "1574467200", - "uses": "0", - "accounts": "0" - }, - { - "day": "1574380800", - "uses": "0", - "accounts": "0" - }, - { - "day": "1574294400", - "uses": "0", - "accounts": "0" - }, - { - "day": "1574208000", - "uses": "0", - "accounts": "0" - }, - { - "day": "1574121600", - "uses": "0", - "accounts": "0" - }, - { - "day": "1574035200", - "uses": "0", - "accounts": "0" - } - ] - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/filters.md b/content/en/methods/accounts/filters.md deleted file mode 100644 index ce1f05f7..00000000 --- a/content/en/methods/accounts/filters.md +++ /dev/null @@ -1,435 +0,0 @@ ---- -title: filters -description: Create and manage filters. -menu: - docs: - weight: 60 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/filters" title="View all filters" >}} -{{< api-method-description >}} - -**Returns:** Filter\ -**OAuth:** User token + `read:filters`\ -**Version history:**\ -2.4.3 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Excerpts of various filters in different contexts. -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "id": "6191", - "phrase": ":eurovision2019:", - "context": [ - "home" - ], - "whole_word": true, - "expires_at": "2019-05-21T13:47:31.333Z", - "irreversible": false - }, - ... - { - "id": "5580", - "phrase": "@twitter.com", - "context": [ - "home", - "notifications", - "public", - "thread" - ], - "whole_word": false, - "expires_at": null, - "irreversible": true - }, - ... -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/filters/:id" title="View a single filter" >}} -{{< api-method-description >}} - -**Returns:** Filter\ -**OAuth:** User token + `read:filters`\ -**Version history:**\ -2.4.3 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Filter returned successfully -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "8449", - "phrase": "test", - "context": [ - "home", - "notifications", - "public", - "thread" - ], - "whole_word": false, - "expires_at": "2019-11-26T09:08:06.254Z", - "irreversible": true -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -Filter ID does not exist, or is not owned by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/filters" title="Create a filter" >}} -{{< api-method-description >}} - -**Returns:** Filter\ -**OAuth:** User token + `write:filters`\ -**Version history:**\ -2.4.3 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="phrase" type="string" required=true >}} -Text to be filtered -{{< endapi-method-parameter >}} -{{< api-method-parameter name="context" type="array" required=true >}} -Array of enumerable strings `home`, `notifications`, `public`, `thread`. At least one context must be specified. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="irreversible" type="boolean" required=false >}} -Should the server irreversibly drop matching entities from home and notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="whole_word" type="boolean" required=false >}} -Consider word boundaries? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="expires_in" type="integer" required=false >}} -Number of seconds from now the filter should expire. Otherwise, null for a filter that doesn't expire. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -The newly-created filter will be returned. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "8449", - "phrase": "test", - "context": [ - "home", - "notifications", - "public", - "thread" - ], - "whole_word": false, - "expires_at": "2019-11-26T09:08:06.254Z", - "irreversible": true -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -If phrase or context are not provided properly -{{< endapi-method-response-example-description >}} - - -{{< tabs >}} -{{< tab title="phrase" >}} -```javascript -{ - "error": "Validation failed: Phrase can't be blank" -} -``` -{{< endtab >}} - -{{< tab title="context" >}} -```javascript -{ - "error": "Validation failed: Context can't be blank, Context None or invalid context supplied" -} -``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="put" host="https://mastodon.example" path="/api/v1/filters/:id" title="Update a filter" >}} -{{< api-method-description >}} - -**Returns:** Filter\ -**OAuth:** User token + `write:filters`\ -**Version history:**\ -2.4.3 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name="id" type="string" required=true >}} -ID of the filter in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="phrase" type="string" required=true >}} -Text to be filtered -{{< endapi-method-parameter >}} -{{< api-method-parameter name="context" type="array" required=true >}} -Array of enumerable strings `home`, `notifications`, `public`, `thread`. At least one context must be specified. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="irreversible" type="boolean" required=false >}} -Should the server irreversibly drop matching entities from home and notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="whole_word" type="boolean" required=false >}} -Consider word boundaries? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="expires_in" type="integer" required=false >}} -Number of seconds from now the filter should expire. Otherwise, null for a filter that doesn't expire. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Filter updated successfully -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "8449", - "phrase": "test", - "context": [ - "home", - "notifications", - "public", - "thread" - ], - "whole_word": false, - "expires_at": null, - "irreversible": true -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -The filter does not exist or is not owned by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -If phrase or context are not provided properly -{{< endapi-method-response-example-description >}} - - -{{< tabs >}} -{{< tab title="phrase" >}} -```javascript -{ - "error": "Validation failed: Phrase can't be blank" -} -``` -{{< endtab >}} - -{{< tab title="context" >}} -```javascript -{ - "error": "Validation failed: Context can't be blank, Context None or invalid context supplied" -} -``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/filters/:id" title="Remove a filter" >}} -{{< api-method-description >}} - -**Returns:** Filter\ -**OAuth:** User token + `write:filters`\ -**Version history:**\ -2.4.3 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name="id" type="string" required=true >}} -ID of the filter in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -The filter has been deleted successfully, so an empty object will be returned. -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -The filter does not exist or is not owned by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/follow_requests.md b/content/en/methods/accounts/follow_requests.md deleted file mode 100644 index f0f0ea80..00000000 --- a/content/en/methods/accounts/follow_requests.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: follow_requests -description: View and manage follow requests. -menu: - docs: - weight: 80 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/follow_requests" title="Pending Follows" >}} -{{< api-method-description >}} - -**Returns:** Array of Account\ -**OAuth:** User token + `read:follows` or `follow`\ -**Version history:**\ -0.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results to return. Defaults to 40. Paginate using the HTTP Link header. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Accounts that are requesting a follow -{{< endapi-method-response-example-description >}} - - -```javascript -Link: ; rel="next", ; rel="prev" - -[ - { - "id": "8889777", - "username": "example", - "acct": "example@social.example", - ... - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/follow_requests/:id/authorize" title="Accept Follow" >}} -{{< api-method-description >}} - -**Returns:** Relationship\ -**OAuth:** User token + `write:follows` or `follow`\ -**Version history:**\ -0.0.0 - added\ -3.0.0 - now returns Relationship instead of nothing - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=false >}} -ID of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Your Relationship with this account should be updated so that you are `followed_by` this account. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "8889777", - "following": false, - "showing_reblogs": false, - "followed_by": true, - "blocking": false, - "blocked_by": false, - "muting": false, - "muting_notifications": false, - "requested": false, - "domain_blocking": false, - "endorsed": false -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -No pending follow request from that user ID -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/follow_requests/:id/reject" title="Reject Follow" >}} -{{< api-method-description >}} - -**Returns:** Relationship\ -**OAuth:** User token + `write:follows` or `follow`\ -**Version history:**\ -0.0.0 - added\ -3.0.0 - now returns Relationship instead of nothing - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=false >}} -ID of the account in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Your Relationship with this Account should be unchanged. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "8889777", - "following": false, - "showing_reblogs": false, - "followed_by": false, - "blocking": false, - "blocked_by": false, - "muting": false, - "muting_notifications": false, - "requested": false, - "domain_blocking": false, - "endorsed": false -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -No pending follow request for that user ID -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/mutes.md b/content/en/methods/accounts/mutes.md deleted file mode 100644 index 4f5b93f8..00000000 --- a/content/en/methods/accounts/mutes.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: mutes -description: 'View your mutes. See also accounts/:id/{mute,unmute}' -menu: - docs: - weight: 30 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/mutes" title="Muted accounts" >}} -{{< api-method-description >}} - -Accounts the user has muted. - -**Returns:** Array of Account\ -**OAuth:** User token + `read:mutes` or `follow`\ -**Version history:**\ -0.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results to return per page. Defaults to 40. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -**Internal parameter.** Use the HTTP Link header for pagination instead. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -**Internal parameter.** Use the HTTP Link header for pagination instead. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Sample response with limit=2. The id of mutes is private, so parse the HTTP `Link` header to find links to next and previous pages. -{{< endapi-method-response-example-description >}} - - -```javascript -Link: ; rel="next", ; rel="prev" - -[ - { - "id": "963076", - "username": "Simia91", - "acct": "Simia91", - "display_name": "", - "locked": false, - "bot": false, - "created_at": "2019-11-07T10:31:17.428Z", - "note": "

", - "url": "https://mastodon.social/@Simia91", - "avatar": "https://files.mastodon.social/accounts/avatars/000/963/076/original/30d3e0502c419cca.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/963/076/original/30d3e0502c419cca.png", - "header": "https://files.mastodon.social/accounts/headers/000/963/076/original/53ba9b1ad4922418.jpg", - "header_static": "https://files.mastodon.social/accounts/headers/000/963/076/original/53ba9b1ad4922418.jpg", - "followers_count": 18, - "following_count": 73, - "statuses_count": 640, - "last_status_at": "2019-11-19T15:14:47.088Z", - "mute_expires_at": null, - "emojis": [], - "fields": [] - }, - { - "id": "1001524", - "username": "hakogamae", - "acct": "hakogamae", - "display_name": "Hakogamae 🔞", - "locked": false, - "bot": false, - "created_at": "2019-11-15T13:01:55.538Z", - "note": "

This blog is going to be about what I don't know -- what's the diff between good for me and not?

I always to make reasonable choices, but I've been wrong many times. Maybe I'll get better by simply working at it slowly.

"If I have the belief that I can do it,
I shall surely acquire the capacity to
do it even if I may not have it at the
beginning." -- Gandhi

My name -- Hakogamae -- comes from the Japanese Kanji Radical 22 匚部 meaning "box." I'm in a box now.

At Humblr, I was Fslowly

", - "url": "https://mastodon.social/@hakogamae", - "avatar": "https://files.mastodon.social/accounts/avatars/001/001/524/original/dd6ab3001057a144.jpg", - "avatar_static": "https://files.mastodon.social/accounts/avatars/001/001/524/original/dd6ab3001057a144.jpg", - "header": "https://files.mastodon.social/accounts/headers/001/001/524/original/09187eeac3fa6d0d.jpg", - "header_static": "https://files.mastodon.social/accounts/headers/001/001/524/original/09187eeac3fa6d0d.jpg", - "followers_count": 23, - "following_count": 0, - "statuses_count": 137, - "last_status_at": "2019-11-21T18:44:25.570Z", - "mute_expires_at": null, - "emojis": [], - "fields": [ - { - "name": "Men", - "value": "living, alive", - "verified_at": null - }, - { - "name": "Carpe diem", - "value": "匚部", - "verified_at": null - }, - { - "name": "Photographs", - "value": "capturing time", - "verified_at": null - }, - { - "name": "Feedback", - "value": "always helps", - "verified_at": null - } - ] - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -If the Authorization header is not provided or contains an invalid token, the request will fail. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/preferences.md b/content/en/methods/accounts/preferences.md deleted file mode 100644 index 8b47d23c..00000000 --- a/content/en/methods/accounts/preferences.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: preferences -description: Preferred common behaviors to be shared across clients. -menu: - docs: - weight: 110 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/preferences" title="View user preferences" >}} -{{< api-method-description >}} - -Preferences defined by the user in their account settings. - -**Returns:** Preferences by key and value\ -**OAuth:** User token + `read:accounts`\ -**Version history:**\ -2.8.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "posting:default:visibility": "public", - "posting:default:sensitive": false, - "posting:default:language": null, - "reading:expand:media": "default", - "reading:expand:spoilers": false -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Incorrect Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/reports.md b/content/en/methods/accounts/reports.md deleted file mode 100644 index a427d79a..00000000 --- a/content/en/methods/accounts/reports.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: reports -description: Report problematic users to your moderators. -menu: - docs: - weight: 70 - parent: methods-accounts ---- - -{{< hint style="warning" >}} - -Responses are not currently documented. -{{< /hint >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/reports" title="File a report" >}} -{{< api-method-description >}} - -**Returns:** Report\ -**OAuth:** User token + `write:reports`\ -**Version history:**\ -1.1 - added\ -2.3.0 - add `forward` parameter - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="account_id" type="string" required=true >}} -ID of the account to report -{{< endapi-method-parameter >}} -{{< api-method-parameter name="status_ids" type="array" required=false >}} -Array of Statuses to attach to the report, for context -{{< endapi-method-parameter >}} -{{< api-method-parameter name="comment" type="string" required=false >}} -Reason for the report \(default max 1000 characters\) -{{< endapi-method-parameter >}} -{{< api-method-parameter name="forward" type="boolean" required=false >}} -If the account is remote, should the report be forwarded to the remote admin? -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/accounts/suggestions.md b/content/en/methods/accounts/suggestions.md deleted file mode 100644 index baf046db..00000000 --- a/content/en/methods/accounts/suggestions.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: suggestions -description: >- - Server-generated suggestions on who to follow, based on previous positive - interactions. -menu: - docs: - weight: 120 - parent: methods-accounts ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/suggestions" title="Follow suggestions" >}} -{{< api-method-description >}} - -Accounts the user has had past positive interactions with, but is not yet following. - -**Returns:** Array of Account\ -**OAuth:** User token + `read`\ -**Version history:**\ -2.4.3 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results to return. Defaults to 40. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Sample call with limit=2 -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "id": "332766", - "username": "kaniini", - "acct": "kaniini@pleroma.site", - "display_name": ":abunhdhappyhop: :abunhdhappy: :abunhdhop: :abunhd: :abunhdhappyhop: :abunhdhappy:", - "locked": false, - "bot": false, - "created_at": "2018-04-18T13:56:23.167Z", - "note": "a friendly #collectivist 🐰

destroyer of bloat @ #pleroma, #pkgconf, #audacious
slayer of techbros
previously #alpinelinux core a few moons ago and #debian much longer ago

she/her", - "url": "https://pleroma.site/users/kaniini", - "avatar": "https://files.mastodon.social/accounts/avatars/000/332/766/original/9fae792e5af298f2.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/332/766/original/9fae792e5af298f2.png", - "header": "https://files.mastodon.social/accounts/headers/000/332/766/original/fe176d8215ec0f36.jpeg", - "header_static": "https://files.mastodon.social/accounts/headers/000/332/766/original/fe176d8215ec0f36.jpeg", - "followers_count": 2442, - "following_count": 473, - "statuses_count": 19533, - "last_status_at": "2019-11-14T01:38:32.193Z", - "emojis": [ - { - "shortcode": "abunhdhappyhop", - "url": "https://files.mastodon.social/custom_emojis/images/000/137/036/original/e102b7869c930411.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/137/036/static/e102b7869c930411.png", - "visible_in_picker": true - }, - { - "shortcode": "abunhdhappy", - "url": "https://files.mastodon.social/custom_emojis/images/000/137/100/original/d47dd4a8a0a85e19.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/137/100/static/d47dd4a8a0a85e19.png", - "visible_in_picker": true - }, - { - "shortcode": "abunhdhop", - "url": "https://files.mastodon.social/custom_emojis/images/000/137/102/original/43fa2536760ea5d4.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/137/102/static/43fa2536760ea5d4.png", - "visible_in_picker": true - }, - { - "shortcode": "abunhd", - "url": "https://files.mastodon.social/custom_emojis/images/000/142/760/original/892a08e7de033e74.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/142/760/static/892a08e7de033e74.png", - "visible_in_picker": true - } - ], - "fields": [] - }, - { - "id": "689455", - "username": "interneteh", - "acct": "interneteh@sunbeam.city", - "display_name": "Sid", - "locked": false, - "bot": false, - "created_at": "2019-01-17T00:10:11.059Z", - "note": "

stay at home dad, painter by commission, sidewalk farmer, editor, socialist organizer, home chef, anxiety ridden, he/him

", - "url": "https://sunbeam.city/@interneteh", - "avatar": "https://files.mastodon.social/accounts/avatars/000/689/455/original/e7a1ba67e373296e.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/689/455/original/e7a1ba67e373296e.png", - "header": "https://files.mastodon.social/accounts/headers/000/689/455/original/2e83fd31bd530745.png", - "header_static": "https://files.mastodon.social/accounts/headers/000/689/455/original/2e83fd31bd530745.png", - "followers_count": 1180, - "following_count": 1707, - "statuses_count": 26320, - "last_status_at": "2019-11-23T04:58:36.907Z", - "emojis": [], - "fields": [] - }, - { - "id": "764276", - "username": "Dee", - "acct": "Dee@fedi.underscore.world", - "display_name": "Dee 🧡", - "locked": false, - "bot": false, - "created_at": "2019-03-15T17:22:26.925Z", - "note": "This instance exists. People tell me I exist, but who knows?


enby :heart_nb: they/them

🌎 Alt: @DeeUnderscore@be.cutewith.me • A bot: @cubeglobe@beeping.town
💬 XMPP: deeunderscore@xmpp.zone
🔗 https://dee.underscore.world/about", - "url": "https://fedi.underscore.world/users/Dee", - "avatar": "https://files.mastodon.social/accounts/avatars/000/764/276/original/86f6bddc26c4b1df.png", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/764/276/original/86f6bddc26c4b1df.png", - "header": "https://files.mastodon.social/accounts/headers/000/764/276/original/c73f0e088c59145c.jpeg", - "header_static": "https://files.mastodon.social/accounts/headers/000/764/276/original/c73f0e088c59145c.jpeg", - "followers_count": 528, - "following_count": 301, - "statuses_count": 15611, - "last_status_at": "2019-11-23T03:30:33.738Z", - "emojis": [ - { - "shortcode": "heart_nb", - "url": "https://files.mastodon.social/custom_emojis/images/000/121/156/original/6eabf6eb2ae69bc9.png", - "static_url": "https://files.mastodon.social/custom_emojis/images/000/121/156/static/6eabf6eb2ae69bc9.png", - "visible_in_picker": true - } - ], - "fields": [] - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Bad Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/suggestions/:account_id" title="Remove a suggestion" >}} -{{< api-method-description >}} - -Remove an account from follow suggestions. - -**Returns:** n/a\ -**OAuth:** User token + `read`\ -**Version history:**\ -2.4.3 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -id of the account in the database to be removed from suggestions -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -A successful call will return an empty object. Note the call will be successful even if the account id provided is invalid or is not a suggested account. -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/admin.md b/content/en/methods/admin.md deleted file mode 100644 index 2bc463b8..00000000 --- a/content/en/methods/admin.md +++ /dev/null @@ -1,598 +0,0 @@ ---- -title: admin -description: Perform moderation actions with accounts and reports. -menu: - docs: - weight: 80 - parent: methods - identifier: methods-admin ---- - -{{< hint style="warning" >}} - -Responses are not currently documented. Exact nature of parameters has not been validated. -{{< /hint >}} - - -## Account methods - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/admin/accounts" title="View accounts by criteria" >}} -{{< api-method-description >}} - -View accounts matching certain criteria for filtering, up to 100 at a time. Pagination may be done with the HTTP Link header in the response. - -**Returns:** Admin::Account\ -**OAuth:** User token + `admin:read:accounts`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="local" type="boolean" required=false >}} -Filter for local accounts? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="remote" type="boolean" required=false >}} -Filter for remote accounts? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="by_domain" type="string" required=false >}} -Filter by the given domain -{{< endapi-method-parameter >}} -{{< api-method-parameter name="active" type="boolean" required=false >}} -Filter for currently active accounts? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="pending" type="boolean" required=false >}} -Filter for currently pending accounts? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="disabled" type="boolean" required=false >}} -Filter for currently disabled accounts? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="silenced" type="boolean" required=false >}} -Filter for currently silenced accounts? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="suspended" type="boolean" required=false >}} -Filter for currently suspended accounts? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="username" type="string" required=false >}} -Username to search for -{{< endapi-method-parameter >}} -{{< api-method-parameter name="display_name" type="string" required=false >}} -Display name to search for -{{< endapi-method-parameter >}} -{{< api-method-parameter name="email" type="string" required=false >}} -Lookup a user with this email -{{< endapi-method-parameter >}} -{{< api-method-parameter name="ip" type="string" required=false >}} -Lookup users by this IP address -{{< endapi-method-parameter >}} -{{< api-method-parameter name="staff" type="boolean" required=false >}} -Filter for staff accounts? -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/admin/accounts/:id" title="View a specific account" >}} -{{< api-method-description >}} - -View admin-level information about the given account. - -**Returns:** Admin::Account\ -**OAuth:** User token + `admin:read:accounts`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the account -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/accounts/:account_id/action" title="Perform an action against an account" >}} -{{< api-method-description >}} - -Perform an action against an account and log this action in the moderation history. - -**Returns:** empty object\ -**OAuth:** User token + `admin:write:accounts`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":account_id" type="string" required=true >}} -ID of the account -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="type" type="string" required=false >}} -Type of action to be taken. Enumerable oneOf: `none` `disable` `silence` `suspend` -{{< endapi-method-parameter >}} -{{< api-method-parameter name="report_id" type="string" required=false >}} -ID of an associated report that caused this action to be taken -{{< endapi-method-parameter >}} -{{< api-method-parameter name="warning_preset_id" type="string" required=false >}} -ID of a preset warning -{{< endapi-method-parameter >}} -{{< api-method-parameter name="text" type="string" required=false >}} -Additional text for clarification of why this action was taken -{{< endapi-method-parameter >}} -{{< api-method-parameter name="send_email_notification" type="boolean" required=false >}} -Whether an email should be sent to the user with the above information. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/accounts/:id/approve" title="Approve pending account" >}} -{{< api-method-description >}} - -Approve the given local account if it is currently pending approval. - -**Returns:** Admin::Account\ -**OAuth:** User token + `admin:write:accounts`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the account -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/accounts/:id/reject" title="Reject pending account" >}} -{{< api-method-description >}} - -Reject the given local account if it is currently pending approval. - -**Returns:** Admin::Account\ -**OAuth:** User token + `admin:write:accounts`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the account -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/accounts/:id/enable" title="Re-enable account" >}} -{{< api-method-description >}} - -Re-enable a local account whose login is currently disabled. - -**Returns:** Admin::Account\ -**OAuth:** User token + `admin:write:accounts`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the account -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/accounts/:id/unsilence" title="Unsilence account" >}} -{{< api-method-description >}} - -Unsilence a currently silenced account. - -**Returns:** Admin::Account\ -**OAuth:** User token + `admin:write:accounts`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the account -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/accounts/:id/unsuspend" title="Unsuspend account" >}} -{{< api-method-description >}} - -Unsuspend a currently suspended account. - -**Returns:** Admin::Account\ -**OAuth:** User token + `admin:write:accounts`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the account -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - -## Report methods - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/admin/reports" title="View all reports" >}} -{{< api-method-description >}} - -View all reports. Pagination may be done with HTTP Link header in the response. - -**Returns:** Array of Admin::Report\ -**OAuth:** User token + `admin:read:reports`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="resolved" type="boolean" required=false >}} -{{< endapi-method-parameter >}} -{{< api-method-parameter name="account_id" type="string" required=false >}} -{{< endapi-method-parameter >}} -{{< api-method-parameter name="target_account_id" type="string" required=false >}} -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/admin/reports/:id/" title="View a single report" >}} -{{< api-method-description >}} - -View information about the report with the given ID. - -**Returns:** Admin::Report\ -**OAuth:** User token + `admin:read:reports`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the report -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/reports/:id/assign_to_self" title="Assign report to self" >}} -{{< api-method-description >}} - -Claim the handling of this report to yourself. - -**Returns:** Admin::Report\ -**OAuth:** User token + `admin:write:reports`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the report -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/reports/:id/unassign" title="Unassign report" >}} -{{< api-method-description >}} - -Unassign a report so that someone else can claim it. - -**Returns:** Admin::Report\ -**OAuth:** User token + `admin:write:reports`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the report -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/reports/:id/resolve" title="Mark as resolved" >}} -{{< api-method-description >}} - -Mark a report as resolved with no further action taken. - -**Returns:** Admin::Report\ -**OAuth:** User token + `admin:write:reports`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the report -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/admin/reports/:id/reopen" title="Re-open report" >}} -{{< api-method-description >}} - -Reopen a currently closed report. - -**Returns:** Admin::Report\ -**OAuth:** User token + `admin:write:reports`\ -**Version history:**\ -2.9.1 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the report -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -``` - -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/admin/_index.md b/content/en/methods/admin/_index.md new file mode 100644 index 00000000..a21e1cfc --- /dev/null +++ b/content/en/methods/admin/_index.md @@ -0,0 +1,10 @@ +--- +title: admin API methods +description: View and manage administrative information. +menu: + docs: + weight: 80 + name: admin + parent: methods + identifier: methods-admin +--- \ No newline at end of file diff --git a/content/en/methods/admin/accounts.md b/content/en/methods/admin/accounts.md new file mode 100644 index 00000000..57b366d8 --- /dev/null +++ b/content/en/methods/admin/accounts.md @@ -0,0 +1,1035 @@ +--- +title: admin/accounts API methods +description: Perform moderation actions with accounts. +menu: + docs: + name: admin/accounts + parent: methods-admin + identifier: methods-admin-accounts +aliases: [ + "/methods/admin/accounts", + "/api/methods/admin/accounts", +] +--- + + + +## View accounts (v1) {#v1} + +```http +GET https://mastodon.example/api/v1/admin/accounts HTTP/1.1 +``` + +View all accounts, optionally matching certain criteria for filtering, up to 100 at a time. Pagination may be done with the HTTP Link header in the response. See [Paginating through API responses]({{}}) for more information. + +**Returns:** Array of [Admin::Account]({{}})\ +**OAuth:** User token + `admin:read:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +2.9.1 - added\ +3.3.0 - added `sensitized`\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +local +: Boolean. Filter for local accounts? + +remote +: Boolean. Filter for remote accounts? + +active +: Boolean. Filter for currently active accounts? + +pending +: Boolean. Filter for currently pending accounts? + +disabled +: Boolean. Filter for currently disabled accounts? + +silenced +: Boolean. Filter for currently silenced accounts? + +suspended +: Boolean. Filter for currently suspended accounts? + +sensitized +: Boolean. Filter for accounts force-marked as sensitive? + +username +: String. Search for the given username + +display_name +: String. Search for the given display name + +by_domain +: String. Filter by the given domain + +email +: String. Lookup a user with this email + +ip +: String. Lookup users with this IP address + +staff +: Boolean. Filter for staff accounts? + +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 100. + +#### Response +##### 200: OK + +```json +[ + { + "id": "108267707882207829", + "username": "trwnh", + "domain": null, + "created_at": "2022-05-08T18:21:56.870Z", + "email": "trwnh@mastodon.local", + "ip": { + "user_id": 2, + "ip": "192.168.42.1", + "used_at": "2022-05-08T18:21:56.944Z" + }, + "role": "user", + "confirmed": false, + "suspended": false, + "silenced": false, + "disabled": false, + "approved": true, + "locale": "en", + "invite_request": null, + "ips": [ + { + "ip": "192.168.42.1", + "used_at": "2022-05-08T18:21:56.944Z" + } + ], + "account": { + "id": "108267707882207829", + "username": "trwnh", + "acct": "trwnh", + // ... + } + }, + { + "id": "108267695853695427", + "username": "admin", + "domain": null, + "created_at": "2022-05-08T18:18:53.221Z", + "email": "admin@mastodon.local", + "ip": { + "user_id": 1, + "ip": "192.168.42.1", + "used_at": "2022-09-08T16:10:38.621Z" + }, + "role": "admin", + "confirmed": true, + "suspended": false, + "silenced": false, + "disabled": false, + "approved": true, + "locale": null, + "invite_request": null, + "ips": [ + { + "ip": "192.168.42.1", + "used_at": "2022-09-08T16:10:38.621Z" + } + ], + "account": { + "id": "108267695853695427", + "username": "admin", + "acct": "admin", + // ... + } + } +] +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## View accounts (v2) {#v2} + +```http +GET https://mastodon.example/api/v2/admin/accounts HTTP/1.1 +``` + +View all accounts, optionally matching certain criteria for filtering, up to 100 at a time. Pagination may be done with the HTTP Link header in the response. See [Paginating through API responses]({{}}) for more information. + +**Returns:** Array of [Admin::Account]({{}})\ +**OAuth:** User token + `admin:read:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +3.5.0 - added\ +4.0.0 - added `role_ids`. Support custom roles and permissions + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +origin +: String. Filter for `local` or `remote` accounts. + +status +: String. Filter for `active`, `pending`, `disabled`, `silenced`, or `suspended` accounts. + +permissions +: String. Filter for accounts with `staff` permissions (users that can manage reports). + +role_ids +: String. Filter for users with these roles. + +invited_by +: String. Lookup users invited by the account with this ID. + +username +: String. Search for the given username. + +display_name +: String. Search for the given display name. + +by_domain +: String. Filter by the given domain. + +email +: String. Lookup a user with this email. + +ip +: String. Lookup users with this IP address. + +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 100. + +#### Response +##### 200: OK + +```json +[ + { + "id": "108267695853695427", + "username": "admin", + "domain": null, + "created_at": "2022-05-08T18:18:53.221Z", + "email": "admin@mastodon.local", + "ip": { + "user_id": 1, + "ip": "192.168.42.1", + "used_at": "2022-09-08T16:10:38.621Z" + }, + "role": { + "id": 3, + "name": "Owner", + "color": "#3584e4", + "position": 1000, + "permissions": 1, + "highlighted": true, + "created_at": "2022-09-08T22:48:07.983Z", + "updated_at": "2022-09-09T10:45:13.226Z" + }, + "confirmed": true, + "suspended": false, + "silenced": false, + "disabled": false, + "approved": true, + "locale": null, + "invite_request": null, + "ips": [ + { + "ip": "192.168.42.1", + "used_at": "2022-09-08T16:10:38.621Z" + } + ], + "account": { + "id": "108267695853695427", + "username": "admin", + "acct": "admin", + // ... + } + } +] +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## View a specific account {#get-one} + +```http +GET https://mastodon.example/api/v1/admin/accounts/:id HTTP/1.1 +``` + +View admin-level information about the given account. + +**Returns:** [Admin::Account]({{}})\ +**OAuth:** User token + `admin:read:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "108267695853695427", + "username": "admin", + "domain": null, + "created_at": "2022-05-08T18:18:53.221Z", + "email": "admin@mastodon.local", + "ip": { + "user_id": 1, + "ip": "192.168.42.1", + "used_at": "2022-09-08T16:10:38.621Z" + }, + "role": { + "id": 3, + "name": "Owner", + "color": "", + "position": 1000, + "permissions": 1, + "highlighted": true, + "created_at": "2022-09-08T22:48:07.983Z", + "updated_at": "2022-09-08T22:48:07.983Z" + }, + "confirmed": true, + "suspended": false, + "silenced": false, + "disabled": false, + "approved": true, + "locale": null, + "invite_request": null, + "ips": [ + { + "ip": "192.168.42.1", + "used_at": "2022-09-08T16:10:38.621Z" + } + ], + "account": { + "id": "108267695853695427", + "username": "admin", + "acct": "admin", + // ... + } +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +Account does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Approve a pending account {#approve} + +```http +POST https://mastodon.example/api/v1/admin/accounts/:id/approve HTTP/1.1 +``` + +Approve the given local account if it is currently pending approval. + +**Returns:** [Admin::Account]({{}})\ +**OAuth:** User token + `admin:write:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The account is now approved + +```json +{ + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + // ... + "approved": true, + // ... +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header, or account is currently not pending. + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +Account does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Reject a pending account {#reject} + +```http +POST https://mastodon.example/api/v1/admin/accounts/:id/reject HTTP/1.1 +``` + +Reject the given local account if it is currently pending approval. + +**Returns:** [Admin::Account]({{}})\ +**OAuth:** User token + `admin:write:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "108965436418975594", + "username": "badguy", + "domain": null, + "created_at": "2022-09-08T23:43:29.427Z", + "email": "badguy@mastodon.local", + "ip": null, + "role": { + "id": -99, + "name": "", + "color": "", + "position": -1, + "permissions": 65536, + "highlighted": false, + "created_at": "2022-09-08T22:48:07.977Z", + "updated_at": "2022-09-08T22:48:07.977Z" + }, + "confirmed": true, + "suspended": false, + "silenced": false, + "disabled": false, + "approved": false, + "locale": "en", + "invite_request": "i am going to commit crimes", + "ips": [], + "account": { + "id": "108965436418975594", + "username": "badguy", + "acct": "badguy", + "display_name": "", + "locked": false, + "bot": false, + "discoverable": null, + "group": false, + "created_at": "2022-09-08T00:00:00.000Z", + "note": "", + "url": "http://mastodon.local/@badguy", + "avatar": "http://mastodon.local/avatars/original/missing.png", + "avatar_static": "http://mastodon.local/avatars/original/missing.png", + "header": "http://mastodon.local/headers/original/missing.png", + "header_static": "http://mastodon.local/headers/original/missing.png", + "followers_count": 0, + "following_count": 0, + "statuses_count": 0, + "last_status_at": null, + "emojis": [], + "fields": [] + } +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header, or the account is not currently pending. + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +Account does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Delete an account {#delete} + +```http +DELETE https://mastodon.example/api/v1/admin/accounts/:id HTTP/1.1 +``` + +Permanently delete data for a suspended account. + +**Returns:** [Admin::Account]({{}})\ +**OAuth:** User token + `admin:write:accounts`\ +**Permissions:** Delete User Data\ +**Version history:**\ +3.3.0 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The account's data has been deleted. + +```json +{ + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + "email": "goody@mastodon.local", + "ip": { + "user_id": 3, + "ip": "192.168.42.1", + "used_at": "2022-09-08T23:42:04.761Z" + }, + "role": { + "id": -99, + "name": "", + "color": "", + "position": -1, + "permissions": 65536, + "highlighted": false, + "created_at": "2022-09-08T22:48:07.977Z", + "updated_at": "2022-09-08T22:48:07.977Z" + }, + "confirmed": true, + "suspended": true, + "silenced": false, + "disabled": false, + "approved": true, + "locale": "en", + "invite_request": "this is a compelling reason", + "ips": [ + { + "ip": "192.168.42.1", + "used_at": "2022-09-08T23:42:04.761Z" + } + ], + "account": { + "id": "108965430868193066", + "username": "goody", + "acct": "goody", + "display_name": "", + "locked": false, + "bot": false, + "discoverable": false, + "group": false, + "created_at": "2022-09-08T00:00:00.000Z", + "note": "", + "url": "http://mastodon.local/@goody", + "avatar": "http://mastodon.local/avatars/original/missing.png", + "avatar_static": "http://mastodon.local/avatars/original/missing.png", + "header": "http://mastodon.local/headers/original/missing.png", + "header_static": "http://mastodon.local/headers/original/missing.png", + "followers_count": 0, + "following_count": 0, + "statuses_count": 0, + "last_status_at": null, + "suspended": true, + "emojis": [], + "fields": [] + } +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header, or account was already deleted. + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Perform an action against an account {#action} + +```http +POST https://mastodon.example/api/v1/admin/accounts/:id/action HTTP/1.1 +``` + +Perform an action against an account and log this action in the moderation history. Also resolves any open reports against this account. + +**Returns:** empty object\ +**OAuth:** User token + `admin:write:accounts`\ +**Permissions:** Manage Users, Manage Reports\ +**Version history:**\ +2.9.1 - added\ +3.3.0 - add `sensitive` as a possible `type`\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +type +: {{}} String. The type of action to be taken: `none`, `sensitive`, `disable`, `silence`, or `suspend`. + +report_id +: String. The ID of an associated report that caused this action to be taken. + +warning_preset_id +: String. The ID of a preset warning. + +text +: String. Additional clarification for why this action was taken. + +send_email_notification +: Boolean. Should an email be sent to the user with the above information? + +#### Response +##### 200: OK + +The action was successfully taken + +```json +{} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +Account or Report with given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Server error + +`type` is not provided or is not understood + +```json +{ + "error": "Record invalid" +} +``` + +--- + +## Enable a currently disabled account {#enable} + +```http +POST https://mastodon.example/api/v1/admin/accounts/:id/enable HTTP/1.1 +``` + +Re-enable a local account whose login is currently disabled. + +**Returns:** [Admin::Account]({{}})\ +**OAuth:** User token + `admin:write:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Account was enabled, or was already enabled. + +```json +{ + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + // ... + "disabled": false, + // ... +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +Account does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Unsilence an account {#unsilence} + +```http +POST https://mastodon.example/api/v1/admin/accounts/:id/unsilence HTTP/1.1 +``` + +Unsilence an account if it is currently silenced. + +**Returns:** [Admin::Account]({{}})\ +**OAuth:** User token + `admin:write:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Account was unsilenced, or was already not silenced + +```json +{ + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + // ... + "silenced": false, + // ... +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +Account does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Unsuspend an account {#unsuspend} + +```http +POST https://mastodon.example/api/v1/admin/accounts/:id/unsuspend HTTP/1.1 +``` + +Unsuspend a currently suspended account. + +**Returns:** [Admin::Account]({{}})\ +**OAuth:** User token + `admin:write:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Account successfully unsuspended + +```json +{ + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + // ... + "suspended": false, + // ... +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header, or Account is not currently suspended + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +Account does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Unmark an account as sensitive {#unsensitive} + +```http +POST https://mastodon.example/api/v1/admin/accounts/:id/unsensitive HTTP/1.1 +``` + +Stops marking an account's posts as sensitive, if it was previously flagged as sensitive. + +**Returns:** [Admin::Account]({{}})\ +**OAuth:** User token + `admin:write:accounts`\ +**Permissions:** Manage Users\ +**Version history:**\ +3.3.0 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The account is no longer marked as sensitive, or was already not marked as sensitive. + +```json +{ + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + // ... + "sensitized": false, + // ... +} +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +Account does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/accounts_controller.rb" caption="app/controllers/api/v1/admin/accounts_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/account_actions_controller.rb" caption="app/controllers/api/v1/admin/account_actions_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/admin/canonical_email_blocks.md b/content/en/methods/admin/canonical_email_blocks.md new file mode 100644 index 00000000..833b348a --- /dev/null +++ b/content/en/methods/admin/canonical_email_blocks.md @@ -0,0 +1,238 @@ +--- +title: canonical_email_blocks API methods +description: Block certain email addresses by their hash. +menu: + docs: + name: canonical_email_blocks + parent: methods-admin + identifier: methods-admin-canonical_email_blocks +aliases: [ + "/methods/admin/canonical_email_blocks", + "/api/methods/admin/canonical_email_blocks", +] +--- + + + +{{< hint style="danger" >}} +This page is under construction. +{{< /hint >}} + +## List all canonical email blocks {#get} + +```http +GET https://mastodon.example/api/v1/admin/canonical_email_blocks HTTP/1.1 +``` + +**Returns:** Array of [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\ +**OAuth:** User token + `admin:read:canonical_email_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 100. + +#### Response +##### 200: OK + + + +```json +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Show a single canonical email block {#get-one} + +```http +GET https://mastodon.example/api/v1/admin/canonical_email_blocks/:id HTTP/1.1 +``` + +**Returns:** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\ +**OAuth:** User token + `admin:read:canonical_email_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + + + +```json +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Test {#test} + +```http +POST https://mastodon.example/api/v1/admin/canonical_email_blocks/test HTTP/1.1 +``` + +**Returns:** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\ +**OAuth:** User token + `admin:read:canonical_email_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +parameter +: TODO: + +#### Response +##### 200: OK + + + +```json +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Block a canonical email {#create} + +```http +POST https://mastodon.example/api/v1/admin/canonical_email_blocks HTTP/1.1 +``` + +**Returns:** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\ +**OAuth:** User token + `admin:write:canonical_email_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +email +: TODO: + +canonical_email_hash +: TODO: + +#### Response +##### 200: OK + + + +```json +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Delete a canonical email block {#delete} + +```http +DELETE https://mastodon.example/api/v1/admin/canonical_email_blocks/:id HTTP/1.1 +``` + +**Returns:** [Admin::CanonicalEmailBlock]({{< relref "entities/Admin_CanonicalEmailBlock" >}})\ +**OAuth:** User token + `admin:write:canonical_email_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + + + +```json +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/canonical_email_blocks_controller.rb" caption="app/controllers/api/v1/admin/canonical_email_blocks_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/admin/dimensions.md b/content/en/methods/admin/dimensions.md new file mode 100644 index 00000000..a4587e4f --- /dev/null +++ b/content/en/methods/admin/dimensions.md @@ -0,0 +1,258 @@ +--- +title: dimensions API methods +description: Obtain qualitative metrics about the server. +menu: + docs: + name: dimensions + parent: methods-admin + identifier: methods-admin-dimensions +aliases: [ + "/methods/admin/dimensions", + "/api/methods/admin/dimensions", +] +--- + + + +## Get dimensional data {#get} + +```http +POST https://mastodon.example/api/v1/admin/dimensions HTTP/1.1 +``` + +Obtain information about popularity of certain accounts, servers, languages, etc. + +**Returns:** Array of [Admin::Dimension]({{< relref "entities/Admin_Dimension" >}})\ +**OAuth:** User token + `admin:read`\ +**Permissions:** View Dashboard\ +**Version history:**\ +3.5.0 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +keys[] +: {{}} Array of String. Request specific dimensions by their keystring. Supported dimensions include: +- `languages` = Most-used languages on this server +- `sources` = Most-used client apps on this server +- `servers` = Remote servers with the most statuses +- `space_usage` = How much space is used by your software stack +- `software_versions` = The version numbers for your software stack +- `tag_servers` = Most-common servers for statuses including a trending tag +- `tag_languages` = Most-used languages for statuses including a trending tag +- `instance_accounts` = Most-followed accounts from a remote server +- `instance_languages` = Most-used languages from a remote server + +start_at +: String (ISO 8601 Datetime). The start date for the time period. If a time is provided, it will be ignored. + +end_at +: String (ISO 8601 Datetime). The end date for the time period. If a time is provided, it will be ignored. + +limit +: Integer. The maximum number of results to return for sources, servers, languages, tag or instance dimensions. + +tag_servers[id] +: String. When `tag_servers` is one of the requested keys, you must provide a trending tag ID to obtain information about which servers are posting the tag. + +tag_languages[id] +: String. When `tag_languages` is one of the requested keys, you must provide a trending tag ID to obtain information about which languages are posting the tag. + +instance_accounts[domain] +: String. When `instance_accounts` is one of the requested keys, you must provide a domain to obtain information about popular accounts from that server. + +instance_languages[domain] +: String. When `instance_accounts` is one of the requested keys, you must provide a domain to obtain information about popular languages from that server. + +#### Response + +##### 200: OK + +Requesting data on mastodon.social and a given trending tag with a limit of 2. + +```json +[ + { + "key": "languages", + "data": [ + { + "key": "en", + "human_key": "English", + "value": "10" + }, + { + "key": "es", + "human_key": "Spanish", + "value": "1" + } + ] + }, + { + "key": "sources", + "data": [ + { + "key": "web", + "human_key": "Website", + "value": "3" + } + ] + }, + { + "key": "servers", + "data": [ + { + "key": "botsin.space", + "human_key": "botsin.space", + "value": "13738" + }, + { + "key": "monads.online", + "human_key": "monads.online", + "value": "8928" + } + ] + }, + { + "key": "space_usage", + "data": [ + { + "key": "postgresql", + "human_key": "PostgreSQL", + "value": "49581359907", + "unit": "bytes", + "human_value": "46.2 GB" + }, + { + "key": "redis", + "human_key": "Redis", + "value": "100765744", + "unit": "bytes", + "human_value": "96.1 MB" + }, + { + "key": "media", + "human_key": "Media storage", + "value": "837837315424", + "unit": "bytes", + "human_value": "780 GB" + } + ] + }, + { + "key": "software_versions", + "data": [ + { + "key": "mastodon", + "human_key": "Mastodon", + "value": "3.5.1+chitter", + "human_value": "3.5.1+chitter" + }, + { + "key": "ruby", + "human_key": "Ruby", + "value": "3.0.3p157", + "human_value": "3.0.3p157" + }, + { + "key": "postgresql", + "human_key": "PostgreSQL", + "value": "14.3", + "human_value": "14.3" + }, + { + "key": "redis", + "human_key": "Redis", + "value": "6.2.7", + "human_value": "6.2.7" + } + ] + }, + { + "key": "instance_languages", + "data": [ + { + "key": "en", + "human_key": "English", + "value": "5848" + }, + { + "key": "de", + "human_key": "German", + "value": "155" + } + ] + }, + { + "key": "instance_accounts", + "data": [ + { + "key": "fribbledom", + "human_key": "fribbledom", + "value": "33" + }, + { + "key": "ShugoWah", + "human_key": "ShugoWah", + "value": "26" + } + ] + }, + { + "key": "tag_servers", + "data": [ + { + "key": "live.hatnix.net", + "human_key": "live.hatnix.net", + "value": "6" + }, + { + "key": "linuxrocks.online", + "human_key": "linuxrocks.online", + "value": "4" + } + ] + }, + { + "key": "tag_languages", + "data": [ + { + "key": "und", + "human_key": "und", + "value": "8" + }, + { + "key": "en", + "human_key": "English", + "value": "7" + } + ] + } +] +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/dimensions_controller.rb" caption="app/controllers/api/v1/admin/dimensions_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension.rb" caption="app/lib/admin/metrics/dimension.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/dimension/" caption="app/lib/admin/metrics/dimension/" >}} \ No newline at end of file diff --git a/content/en/methods/admin/domain_allows.md b/content/en/methods/admin/domain_allows.md new file mode 100644 index 00000000..d4f05dde --- /dev/null +++ b/content/en/methods/admin/domain_allows.md @@ -0,0 +1,255 @@ +--- +title: domain_allows API methods +description: Allow certain domains to federate. +menu: + docs: + name: domain_allows + parent: methods-admin + identifier: methods-admin-domain_allows +aliases: [ + "/methods/admin/domain_allows", + "/api/methods/admin/domain_allows", +] +--- + + + +## List all allowed domains {#get} + +```http +GET https://mastodon.example/api/v1/admin/domain_allows HTTP/1.1 +``` + +Show information about all allowed domains. + +**Returns:** Array of [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})\ +**OAuth:** User token + `admin:read:domain_allows`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 100. + +#### Response + +##### 200: OK + +```json +[ + { + "id": "2", + "domain": "mastodon", + "created_at": "2022-09-14T21:24:15.360Z" + }, + { + "id": "1", + "domain": "mastodon.social", + "created_at": "2022-09-14T21:23:02.755Z" + } +] +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Get a single allowed domain {#get-one} + +```http +GET https://mastodon.example/api/v1/admin/domain_allows/:id HTTP/1.1 +``` +Show information about a single allowed domain. + +**Returns:** [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})\ +**OAuth:** User token + `admin:read:domain_allows`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +##### Path parameters + +:id +: {{}} String. The ID of the DomainAllow in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "1", + "domain": "mastodon.social", + "created_at": "2022-09-14T21:23:02.755Z" +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +DomainAllow with the given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Allow a domain to federate {#create} + +```http +POST https://mastodon.example/api/v1/admin/domain_allows HTTP/1.1 +``` + +Add a domain to the list of domains allowed to federate, to be used when the instance is in allow-list federation mode. + +**Returns:** [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})\ +**OAuth:** User token + `admin:write:domain_allows`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +domain +: {{}} String. The domain to allow federation with. + +#### Response +##### 200: OK + +Domain has been allowed to federate, or was already allowed to federate + +```json +{ + "id": "1", + "domain": "mastodon.social", + "created_at": "2022-09-14T21:23:02.755Z" +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity + +The domain parameter was not provided or was invalid + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +--- + +## Delete an allowed domain {#delete} + +```http +DELETE https://mastodon.example/api/v1/admin/domain_allows/:id HTTP/1.1 +``` + +Delete a domain from the allowed domains list. + +**Returns:** [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})\ +**OAuth:** User token + `admin:write:domain_allows`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the DomainAllow in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The allowed domain has been removed from the allow list + +```json +{ + "id": "4", + "domain": "*", + "created_at": "2022-09-14T21:32:44.945Z" +} +``` +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +DomainAllow with the given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/domain_allows_controller.rb" caption="app/controllers/api/v1/admin/domain_allows_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/admin/domain_blocks.md b/content/en/methods/admin/domain_blocks.md new file mode 100644 index 00000000..06c2cc08 --- /dev/null +++ b/content/en/methods/admin/domain_blocks.md @@ -0,0 +1,368 @@ +--- +title: admin/domain_blocks API methods +description: Disallow certain domains to federate. +menu: + docs: + name: admin/domain_blocks + parent: methods-admin + identifier: methods-admin-domain_blocks +aliases: [ + "/methods/admin/domain_blocks", + "/api/methods/admin/domain_blocks", +] +--- + + + +{{< hint style="danger" >}} +This page is under construction. +{{< /hint >}} + +## List all blocked domains {#get} + +```http +GET https://mastodon.example/api/v1/admin/domain_blocks HTTP/1.1 +``` + +Show information about all blocked domains. + +**Returns:** Array of [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth:** User token + `admin:read:domain_blocks`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 100. + +#### Response + +##### 200: OK + +```json +[ + { + "id": "1", + "domain": "example.com", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false + }, + // ... +] +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Get a single blocked domain {#get-one} + +```http +GET https://mastodon.example/api/v1/admin/domain_blocks/:id HTTP/1.1 +``` +Show information about a single blocked domain. + +**Returns:** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth:** User token + `admin:read:domain_blocks`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +##### Path parameters + +:id +: {{}} String. The ID of the DomainBlock in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "1", + "domain": "example.com", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +DomainBlock with the given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Block a domain from federating {#create} + +```http +POST https://mastodon.example/api/v1/admin/domain_blocks HTTP/1.1 +``` + +Add a domain to the list of domains blocked from federating. + +**Returns:** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth:** User token + `admin:write:domain_blocks`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +domain +: {{}} String. The domain to block federation with. + +severity +: String. Whether to apply a `silence`, `suspend`, or `noop` to the domain. Defaults to `silence` + +reject_media +: Boolean. Whether media attachments should be rejected. Defaults to false + +reject_reports +: Boolean. Whether reports from this domain should be rejected. Defaults to false + +private_comment +: String. A private note about this domain block, visible only to admins. + +public_comment +: String. A public note about this domain block, optionally shown on the about page. + +obfuscate +: Boolean. Whether to partially censor the domain when shown in public. Defaults to false + +#### Response +##### 200: OK + +Domain has been blocked from federating. + +```json +{ + "id": "1", + "domain": "example.com", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity + +The domain parameter was not provided + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +--- + +## Update a domain block {#update} + +```http +PUT https://mastodon.example/api/v1/admin/domain_blocks/:id HTTP/1.1 +``` + +Change parameters for an existing domain block. + +**Returns:** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth:** User token + `admin:write:domain_blocks`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the DomainAllow in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +severity +: String. Whether to apply a `silence`, `suspend`, or `noop` to the domain. Defaults to `silence` + +reject_media +: Boolean. Whether media attachments should be rejected. Defaults to false + +reject_reports +: Boolean. Whether reports from this domain should be rejected. Defaults to false + +private_comment +: String. A private note about this domain block, visible only to admins. + +public_comment +: String. A public note about this domain block, optionally shown on the about page. + +obfuscate +: Boolean. Whether to partially censor the domain when shown in public. Defaults to false + +#### Response +##### 200: OK + +Domain block has been updated + +```json +{ + "id": "1", + "domain": "example.com", + "created_at": "2022-11-16T08:15:34.238Z", + "severity": "noop", + "reject_media": false, + "reject_reports": false, + "private_comment": null, + "public_comment": null, + "obfuscate": false +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 500: Server error + +Invalid severity + +--- + +## Remove a domain block {#delete} + +```http +DELETE https://mastodon.example/api/v1/admin/domain_blocks/:id HTTP/1.1 +``` + +Lift a block against a domain. + +**Returns:** [Admin::DomainBlock]({{< relref "entities/Admin_DomainBlock" >}})\ +**OAuth:** User token + `admin:write:domain_blocks`\ +**Permissions:** Manage Federation\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the DomainAllow in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The domain has been removed from the block list + +```json +{} +``` +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +DomainBlock with the given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/domain_blocks_controller.rb" caption="app/controllers/api/v1/admin/domain_blocks_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/admin/email_domain_blocks.md b/content/en/methods/admin/email_domain_blocks.md new file mode 100644 index 00000000..438274e9 --- /dev/null +++ b/content/en/methods/admin/email_domain_blocks.md @@ -0,0 +1,370 @@ +--- +title: email_domain_blocks API methods +description: Disallow certain email domains from signing up. +menu: + docs: + name: email_domain_blocks + parent: methods-admin + identifier: methods-admin-email_domain_blocks +aliases: [ + "/methods/admin/email_domain_blocks", + "/api/methods/admin/email_domain_blocks", +] +--- + + + +{{< hint style="danger" >}} +This page is under construction. +{{< /hint >}} + +## List all blocked email domains {#get} + +```http +GET https://mastodon.example/api/v1/admin/email_domain_blocks HTTP/1.1 +``` + +Show information about all email domains blocked from signing up. + +**Returns:** Array of [Admin::EmailDomainBlock]({{< relref "entities/Admin_EmailDomainBlock" >}})\ +**OAuth:** User token + `admin:read:email_domain_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 100. + +#### Response + +##### 200: OK + +```json +[ + { + "id": "1", + "domain": "foo", + "created_at": "2022-11-16T06:09:36.176Z", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ] + }, + // ... +] +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Get a single blocked email domain {#get-one} + +```http +GET https://mastodon.example/api/v1/admin/email_domain_blocks/:id HTTP/1.1 +``` +Show information about a single email domain that is blocked from signups. + +**Returns:** [Admin::EmailDomainBlock]({{< relref "entities/Admin_EmailDomainBlock" >}})\ +**OAuth:** User token + `admin:read:email_domain_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.3 - added + +##### Path parameters + +:id +: {{}} String. The ID of the DomainBlock in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "1", + "domain": "foo", + "created_at": "2022-11-16T06:09:36.176Z", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ] +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +EmailDomainBlock with the given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Block an email domain from signups {#create} + +```http +POST https://mastodon.example/api/v1/admin/email_domain_blocks HTTP/1.1 +``` + +Add a domain to the list of email domains blocked from signups. + +**Returns:** [Admin::EmailDomainBlock]({{< relref "entities/Admin_EmailDomainBlock" >}})\ +**OAuth:** User token + `admin:write:email_domain_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +domain +: {{}} String. The domain to block federation with. + +#### Response +##### 200: OK + +Email domain has been blocked from signups. + +```json +{ + "id": "1", + "domain": "foo", + "created_at": "2022-11-16T06:09:36.176Z", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ] +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity + +The domain parameter was not provided + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +Alternatively, the domain provided contains an invalid character + +```json +{ + "error": "Validation failed: Domain is invalid, Domain is not a valid domain name" +} +``` + +--- + +## Delete an email domain block {#delete} + +```http +DELETE https://mastodon.example/api/v1/admin/email_domain_blocks/:id HTTP/1.1 +``` + +Lift a block against an email domain. + +**Returns:** [Admin::EmailDomainBlock]({{< relref "entities/Admin_EmailDomainBlock" >}})\ +**OAuth:** User token + `admin:write:email_domain_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the DomainAllow in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The email domain has been removed from the block list + +```json +{} +``` +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +EmailDomainBlock with the given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/email_domain_blocks_controller.rb" caption="app/controllers/api/v1/admin/email_domain_blocks_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/admin/ip_blocks.md b/content/en/methods/admin/ip_blocks.md new file mode 100644 index 00000000..4d306dbe --- /dev/null +++ b/content/en/methods/admin/ip_blocks.md @@ -0,0 +1,338 @@ +--- +title: ip_blocks API methods +description: Disallow certain IP address ranges from signing up. +menu: + docs: + name: ip_blocks + parent: methods-admin + identifier: methods-admin-ip_blocks +aliases: [ + "/methods/admin/domain_blocks", + "/api/methods/admin/domain_blocks", +] +--- + + + +{{< hint style="danger" >}} +This page is under construction. +{{< /hint >}} + +## List all IP blocks {#get} + +```http +GET https://mastodon.example/api/v1/admin/ip_blocks HTTP/1.1 +``` + +Show information about all blocked IP ranges. + +**Returns:** Array of [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth:** User token + `admin:read:ip_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 100. + +#### Response + +##### 200: OK + +```json +[ + { + "id": "1", + "ip": "8.8.8.8/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null + }, + // ... +] +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Get a single IP block {#get-one} + +```http +GET https://mastodon.example/api/v1/admin/ip_blocks/:id HTTP/1.1 +``` + +Show information about a single IP block. + +**Returns:** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth:** User token + `admin:read:ip_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +##### Path parameters + +:id +: {{}} String. The ID of the IpBlock in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "1", + "ip": "8.8.8.8/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +IpBlock with the given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Block an IP address range from signing up {#create} + +```http +POST https://mastodon.example/api/v1/admin/ip_blocks HTTP/1.1 +``` + +Add an IP address range to the list of IP blocks. + +**Returns:** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth:** User token + `admin:write:ip_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +ip +: String. The IP address and prefix to block. Defaults to `0.0.0.0/32` + +severity +: {{}} String. The policy to apply to this IP range: `sign_up_requires_approval`, `sign_up_block`, or `no_access` + +comment +: String. The reason for this IP block. + +expires_in +: Integer. The number of seconds in which this IP block will expire. + +#### Response +##### 200: OK + +IP has been blocked from signups. + +```json +{ + "id": "1", + "ip": "8.8.8.8/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 422: Unprocessable entity + +IP has already been blocked, and/or no severity was provided + +```json +{ + "error": "Validation failed: Severity can't be blank, Ip has already been taken" +} +``` + +--- + +## Update a domain block {#update} + +```http +PUT https://mastodon.example/api/v1/admin/ip_blocks/:id HTTP/1.1 +``` + +Change parameters for an existing IP block. + +**Returns:** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth:** User token + `admin:write:ip_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the IpBlock in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +ip +: String. The IP address and prefix to block. Defaults to `0.0.0.0/32` + +severity +: String. The policy to apply to this IP range: `sign_up_requires_approval`, `sign_up_block`, or `no_access` + +comment +: String. The reason for this IP block. + +expires_in +: Integer. The number of seconds in which this IP block will expire. + +#### Response +##### 200: OK + +IP block has been updated + +```json +{ + "id": "1", + "ip": "8.8.4.4/32", + "severity": "no_access", + "comment": "", + "created_at": "2022-11-16T07:22:00.501Z", + "expires_at": null +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Delete an IP block {#delete} + +```http +DELETE https://mastodon.example/api/v1/admin/ip_blocks/:id HTTP/1.1 +``` + +Lift a block against an IP range. + +**Returns:** [Admin::IpBlock]({{< relref "entities/Admin_IpBlock" >}})\ +**OAuth:** User token + `admin:write:domain_blocks`\ +**Permissions:** Manage Blocks\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the DomainAllow in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The IP has been removed from the block list + +```json +{} +``` +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +##### 404: Not found + +IpBlock with the given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/ip_blocks_controller.rb" caption="app/controllers/api/v1/admin/ip_blocks_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/admin/measures.md b/content/en/methods/admin/measures.md new file mode 100644 index 00000000..f56b9db1 --- /dev/null +++ b/content/en/methods/admin/measures.md @@ -0,0 +1,298 @@ +--- +title: measures API methods +description: Obtain quantitative metrics about the server. +menu: + docs: + name: measures + parent: methods-admin + identifier: methods-admin-measures +aliases: [ + "/methods/admin/measures", + "/api/methods/admin/measures", +] +--- + + + +## Get measurable data {#get} + +```http +POST https://mastodon.example/api/v1/admin/measures HTTP/1.1 +``` + +Obtain statistical measures for your server. + +**Returns:** Array of [Admin::Measure]({{< relref "entities/Admin_Measure" >}})\ +**OAuth:** User token + `admin:read`\ +**Permissions:** View Dashboard\ +**Version history:**\ +3.5.0 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +keys[] +: {{}} Array of String. Request specific measures by their keystring. Supported measures include: +- `active_users` = Total active users on your instance within the time period +- `new_users` = Users who joined your instance within the time period +- `interactions` = Total interactions (favourites, boosts, replies) on local statuses within the time period +- `opened_reports` = Total reports filed within the time period +- `resolved_reports` = Total reports resolved within the time period +- `tag_accounts` = Total accounts who used a tag in at least one status within the time period +- `tag_uses` = Total statuses which used a tag within the time period +- `tag_servers` = Total remote origin servers for statuses which used a tag within the time period +- `instance_accounts` = Total accounts originating from a remote domain within the time period +- `instance_media_attachments` = Total space used by media attachments from a remote domain within the time period +- `instance_reports` = Total reports filed against accounts from a remote domain within the time period +- `instance_statuses` = Total statuses originating from a remote domain within the time period +- `instance_follows` = Total accounts from a remote domain followed by a local user within the time period +- `instance_followers` = Total local accounts followed by accounts from a remote domain within the time period + +start_at +: {{}} String (ISO 8601 Datetime). The start date for the time period. If a time is provided, it will be ignored. + +end_at +: {{}} String (ISO 8601 Datetime). The end date for the time period. If a time is provided, it will be ignored. + +tag_accounts[id] +: String. When `tag_accounts` is one of the requested keys, you must provide a tag ID to obtain the measure of how many accounts used that hashtag in at least one status within the given time period. + +tag_uses[id] +: String. When `tag_uses` is one of the requested keys, you must provide a tag ID to obtain the measure of how many statuses used that hashtag within the given time period. + +tag_servers[id] +: String. When `tag_servers` is one of the requested keys, you must provide a tag ID to obtain the measure of how many servers used that hashtag in at least one status within the given time period. + +instance_accounts[domain] +: String. When `instance_accounts` is one of the requested keys, you must provide a remote domain to obtain the measure of how many accounts have been discovered from that server within the given time period. + +instance_media_attachments[domain] +: String. When `instance_media_attachments` is one of the requested keys, you must provide a remote domain to obtain the measure of how much space is used by media attachments from that server within the given time period. + +instance_reports[domain] +: String. When `instance_reports` is one of the requested keys, you must provide a remote domain to obtain the measure of how many reports have been filed against accounts from that server within the given time period. + +instance_statuses[domain] +: String. When `instance_statuses` is one of the requested keys, you must provide a remote domain to obtain the measure of how many statuses originate from that server within the given time period. + +instance_follows[domain] +: String. When `instance_follows` is one of the requested keys, you must provide a remote domain to obtain the measure of how many follows were performed on accounts from that server by local accounts within the given time period. + +instance_followers[domain] +: String. When `instance_followers` is one of the requested keys, you must provide a remote domain to obtain the measure of how many follows were performed by accounts from that server on local accounts within the given time period. + +#### Response +##### 200: OK + +Returns quantitative data for each measure, in aggregate and also by data bucket. + +```json +[ + { + "key": "active_users", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + // ... + ] + }, + { + "key": "new_users", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "interactions", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + // ... + ] + }, + { + "key": "opened_reports", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "resolved_reports", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "tag_accounts", + "unit": null, + "total": "1", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + // ... + ] + }, + { + "key": "tag_uses", + "unit": null, + "total": "2", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00Z", + "value": "0" + }, + // ... + ] + }, + { + "key": "tag_servers", + "unit": null, + "total": "0", + "previous_total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_accounts", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_media_attachments", + "unit": "bytes", + "total": "0", + "human_value": "0 Bytes", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "" + }, + // ... + ] + }, + { + "key": "instance_reports", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_statuses", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_follows", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + }, + { + "key": "instance_followers", + "unit": null, + "total": "0", + "data": [ + { + "date": "2022-09-14T00:00:00.000+00:00", + "value": "0" + }, + // ... + ] + } +] +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/measures_controller.rb" caption="app/controllers/api/v1/admin/measures_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure.rb" caption="app/lib/admin/metrics/measure.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/admin/metrics/measure/" caption="app/lib/admin/metrics/measure/" >}} \ No newline at end of file diff --git a/content/en/methods/admin/reports.md b/content/en/methods/admin/reports.md new file mode 100644 index 00000000..76abc14e --- /dev/null +++ b/content/en/methods/admin/reports.md @@ -0,0 +1,532 @@ +--- +title: admin/reports API methods +description: Perform moderation actions with reports. +menu: + docs: + name: admin/reports + parent: methods-admin + identifier: methods-admin-reports +aliases: [ + "/methods/admin/reports", + "/api/methods/admin/reports", +] +--- + + + +## View all reports {#get} + +```http +GET https://mastodon.example/api/v1/admin/reports HTTP/1.1 +``` + +View information about all reports. + +**Returns:** Array of [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** User token + `admin:read:reports`\ +**Permissions:** Manage Reports\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +resolved +: Boolean. Filter for resolved reports? + +account_id +: String. Filter for reports filed by this account. + +target_account_id +: String. Filter for reports targeting this account. + +#### Response +##### 200: OK + +```json +[ + { + "id": "3", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:23.085Z", + "updated_at": "2022-09-09T21:19:23.085Z", + "account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "target_account": { + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + "email": "goody@mastodon.local", + // ... + "account": { + "id": "108965430868193066", + "username": "goody", + "acct": "goody", + // ... + } + }, + "assigned_account": null, + "action_taken_by_account": null, + "statuses": [], + "rules": [] + }, + // ... +] +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## View a single report {#get-one} + +```http +GET https://mastodon.example/api/v1/admin/reports/:id HTTP/1.1 +``` + +**Returns:** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** User token + `admin:read:reports`\ +**Permissions:** Manage Reports\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Report in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "2", + "action_taken": true, + "action_taken_at": "2022-09-09T21:38:54.679Z", + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:44.021Z", + "updated_at": "2022-09-09T21:38:54.681Z", + "account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "target_account": { + "id": "108965430868193066", + "username": "goody", + "domain": null, + "created_at": "2022-09-08T23:42:04.731Z", + "email": "goody@mastodon.local", + // ... + "account": { + "id": "108965430868193066", + "username": "goody", + "acct": "goody", + // ... + } + }, + "assigned_account": null, + "action_taken_by_account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "statuses": [], + "rules": [] +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Update a report {#update} + +```http +PUT https://mastodon.example/api/v1/admin/reports/:id HTTP/1.1 +``` + +Change metadata for a report. + +**Returns:** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** User token + `admin:write:reports`\ +**Permissions:** Manage Reports\ +**Version history:**\ +3.5.0 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Report in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +category +: String. Change the classification of the report to `spam`, `violation`, or `other`. + +rule_ids[] +: Array of Integer. For `violation` category reports, specify the ID of the exact rules broken. Rules and their IDs are available via [GET /api/v1/instance/rules]({{< relref "methods/instance#rules" >}}) and [GET /api/v1/instance]({{< relref "methods/instance#get" >}}). + +#### Response +##### 200: OK + +The report category and/or rule IDs should now be updated. + +```json +{ + "id": "3", + "action_taken": false, + "action_taken_at": null, + "category": "other", + // ... + "rules": [] +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Assign report to self {#assign_to_self} + +```http +POST https://mastodon.example/api/v1/admin/reports/:id/assign_to_self HTTP/1.1 +``` + +Claim the handling of this report to yourself. + +**Returns:** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** User token + `admin:write:reports`\ +**Permissions:** Manage Reports\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Report in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The report should now be assigned to you, or it was already assigned to you. + +```json +{ + "id": "3", + "action_taken": false, + "action_taken_at": null, + "category": "other", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:21:01.204Z", + "updated_at": "2022-09-11T14:39:01.531Z", + // ... + "assigned_account": { + "id": "108965218747268792", + "username": "admin", + "domain": null, + "created_at": "2022-09-08T22:48:07.985Z", + "email": "admin@mastodon.local", + // ... + "account": { + "id": "108965218747268792", + "username": "admin", + "acct": "admin", + // ... + } + }, + "action_taken_by_account": null, + "statuses": [], + "rules": [] +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Unassign report {#unassign} + +```http +POST https://mastodon.example/api/v1/admin/reports/:id/unassign HTTP/1.1 +``` + +Unassign a report so that someone else can claim it. + +**Returns:** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** User token + `admin:write:reports`\ +**Permissions:** Manage Reports\ +**Version history:**\ +2.9.1 - added +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Report in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The report should no longer be assigned to you, or it was already not assigned to anyone. + +```json +{ + "id": "3", + "action_taken": false, + "action_taken_at": null, + "category": "other", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:21:01.204Z", + "updated_at": "2022-09-11T14:39:01.531Z", + // ... + "assigned_account": null, + "action_taken_by_account": null, + "statuses": [], + "rules": [] +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## Mark report as resolved {#resolve} + +```http +POST https://mastodon.example/api/v1/admin/reports/:id/resolve HTTP/1.1 +``` + +Mark a report as resolved with no further action taken. + +**Returns:** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** User token + `admin:write:reports`\ +**Permissions:** Manage Reports\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Report in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The report is now resolved, or it was already resolved. + +```json +{ + "id": "2", + "action_taken": true, + "action_taken_at": "2022-09-11T14:46:22.936Z", + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:44.021Z", + "updated_at": "2022-09-11T14:46:22.945Z", + // ... +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` +--- + +## Reopen a closed report {#reopen} + +```http +POST https://mastodon.example/api/v1/admin/reports/:id/reopen HTTP/1.1 +``` + +Reopen a currently closed report, if it is closed. + +**Returns:** [Admin::Report]({{< relref "entities/Admin_Report" >}})\ +**OAuth:** User token + `admin:write:reports`\ +**Permissions:** Manage Reports\ +**Version history:**\ +2.9.1 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the SOMETHING in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The report no longer has an action taken, or it already had no action taken. + +```json +{ + "id": "2", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "", + "forwarded": false, + "created_at": "2022-09-09T21:19:44.021Z", + "updated_at": "2022-09-11T14:42:21.855Z", + // ... +} +``` + +##### 403: Forbidden + +Authorized user is not allowed to perform this action, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/admin/accounts#action" caption="POST /api/v1/admin/accounts/:id/action" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/reports_controller.rb" caption="app/controllers/api/v1/admin/reports_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/admin/retention.md b/content/en/methods/admin/retention.md new file mode 100644 index 00000000..4f77b258 --- /dev/null +++ b/content/en/methods/admin/retention.md @@ -0,0 +1,173 @@ +--- +title: retention API methods +description: Show retention data over time. +menu: + docs: + name: retention + parent: methods-admin + identifier: methods-admin-retention +aliases: [ + "/methods/admin/retention", + "/api/methods/admin/retention", +] +--- + + + +## Calculate retention data {#create} + +```http +POST https://mastodon.example/api/v1/admin/retention HTTP/1.1 +``` + +Generate a retention data report for a given time period and bucket. + +**Returns:** Array of [Admin::Cohort]({{< relref "entities/Admin_Cohort" >}})\ +**OAuth:** User token + `admin:read`\ +**Permissions:** View Dashboard\ +**Version history:**\ +3.5.0 - added\ +4.0.0 - support custom roles and permissions + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +start_at +: {{}} String (ISO 8601 Datetime). The start date for the time period. If a time is provided, it will be ignored. + +end_at +: {{}} String (ISO 8601 Datetime). The end date for the time period. If a time is provided, it will be ignored. + +frequency +: {{}} String (Enumerable oneOf). Specify whether to use `day` or `month` buckets. If any other value is provided, defaults to `day`. + +#### Response +##### 200: OK + +Monthly retention data for the month of 2022-09, given that 2 users registered during 2022-09 and were active at least once during that month. + +```json +[ + { + "period": "2022-09-01T00:00:00+00:00", + "frequency": "month", + "data": [ + { + "date": "2022-09-01T00:00:00+00:00", + "rate": 1.0, + "value": "2" + } + ] + } +] +``` + +Daily retention data for the week between 2022-09-08 and 2022-09-14, given that 2 users registered on 2022-09-08 and 1 of those users stopped being active after 2022-09-09. + +```json +[ + { + "period": "2022-09-08T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-08T00:00:00+00:00", + "rate": 1, + "value": "2" + }, + { + "date": "2022-09-09T00:00:00+00:00", + "rate": 1, + "value": "2" + }, + { + "date": "2022-09-10T00:00:00+00:00", + "rate": 0.5, + "value": "1" + }, + // ... + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0.5, + "value": "1" + } + ] + }, + { + "period": "2022-09-09T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-09T00:00:00+00:00", + "rate": 0, + "value": "0" + }, + // ... + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0, + "value": "0" + } + ] + }, + { + "period": "2022-09-10T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-10T00:00:00+00:00", + "rate": 0, + "value": "0" + }, + // ... + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0, + "value": "0" + } + ] + }, + // ... + { + "period": "2022-09-14T00:00:00+00:00", + "frequency": "day", + "data": [ + { + "date": "2022-09-14T00:00:00+00:00", + "rate": 0, + "value": "0" + } + ] + } +] +``` + +If any of the parameters are missing, cohort calculation will fail and an empty array will be returned. + +```json +[] +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/retention_controller.rb" caption="app/controllers/api/v1/admin/retention_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/admin/trends.md b/content/en/methods/admin/trends.md new file mode 100644 index 00000000..ea877743 --- /dev/null +++ b/content/en/methods/admin/trends.md @@ -0,0 +1,137 @@ +--- +title: admin/trends API methods +description: TODO +menu: + docs: + name: admin/trends + parent: methods-admin + identifier: methods-admin-trends +aliases: [ + "/methods/admin/measures", + "/api/methods/admin/measures", +] +--- + + + +{{< hint style="danger" >}} +This page is under construction. +{{< /hint >}} + +## View trending links {#links} + +```http +GET https://mastodon.example/api/v1/admin/trends/links HTTP/1.1 +``` + +**Returns:** [???]({{< relref "entities/???" >}})\ +**OAuth:** User token + `admin:read`\ +**Permissions:** Manage Taxonomies\ +**Version history:**\ +3.5.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + + +```json +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +## View trending statuses {#statuses} + +```http +GET https://mastodon.example/api/v1/admin/trends/statuses HTTP/1.1 +``` + +**Returns:** [???]({{< relref "entities/???" >}})\ +**OAuth:** User token + `admin:read`\ +**Permissions:** Manage Taxonomies\ +**Version history:**\ +3.5.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + + +```json +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +## View trending tags {#tags} + +```http +GET https://mastodon.example/api/v1/admin/trends/tags HTTP/1.1 +``` + +**Returns:** [???]({{< relref "entities/???" >}})\ +**OAuth:** User token + `admin:read`\ +**Permissions:** Manage Taxonomies\ +**Version history:**\ +3.5.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + + +```json +``` + +##### 403: Forbidden + +Authorized user is missing a permission, or invalid or missing Authorization header + +```json +{ + "error": "This action is not allowed" +} +``` + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/trends/links_controller.rb" caption="app/controllers/api/v1/admin/trends/links_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/trends/statuses_controller.rb" caption="app/controllers/api/v1/admin/trends/statuses_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/trends/tags_controller.rb" caption="app/controllers/api/v1/admin/trends/tags_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/announcements.md b/content/en/methods/announcements.md index 3a9eb125..fe0a649c 100644 --- a/content/en/methods/announcements.md +++ b/content/en/methods/announcements.md @@ -1,45 +1,54 @@ --- -title: announcements +title: announcements API methods description: For announcements set by administration. menu: docs: weight: 90 - parent: methods + name: announcements + parent: methods-instance + identifier: methods-announcements +aliases: [ + "/methods/announcements", + "/api/methods/announcements", + "/methods/instance/announcements", +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/announcements" title="View all announcements" >}} -{{< api-method-description >}} + + +## View all announcements {#get} + +```http +GET https://mastodon.example/api/v1/announcements HTTP/1.1 +``` See all currently active announcements set by admins. -**Returns:** Array of Announcement\ +**Returns:** Array of [Announcement]({{< relref "entities/announcement">}})\ **OAuth:** User token\ **Version history:**\ 3.1.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="with_dismissed" type="boolean" required=false >}} -If true, response will include announcements dismissed by the user. Defaults to false. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +with_dismissed +: Boolean. If true, response will include announcements dismissed by the user. Defaults to false. + +#### Response +##### 200: OK Currently active announcements -{{< endapi-method-response-example-description >}} - -```javascript +```json [ { "id": "8", @@ -85,14 +94,24 @@ Currently active announcements } ] ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +##### 401: Unauthorized -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/announcements/:id/dismiss" title="Dismiss an announcement" >}} -{{< api-method-description >}} +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Dismiss an announcement {#dismiss} + +```http +POST https://mastodon.example/api/v1/announcements/:id/dismiss HTTP/1.1 +``` Allows a user to mark the announcement as read. @@ -101,37 +120,51 @@ Allows a user to mark the announcement as read. **Version history:**\ 3.1.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of an announcement in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The ID of the Announcement in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK +```json {} ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +##### 401: Unauthorized -{{< api-method method="put" host="https://mastodon.example" path="/api/v1/announcements/:id/reactions/:name" title="Add reaction" >}} -{{< api-method-description >}} +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Announcement with given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Add a reaction to an announcement {#put-reactions} + +```http +PUT https://mastodon.example/api/v1/announcements/:id/reactions/:name HTTP/1.1 +``` React to an announcement with an emoji. @@ -140,48 +173,63 @@ React to an announcement with an emoji. **Version history:**\ 3.1.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of an announcement in the database. -{{< endapi-method-parameter >}} -{{< api-method-parameter name=":name" type="string" required=true >}} -Unicode emoji, or shortcode of custom emoji -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The ID of the Announcement in the database. + +:name +: {{}} String. Unicode emoji, or the shortcode of a custom emoji. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json {} ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized -```javascript -{"error":"Validation failed: Name is not a recognized emoji"} +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/announcements/:id/reactions/:name" title="Remove reaction" >}} -{{< api-method-description >}} +##### 404: Not found + +Announcement with given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Name is not a recognized emoji" +} +``` + +--- + +## Remove a reaction from an announcement {#delete-reactions} + +```http +DELETE https://mastodon.example/api/v1/announcements/:id/reactions/:name HTTP/1.1 +``` Undo a react emoji to an announcement. @@ -190,42 +238,60 @@ Undo a react emoji to an announcement. **Version history:**\ 3.1.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of an announcement in the database. -{{< endapi-method-parameter >}} -{{< api-method-parameter name=":name" type="string" required=true >}} -Unicode emoji, or shortcode of custom emoji -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The ID of the Announcement in the database. + +:name +: {{}} String. Unicode emoji, or the shortcode of a custom emoji. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json {} ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized -```javascript -{"error":"Validation failed: Name is not a recognized emoji"} +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} \ No newline at end of file + +##### 404: Not found + +Announcement with given ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Name is not a recognized emoji" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/announcements_controller.rb" caption="app/controllers/api/v1/announcements_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/announcements/reactions_controller.rb" caption="app/controllers/api/v1/announcements/reactions_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/apps.md b/content/en/methods/apps.md index eda1e4f5..76e860b3 100644 --- a/content/en/methods/apps.md +++ b/content/en/methods/apps.md @@ -1,51 +1,57 @@ --- -title: apps +title: apps API methods description: Register client applications that can be used to obtain OAuth tokens. menu: docs: weight: 10 + name: apps parent: methods identifier: methods-apps +aliases: [ + "/methods/apps", + "/api/methods/apps", +] --- -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/apps" title="Create an application" >}} -{{< api-method-description >}} + + +## Create an application {#create} + +```http +POST https://mastodon.example/api/v1/apps HTTP/1.1 +``` Create a new application to obtain OAuth2 credentials. -**Returns:** Application, with `client_id` and `client_secret`\ +**Returns:** [Application]({{< relref "entities/Application" >}})\ **OAuth:** Public\ **Version history:**\ 0.0.0 - added\ 2.7.2 - now returns `vapid_key` -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="client_name" type="string" required=true >}} -A name for your application -{{< endapi-method-parameter >}} -{{< api-method-parameter name="redirect_uris" type="string" required=true >}} -Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="scopes" type="string" required=false >}} -Space separated list of scopes. If none is provided, defaults to `read`. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="website" type="string" required=false >}} -A URL to the homepage of your app -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Form data parameters + +client_name +: {{}} String. A name for your application + +redirect_uris +: {{}} String. Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter. + +scopes +: String. Space separated list of scopes. If none is provided, defaults to `read`. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a list of possible scopes. + +website +: String. A URL to the homepage of your app + +#### Response +##### 200: OK Store the `client_id` and `client_secret` in your cache, as these will be used to obtain OAuth tokens. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "563419", "name": "test app", @@ -56,74 +62,67 @@ Store the `client_id` and `client_secret` in your cache, as these will be used t "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} + +##### 422: Unprocessable entity If a required parameter is missing or improperly formatted, the request will fail. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "Validation failed: Redirect URI must be an absolute URI." } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/apps/verify_credentials" title="Verify your app works" >}} -{{< api-method-description >}} + +--- + +## Verify your app works {#verify_credentials} + +```http +GET https://mastodon.example/api/v1/apps/verify_credentials HTTP/1.1 +``` Confirm that the app's OAuth2 credentials work. -**Returns:** Application\ +**Returns:** [Application]({{< relref "entities/application" >}}), but without `client_id` or `client_secret`\ **OAuth level:** App token\ **Version history:**\ 2.0.0 - added\ 2.7.2 - now returns `vapid_key` -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <app token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK If the Authorization header was provided with a valid token, you should see your app returned as an Application entity. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "name": "test app", "website": null, "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} + +##### 401: Unauthorized If the Authorization header contains an invalid token, is malformed, or is not present, an error will be returned indicating an authorization failure. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/apps_controller.rb" caption="app/controllers/api/v1/apps_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/apps/credentials_controller.rb" caption="app/controllers/api/v1/apps/credentials_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/apps/oauth.md b/content/en/methods/apps/oauth.md deleted file mode 100644 index f01ff617..00000000 --- a/content/en/methods/apps/oauth.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: oauth -description: Generate and manage OAuth tokens. -menu: - docs: - weight: 10 - parent: methods-apps ---- - -{{< api-method method="get" host="https://mastodon.example" path="/oauth/authorize" title="Authorize a user" >}} -{{< api-method-description >}} - -Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested. The authorization code can be used while requesting a token to obtain access to user-level methods. - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="response_type" type="string" required=true >}} -Should be set equal to `code`. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="client_id" type="string" required=true >}} -Client ID, obtained during app registration. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="redirect_uri" type="string" required=true >}} -Set a URI to redirect the user to. If this parameter is set to `urn:ietf:wg:oauth:2.0:oob` then the authorization code will be shown instead. Must match one of the redirect URIs declared during app registration. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="scope" type="string" required=false >}} -List of requested OAuth scopes, separated by spaces \(or by pluses, if using query parameters\). Must be a subset of scopes declared during app registration. If not provided, defaults to `read`. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="force_login" type="bool" required=false >}} -Added in 2.6.0. Forces the user to re-login, which is necessary for authorizing with multiple accounts from the same instance. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -The authorization code will be returned as a query parameter named `code`. -{{< endapi-method-response-example-description >}} - - -```http -redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=400 >}} -{{< api-method-response-example-description >}} - -If the authorization code is incorrect or has been used already, the request will fail. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "invalid_grant", - "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/oauth/token" title="Obtain a token" >}} -{{< api-method-description >}} - -Returns an access token, to be used during API calls that are not public. - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="grant_type" type="string" required=true >}} -Set equal to `authorization_code` if `code` is provided in order to gain user-level access. Otherwise, set equal to `client_credentials` to obtain app-level access only. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="client_id" type="string" required=true >}} -Client ID, obtained during app registration -{{< endapi-method-parameter >}} -{{< api-method-parameter name="client_secret" type="string" required=true >}} -Client secret, obtained during app registration -{{< endapi-method-parameter >}} -{{< api-method-parameter name="redirect_uri" type="string" required=true >}} -Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the token will be shown instead. Must match one of the redirect URIs declared during app registration. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="scope" type="string" required=false >}} -List of requested OAuth scopes, separated by spaces. Must be a subset of scopes declared during app registration. If not provided, defaults to `read`. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="code" type="string" required=false >}} -A user authorization code, obtained via /oauth/authorize -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Store this access_token for later use with auth-required methods. The token should be passed as an HTTP `Authorization` header when making API calls, with the value `Bearer access_token` -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0", - "token_type": "Bearer", - "scope": "read write follow push", - "created_at": 1573979017 -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=400 >}} -{{< api-method-response-example-description >}} - -If you try to request a scope that was not included when registering the app, the request will fail. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "invalid_scope", - "error_description": "The requested scope is invalid, unknown, or malformed." -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -If client_id and client_secret do not match or are invalid, the request will fail. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "invalid_client", - "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method." -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/oauth/revoke" title="Revoke token" >}} -{{< api-method-description >}} - -Revoke an access token to make it no longer valid for use. - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="client_id" type="string" required=true >}} -Client ID, obtained during app registration -{{< endapi-method-parameter >}} -{{< api-method-parameter name="client_secret" type="string" required=true >}} -Client secret, obtained during app registration -{{< endapi-method-parameter >}} -{{< api-method-parameter name="token" type="string" required=true >}} -The previously obtained token, to be invalidated -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -If you own the provided token, the API call will provide an empty response. This operation is idempotent, so calling this API multiple times will still return OK. -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=403 >}} -{{< api-method-response-example-description >}} - -If you provide a token you do not own, or no token at all, the API call will return a 403 error. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "unauthorized_client", - "error_description": "You are not authorized to revoke this token" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - diff --git a/content/en/methods/blocks.md b/content/en/methods/blocks.md new file mode 100644 index 00000000..e8504c2e --- /dev/null +++ b/content/en/methods/blocks.md @@ -0,0 +1,102 @@ +--- +title: blocks API methods +description: View your blocks. See also accounts/:id/{block,unblock} +menu: + docs: + weight: 40 + name: blocks + parent: methods-accounts + identifier: methods-blocks +aliases: [ + "/methods/blocks", + "/api/methods/blocks", + "/methods/accounts/blocks", +] +--- + + + +## View blocked users {#get} + +```http +GET https://mastodon.example/api/v1/blocks HTTP/1.1 +``` + +**Returns:** Array of [Account]({{< relref "entities/account" >}})\ +**OAuth:** User token + `read:blocks`\ +**Version history:**\ +0.0.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +Sample call with limit=2. + +```json +[ + { + "id": "585315", + "username": "admin", + "acct": "admin@happylittle.cloudns.cc", + "display_name": "☁️ ⛅ Happy Little Clouds ⛅ ☁️", + // ... + }, + { + "id": "650568", + "username": "Nikolai_Kingsley", + "acct": "Nikolai_Kingsley@dobbs.town", + "display_name": "Rev.Dr. Nikolai Kingsley", + // ... + } +] +``` + +Because Block IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/accounts#block" caption="POST /api/v1/accounts/:id/block" >}} + +{{< page-relref ref="methods/accounts#unblock" caption="POST /api/v1/accounts/:id/unblock" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/blocks_controller.rb" caption="app/controllers/api/v1/blocks_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/bookmarks.md b/content/en/methods/bookmarks.md new file mode 100644 index 00000000..54b92788 --- /dev/null +++ b/content/en/methods/bookmarks.md @@ -0,0 +1,108 @@ +--- +title: bookmarks API methods +description: View your bookmarks. See also statuses/:id/{bookmark,unbookmark} +menu: + docs: + weight: 10 + name: bookmarks + parent: methods-accounts + identifier: methods-bookmarks +aliases: [ + "/methods/bookmarks", + "/api/methods/bookmarks", + "/methods/accounts/bookmarks", +] +--- + + + +## View bookmarked statuses {#get} + +```http +GET https://mastodon.example/api/v1/bookmarks HTTP/1.1 +``` + +Statuses the user has bookmarked. + +**Returns:** Array of [Status]({{< relref "entities/status" >}})\ +**OAuth:** User token + `read:bookmarks`\ +**Version history:**\ +3.1.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now + +### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +```json +[ + { + "id": "108724195870225687", + "created_at": "2022-07-28T09:12:47.000Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + // ... + }, + { + "id": "108200780982641655", + "created_at": "2022-04-26T22:41:28.492Z", + "in_reply_to_id": "108200775562138405", + "in_reply_to_account_id": "806143", + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + // ... + }, + // ... +] +``` + +Because Bookmark IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/statuses#bookmark" caption="POST /api/v1/statuses/:id/bookmark" >}} + +{{< page-relref ref="methods/statuses#unbookmark" caption="POST /api/v1/statuses/:id/unbookmark" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/bookmarks_controller.rb" caption="app/controllers/api/v1/bookmarks_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/conversations.md b/content/en/methods/conversations.md new file mode 100644 index 00000000..3f975c80 --- /dev/null +++ b/content/en/methods/conversations.md @@ -0,0 +1,246 @@ +--- +title: conversations API methods +description: >- + Direct conversations with other participants. (Currently, just threads + containing a post with "direct" visibility.) +menu: + docs: + weight: 10 + name: conversations + parent: methods-timelines + identifier: methods-conversations +aliases: [ + "/methods/conversations", + "/api/methods/conversations", + "/methods/timelines/conversations", +] +--- + + + +## View all conversations {#get} + +```http +GET https://mastodon.example/api/v1/conversations HTTP/1.1 +``` + +**Returns:** Array of [Conversation]({{< relref "entities/conversation" >}})\ +**OAuth:** User token + `read:statuses`\ +**Version history:**\ +2.6.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 20. Max 40. + +#### Response + +##### 200: OK + +Truncated sample results of an API call with limit=2 + +```json +[ + { + "id": "418450", + "unread": true, + "accounts": [ + { + "id": "482403", + "username": "amic", + "acct": "amic@nulled.red", + // ... + } + ], + "last_status": { + "id": "103196583826321184", + "created_at": "2019-11-25T04:08:24.000Z", + "in_reply_to_id": "103196540587943467", + "in_reply_to_account_id": "14715", + // ... + } + }, + { + "id": "418374", + "unread": false, + "accounts": [ + { + "id": "464472", + "username": "freon", + "acct": "freon@letsalllovela.in", + // ... + } + ], + "last_status": { + "id": "103195253010396431", + "created_at": "2019-11-24T22:29:56.331Z", + "in_reply_to_id": "103195239650546339", + "in_reply_to_account_id": "14715", + // ... + } + } +] +``` + +Because AccountConversation IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Remove a conversation {#delete} + +```http +DELETE https://mastodon.example/api/v1/conversations/:id HTTP/1.1 +``` + +Removes a conversation from your list of conversations. + +**Returns:** empty object\ +**OAuth:** User token + `write:conversations`\ +**Version history:**\ +2.6.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Conversation in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +The conversation does not exist, or is not owned by you. + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Mark a conversation as read {#read} + +```http +POST https://mastodon.example/api/v1/conversations/:id/read HTTP/1.1 +``` + +**Returns:** [Conversation]({{< relref "entities/conversation" >}})\ +**OAuth:** User token + `write:conversations`\ +**Version history:**\ +2.6.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Conversation in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The value of `unread` has been changed to false. + +```json +{ + "id": "418450", + "unread": false, + "accounts": [ + { + "id": "482403", + // ... + } + ], + "last_status": { + "id": "103196583826321184", + // ... + } +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +The conversation does not exist, or is not owned by you. + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/conversations_controller.rb" caption="app/controllers/api/v1/conversations_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/instance/custom_emojis.md b/content/en/methods/custom_emojis.md similarity index 72% rename from content/en/methods/instance/custom_emojis.md rename to content/en/methods/custom_emojis.md index 6626ebe1..54e648cc 100644 --- a/content/en/methods/instance/custom_emojis.md +++ b/content/en/methods/custom_emojis.md @@ -1,37 +1,45 @@ --- -title: custom_emojis +title: custom_emojis API methods description: >- Each site can define and upload its own custom emoji to be attached to profiles or statuses. menu: docs: weight: 30 + name: custom_emojis parent: methods-instance + identifier: methods-custom_emojis +aliases: [ + "/methods/custom_emojis", + "/api/methods/custom_emojis", + "/methods/instance/custom_emojis" +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/custom_emojis" title="Custom emoji" >}} -{{< api-method-description >}} + + +## View all custom emoji {#get} + +```http +GET https://mastodon.example/api/v1/custom_emojis HTTP/1.1 +``` Returns custom emojis that are available on the server. -**Returns:** Array of Emoji\ +**Returns:** Array of [CustomEmoji]({{< relref "entities/CustomEmoji" >}})\ **OAuth:** Public\ **Version history:**\ 2.0.0 - added\ 3.0.0 - optional `category` added to response -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Response +##### 200: OK Sample response from mastodon.social -{{< endapi-method-response-example-description >}} - -```javascript +```json [ { "shortcode": "aaaa", @@ -72,9 +80,9 @@ Sample response from mastodon.social } ] ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/custom_emojis_controller.rb" caption="app/controllers/api/v1/custom_emojis_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/directory.md b/content/en/methods/directory.md new file mode 100644 index 00000000..bd857de8 --- /dev/null +++ b/content/en/methods/directory.md @@ -0,0 +1,78 @@ +--- +title: directory API methods +description: A directory of profiles that your website is aware of. +menu: + docs: + weight: 20 + name: directory + parent: methods-instance + identifier: methods-directory +aliases: [ + "/methods/directory", + "/api/methods/directory", + "/methods/instance/directory", +] +--- + + + +## View profile directory {#get} + +```http +GET https://mastodon.example/api/v1/directory HTTP/1.1 +``` + +List accounts visible in the directory. + +**Returns:** Array of [Account]({{< relref "entities/account" >}})\ +**OAuth:** Public\ +**Version history:**\ +3.0.0 - added + +#### Request + +##### Query parameters + +offset +: Number. How many accounts to skip before returning results. Default 0. + +limit +: Number. How many accounts to load. Default 40. + +order +: String. Use `active` to sort by most recently posted statuses (default) or `new` to sort by most recently created profiles. + +local +: Boolean. If true, returns only local accounts. + +#### Response +##### 200: OK + +Sample results with limit=2 + +```json +[ + { + "id": "796927", + "username": "eternalNo3", + "acct": "eternalNo3@best-friends.chat", + "display_name": "ESD＠┓（谷）┏", + // ... + }, + { + "id": "787648", + "username": "ariel", + "acct": "ariel@best-friends.chat", + "display_name": "あやっしー🧜🏻‍♀️", + // ... + } +] +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/directories_controller.rb" caption="app/controllers/api/v1/directories_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/domain_blocks.md b/content/en/methods/domain_blocks.md new file mode 100644 index 00000000..a3e1a8f9 --- /dev/null +++ b/content/en/methods/domain_blocks.md @@ -0,0 +1,213 @@ +--- +title: domain_blocks API methods +description: Manage a user's blocked domains. +menu: + docs: + weight: 50 + name: domain_blocks + parent: methods-accounts + identifier: methods-domain_blocks +aliases: [ + "/methods/domain_blocks", + "/api/methods/domain_blocks", + "/methods/accounts/domain_blocks"] +--- + + + +## Get domain blocks {#get} + +```http +GET https://mastodon.example/api/v1/domain_blocks HTTP/1.1 +``` + +View domains the user has blocked. + +**Returns:** Array of String\ +**OAuth:** User token + `read:blocks` or `follow`\ +**Version:**\ +1.4.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +Sample call with limit=2. + +```json +["nsfw.social","artalley.social"] +``` + +Because AccountDomainBlock IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Block a domain {#block} + +```http +POST https://mastodon.example/api/v1/domain_blocks HTTP/1.1 +``` + +Block a domain to: +- hide all public posts from it +- hide all notifications from it +- remove all followers from it +- prevent following new users from it (but does not remove existing follows) + +**Returns:** empty object\ +**OAuth:** User token + `write:blocks` or `follow`\ +**Version:**\ +1.4.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +domain +: {{}} String. Domain to block. + +#### Response +##### 200: OK + +If the call was successful, an empty object will be returned. Note that the call will be successful even if the domain is already blocked, or if the domain does not exist, or if the domain is not a domain. + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +If `domain` is not provided, the request will fail. + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +If `domain` contains spaces, the request will fail. + +```json +{ + "error": "Validation failed: Domain is not a valid domain name" +} +``` + +--- + +## Unblock a domain {#unblock} + +```http +DELETE https://mastodon.example/api/v1/domain_blocks HTTP/1.1 +``` + +Remove a domain block, if it exists in the user's array of blocked domains. + +**Returns:** empty object\ +**OAuth:** User token + `write:blocks` or `follow`\ +**Version history:**\ +1.4.0 - added + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +domain +: {{}} String. Domain to unblock. + +#### Response +##### 200: OK + +If the call was successful, an empty object will be returned. Note that the call will be successful even if the domain was not previously blocked. + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +If `domain` is not provided, the request will fail. + +```json +{ + "error": "Validation failed: Domain can't be blank" +} +``` + +If `domain` contains spaces, the request will fail. + +```json +{ + "error": "Validation failed: Domain is not a valid domain name" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/domain_blocks_controller.rb" caption="app/controllers/api/v1/domain_blocks_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/emails.md b/content/en/methods/emails.md new file mode 100644 index 00000000..f9385460 --- /dev/null +++ b/content/en/methods/emails.md @@ -0,0 +1,67 @@ +--- +title: emails API methods +description: Request a new confirmation email, potentially to a new email address. +menu: + docs: + weight: 20 + name: emails + parent: methods-apps + identifier: methods-emails +aliases: [ + "/methods/emails", + "/api/methods/emails", + "/methods/apps/emails", +] +--- + + + +## Resend confirmation email {#confirmation} + +```http +POST https://mastodon.example/api/v1/emails/confirmation HTTP/1.1 +``` + +**Returns:** Empty object\ +**OAuth:** User token issued to the client that created the unconfirmed user\ +**Version history:**\ +3.4.0 - added + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +email +: If provided, updates the unconfirmed user's email before resending the confirmation email. + +#### Response +##### 200: OK + +```json +{} +``` + +##### 403: Forbidden +The client associated with the token does not own the unconfirmed user. + +```json +{ + "error": "This method is only available to the application the user originally signed-up with" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}} + +{{< page-relref ref="methods/accounts#create" caption="POST /api/v1/accounts" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/emails/confirmations_controller.rb" caption="app/controllers/api/v1/emails/confirmations_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/accounts/endorsements.md b/content/en/methods/endorsements.md similarity index 58% rename from content/en/methods/accounts/endorsements.md rename to content/en/methods/endorsements.md index 8a50b70a..8572bc22 100644 --- a/content/en/methods/accounts/endorsements.md +++ b/content/en/methods/endorsements.md @@ -1,53 +1,64 @@ --- -title: endorsements -description: 'Feature other profiles on your own profile. See also accounts/:id/{pin,unpin}' +title: endorsements API methods +description: Feature other profiles on your own profile. See also accounts/:id/{pin,unpin} menu: docs: weight: 90 + name: endorsements parent: methods-accounts + identifier: methods-endorsements +aliases: [ + "/methods/endorsements", + "/api/methods/endorsements", + "/methods/accounts/endorsements", +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/endorsements" title="View currently featured profiles" >}} -{{< api-method-description >}} + + +## View currently featured profiles {#get} + +```http +GET https://mastodon.example/api/v1/endorsements HTTP/1.1 +``` Accounts that the user is currently featuring on their profile. -**Returns:** Array of Account\ +**Returns:** Array of [Account]({{< relref "entities/account" >}})\ **OAuth:** User token + `read:accounts`\ **Version history:**\ -2.5.0 - added +2.5.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results to return. Defaults to 40. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Internal parameter. Use HTTP `Link` header from response for pagination -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Internal parameter. Use HTTP `Link` header from response for pagination. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request -Sample call with limit=2. Because endorsement ids are private, you must parse the HTTP Link header to find next and previous pages. -{{< endapi-method-response-example-description >}} +##### Headers +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. -```javascript -Link: ; rel="next", ; rel="prev" +##### Query parameters +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +Sample call with limit=2. + +```json [ { "id": "952529", @@ -100,22 +111,29 @@ Link: ; rel=" } ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -If Authorization header is not provided correctly -{{< endapi-method-response-example-description >}} +Because AccountPin IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. +```http +Link: ; rel="next", ; rel="prev" +``` -```javascript +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< page-relref ref="methods/accounts#pin" caption="POST /api/v1/accounts/:id/pin" >}} + +{{< page-relref ref="methods/accounts#unpin" caption="POST /api/v1/accounts/:id/unpin" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/endorsements_controller.rb" caption="app/controllers/api/v1/endorsements_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/favourites.md b/content/en/methods/favourites.md new file mode 100644 index 00000000..299a3ae2 --- /dev/null +++ b/content/en/methods/favourites.md @@ -0,0 +1,141 @@ +--- +title: favourites API methods +description: View your favourites. See also statuses/:id/{favourite,unfavourite} +menu: + docs: + weight: 20 + name: favourites + parent: methods-accounts + identifier: methods-favourites +aliases: [ + "/methods/favourites", + "/api/methods/favourites", + "/methods/accounts/favourites", +] +--- + + + +## View favourited statuses {#get} + +```http +GET https://mastodon.example/api/v1/favourites HTTP/1.1 +``` + +Statuses the user has favourited. + +**Returns:** Array of [Status]({{< relref "entities/status" >}})\ +**OAuth:** User token + `read:favourites`\ +**Version:**\ +0.0.0 - added\ +2.6.0 - `min_id` added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +An example call with limit=2. + +```json +[ + { + "id": "103186075217296344", + "created_at": "2019-11-23T07:35:52.000Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "unlisted", + "language": "enCy", + "uri": "https://cybre.space/users/haskal/statuses/103186075002013902", + "url": "https://cybre.space/@haskal/103186075002013902", + "replies_count": 0, + "reblogs_count": 1, + "favourites_count": 1, + "favourited": true, + "reblogged": false, + "muted": false, + "bookmarked": false, + "content": "

the pirate gay

", + "reblog": null, + "account": { + "id": "297420", + "username": "haskal", + "acct": "haskal@cybre.space", + "display_name": "soft nb friend :blobcatsleep:", + // ... + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null + }, + { + "id": "103186044372624124", + "created_at": "2019-11-23T07:28:03.000Z", + // ... + "content": "

cute,,,

", + "reblog": null, + "account": { + "id": "297420", + "username": "haskal", + "acct": "haskal@cybre.space", + "display_name": "soft nb friend :blobcatsleep:", + "locked": false, + "bot": false, + // ... + }, + // ... + } +] +``` + +Because Favourite IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/statuses#favourite" caption="POST /api/v1/statuses/:id/favourite" >}} + +{{< page-relref ref="methods/statuses#unfavourite" caption="POST /api/v1/statuses/:id/unfavourite" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/favourites_controller.rb" caption="app/controllers/api/v1/favourites_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/featured_tags.md b/content/en/methods/featured_tags.md new file mode 100644 index 00000000..1183b614 --- /dev/null +++ b/content/en/methods/featured_tags.md @@ -0,0 +1,312 @@ +--- +title: featured_tags API methods +description: Feature tags that you use frequently on your profile. +menu: + docs: + weight: 100 + name: featured_tags + parent: methods-accounts + identifier: methods-featured_tags +aliases: [ + "/methods/featured_tags", + "/api/methods/featured_tags", + "/methods/accounts/featured_tags", +] +--- + + + +## View your featured tags {#get} + +```http +GET https://mastodon.example/api/v1/featured_tags HTTP/1.1 +``` + +List all hashtags featured on your profile. + +**Returns:** Array of [FeaturedTag]({{< relref "entities/featuredtag" >}})\ +**OAuth:** User token + `read:accounts`\ +**Version history:**\ +3.0.0 - added + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +[ + { + "id": "627", + "name": "nowplaying", + "url": "https://mastodon.social/@trwnh/tagged/nowplaying", + "statuses_count": 70, + "last_status_at": "2022-08-29T12:03:35.061Z" + } +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Feature a tag {#feature} + +```http +POST https://mastodon.example/api/v1/featured_tags HTTP/1.1 +``` + +Promote a hashtag on your profile. + +**Returns:** [FeaturedTag]({{< relref "entities/featuredtag" >}})\ +**OAuth:** User token + `write:accounts`\ +**Version history:**\ +3.0.0 - added + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +name +: {{}} String. The hashtag to be featured, without the hash sign. + +#### Response +##### 200: OK + +A FeaturedTag will be created with the specified `name`. + +```json +{ + "id": "13174", + "name": "circasurvive", + "url": "https://mastodon.social/@trwnh/tagged/circasurvive", + "statuses_count": 23, + "last_status_at": "2021-10-22T14:47:35.357Z" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +If `name` is not a valid hashtag, e.g. contains illegal characters or only numbers + +```json +{ + "error": "Validation failed: Tag is invalid" +} +``` + +--- + +## Unfeature a tag {unfeature} + +```http +DELETE https://mastodon.example/api/v1/featured_tags/:id HTTP/1.1 +``` + +Stop promoting a hashtag on your profile. + +**Returns:** empty object\ +**OAuth:** User token + `write:accounts`\ +**Version history:**\ +3.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the FeaturedTag in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The tag was unfeatured. + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +FeaturedTag is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## View suggested tags to feature {#suggestions} + +```http +GET https://mastodon.example/api/v1/featured_tags/suggestions HTTP/1.1 +``` + +Shows up to 10 recently-used tags. + +**Returns:** Array of [Tag]({{< relref "entities/Tag" >}})\ +**OAuth:** User token + `read:accounts`\ +**Version history:**\ +3.0.0 - added + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Truncated results to first and last tag. + +```json +[ + { + "name": "nowplaying", + "url": "https://mastodon.social/tags/nowplaying", + "history": [ + { + "day": "1574553600", + "uses": "200", + "accounts": "31" + }, + { + "day": "1574467200", + "uses": "272", + "accounts": "39" + }, + { + "day": "1574380800", + "uses": "345", + "accounts": "40" + }, + { + "day": "1574294400", + "uses": "366", + "accounts": "46" + }, + { + "day": "1574208000", + "uses": "226", + "accounts": "32" + }, + { + "day": "1574121600", + "uses": "217", + "accounts": "42" + }, + { + "day": "1574035200", + "uses": "214", + "accounts": "34" + } + ] + }, + // ... + { + "name": "mastothemes", + "url": "https://mastodon.social/tags/mastothemes", + "history": [ + { + "day": "1574553600", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574467200", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574380800", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574294400", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574208000", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574121600", + "uses": "0", + "accounts": "0" + }, + { + "day": "1574035200", + "uses": "0", + "accounts": "0" + } + ] + } +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/featured_tags_controller.rb" caption="app/controllers/api/v1/featured_tags_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/featured_tags/suggestions_controller.rb" caption="app/controllers/api/v1/featured_tags/suggestions_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/filters.md b/content/en/methods/filters.md new file mode 100644 index 00000000..0d98e0b0 --- /dev/null +++ b/content/en/methods/filters.md @@ -0,0 +1,540 @@ +--- +title: filters API methods +description: Create and manage filters. +menu: + docs: + weight: 60 + name: filters + parent: methods-accounts + identifier: methods-filters +aliases: [ + "/methods/filters", + "/api/methods/filters", + "/methods/accounts/filters", +] +--- + +{{}} +This page is under construction. +{{}} + +## Server-side (v2) methods {#v2} + +Since Mastodon 3.6, filters can contain multiple keywords and are matched server-side. Clients apply the filter action based on [the status's `filtered` attribute]({{< relref "entities/Status#filtered" >}}). + +--- + +### View all filters {#get} + + + +```http +GET https://mastodon.example/api/v2/filters HTTP/1.1 +``` + +--- + +### View a specific filter {#get-one} + + + +```http +GET https://mastodon.example/api/v2/filters/:id HTTP/1.1 +``` + +--- + +### Create a filter {#create} + + + +```http +POST https://mastodon.example/api/v2/filters HTTP/1.1 +``` + +--- + +### Update a filter {#update} + + + +```http +PUT https://mastodon.example/api/v2/filters/:id HTTP/1.1 +``` + +--- + +### Delete a filter {#delete} + + + +```http +DELETE https://mastodon.example/api/v2/filters/:id HTTP/1.1 +``` + +--- + +### View keywords added to a filter {#keywords-get} + + + +```http +GET https://mastodon.example/api/v2/filters/:id/keywords HTTP/1.1 +``` + +--- + +### View a single keyword within a filter {#keywords-get-one} + + + +```http +GET https://mastodon.example/api/v2/filters/:filter_id/keywords/:id HTTP/1.1 +``` + +--- + +### Add a keyword to a filter {#keywords-create} + + + +```http +POST https://mastodon.example/api/v2/filters/:filter_id/keywords HTTP/1.1 +``` + +--- + +### Edit a keyword within a filter {#keywords-update} + + + +```http +PUT https://mastodon.example/api/v2/filters/keywords/:id HTTP/1.1 +``` + +--- + +### Remove keywords from a filter {#keywords-get} + + + +```http +DELETE https://mastodon.example/api/v2/filters/keywords/:id HTTP/1.1 +``` + +--- + +## Client-side (v1) methods {#v1} + +Prior to Mastodon 3.6, matching filters was done client-size and filters could only contain one phrase to filter against. + +--- + +### View your filters {#get-v1} + +```http +GET https://mastodon.example/api/v1/filters HTTP/1.1 +``` + +**Returns:** List of [V1::Filter]({{< relref "entities/V1_Filter" >}})\ +**OAuth:** User token + `read:filters`\ +**Version history:**\ +2.4.3 - added\ +4.0.0 - deprecated. For compatibility purposes, now returns a List of V1::Filter, with each V1::Filter representing one FilterKeyword (with the `keyword` being presented in the `phrase` attribute) + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Excerpts of various filters in different contexts. + +```json +[ + { + "id": "6191", + "phrase": ":eurovision2019:", + "context": [ + "home" + ], + "whole_word": true, + "expires_at": "2019-05-21T13:47:31.333Z", + "irreversible": false + }, + // ... + { + "id": "5580", + "phrase": "@twitter.com", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": null, + "irreversible": true + }, + // ... +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +### View a single filter {#get-one-v1} + +```http +GET https://mastodon.example/api/v1/filters/:id HTTP/1.1 +``` + +**Returns:** [V1::Filter]({{< relref "entities/V1_Filter" >}})\ +**OAuth:** User token + `read:filters`\ +**Version history:**\ +2.4.3 - added\ +4.0.0 - deprecated. For compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the `keyword` being presented in the `phrase` attribute) + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the FilterKeyword in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "8449", + "phrase": "test", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": "2019-11-26T09:08:06.254Z", + "irreversible": true +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Filter ID does not exist, or is not owned by you + +```json +{ + "error": "Record not found" +} +``` + +--- + +### Create a filter {#create-v1} + +```http +POST https://mastodon.example/api/v1/filters HTTP/1.1 +``` + +**Returns:** [V1::Filter]({{< relref "entities/V1_Filter" >}})\ +**OAuth:** User token + `write:filters`\ +**Version history:**\ +2.4.3 - added\ +3.1.0 - added `account` context to filter in profile views\ +4.0.0 - deprecated. For compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the `keyword` being presented in the `phrase` attribute). This method will create a Filter that contains only one FilterKeyword. The `title` of the Filter and the `keyword` of the FilterKeyword will be set equal to the `phrase` provided. + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +phrase +: {{}} String. The text to be filtered. + +context[] +: {{}} Array of String. Where the filter should be applied. Specify at least one of `home`, `notifications`, `public`, `thread`, `account`. + +irreversible +: Boolean. Should the server irreversibly drop matching entities from home and notifications? Defaults to false. + +whole_word +: Boolean. Should the filter consider word boundaries for this keyword? Defaults to false. + +expires_in +: Integer. Number of seconds from now that the filter should expire. Otherwise, `null` for a filter that doesn't expire. + +#### Response +##### 200: OK + +The newly-created filter will be returned. + +```json +{ + "id": "8449", + "phrase": "test", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": "2019-11-26T09:08:06.254Z", + "irreversible": true +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +If phrase is not provided properly: + +```json +{ + "error": "Validation failed: Phrase can't be blank" +} +``` + +If context is not provided properly: + +```json +{ + "error": "Validation failed: Context can't be blank, Context None or invalid context supplied" +} +``` + +--- + +### Update a filter {#update-v1} + +```http +PUT https://mastodon.example/api/v1/filters/:id HTTP/1.1 +``` + +Replaces a filter's parameters in-place. + +**Returns:** [V1::Filter]({{< relref "entities/V1_Filter" >}})\ +**OAuth:** User token + `write:filters`\ +**Version history:**\ +2.4.3 - added\ +3.1.0 - added `account` context to filter in profile views\ +4.0.0 - deprecated. or compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the `keyword` being presented in the `phrase` attribute). This method will return an error if you attempt to change `expires_in`, `irreversible`, or `context` for a filter with multiple keywords. Changing `phrase` and `whole_word` is always safe. + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the FilterKeyword in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +phrase +: {{}} String. The text to be filtered. + +context[] +: {{}} Array of String. Specify at least one of `home`, `notifications`, `public`, `thread`, `account`. + +irreversible +: Boolean. Should the server irreversibly drop matching entities from home and notifications? Defaults to false. + +whole_word +: Boolean. Should the filter consider word boundaries? Defaults to false. + +expires_in +: Integer. Number of seconds from now that the filter should expire. Otherwise, `null` for a filter that doesn't expire. + +#### Response +##### 200: OK + +Filter updated + +```json +{ + "id": "8449", + "phrase": "test", + "context": [ + "home", + "notifications", + "public", + "thread" + ], + "whole_word": false, + "expires_at": null, + "irreversible": true +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Filter does not exist or is not owned by you + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +If phrase is not provided properly: + +```json +{ + "error": "Validation failed: Phrase can't be blank" +} +``` + +If context is not provided properly: + +```json +{ + "error": "Validation failed: Context can't be blank, Context None or invalid context supplied" +} +``` + +--- + +### Remove a filter {#delete-v1} + +```http +DELETE https://mastodon.example/api/v1/filters/:id HTTP/1.1 +``` + +**Returns:** empty object\ +**OAuth:** User token + `write:filters`\ +**Version history:**\ +2.4.3 - added\ +4.0.0 - deprecated. This method will delete only the FilterKeyword from its parent Filter. To delete the parent Filter, you must use the v2 filters API. + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the SOMETHING in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The filter has been deleted successfully, so an empty object will be returned. + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Filter does not exist or is not owned by you + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/filters_controller.rb" caption="app/controllers/api/v2/filters_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters/keywords_controller.rb" caption="app/controllers/api/v1/filters/keywords_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters/statuses_controller.rb" caption="app/controllers/api/v1/filters/statuses_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters_controller.rb" caption="app/controllers/api/v1/filters_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/follow_requests.md b/content/en/methods/follow_requests.md new file mode 100644 index 00000000..6a694b88 --- /dev/null +++ b/content/en/methods/follow_requests.md @@ -0,0 +1,232 @@ +--- +title: follow_requests API methods +description: View and manage follow requests. +menu: + docs: + weight: 80 + name: follow_requests + parent: methods-accounts + identifier: methods-follow_requests +aliases: [ + "/methods/follow_requests", + "/api/methods/follow_requests", + "/methods/accounts/follow_requests", +] +--- + + + +## View pending follow requests {#get} + +```http +GET https://mastodon.example/api/v1/follow_requests HTTP/1.1 +``` + +**Returns:** Array of [Account]({{< relref "entities/account" >}})\ +**OAuth:** User token + `read:follows` or `follow`\ +**Version history:**\ +0.0.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. Paginate using the HTTP Link header. + +#### Response +##### 200: OK + +Sample call for Accounts that are requesting a follow, with limit=2 + +```json +[ + { + "id":"108119793981152178", + "username":"spcpro3022", + "acct":"spcpro3022@shitposter.club", + "display_name":"spcpro3022", + // ... + }, + { + "id":"106780475844882270", + "username":"EricStoner", + "acct":"EricStoner@freeatlantis.com", + "display_name":"EricStoner", + // ... + } +] +``` + +Because FollowRequest IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Accept follow request {#accept} + +```http +POST https://mastodon.example/api/v1/follow_requests/:account_id/authorize HTTP/1.1 +``` + +**Returns:** [Relationship]({{< relref "entities/relationship" >}})\ +**OAuth:** User token + `write:follows` or `follow`\ +**Version history:**\ +0.0.0 - added\ +3.0.0 - now returns Relationship instead of nothing + +#### Request + +##### Path parameters + +:account_id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Your Relationship with this account should be updated so that you are `followed_by` this account. + +```json +{ + "id": "8889777", + "following": false, + "showing_reblogs": false, + "followed_by": true, + "blocking": false, + "blocked_by": false, + "muting": false, + "muting_notifications": false, + "requested": false, + "domain_blocking": false, + "endorsed": false +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +No pending follow request from that account ID + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Reject follow request {#reject} + +```http +POST https://mastodon.example/api/v1/follow_requests/:account_id/reject HTTP/1.1 +``` + +**Returns:** [Relationship]({{< relref "entities/relationship" >}})\ +**OAuth:** User token + `write:follows` or `follow`\ +**Version history:**\ +0.0.0 - added\ +3.0.0 - now returns Relationship instead of nothing + +#### Request + +##### Path parameters + +:account_id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Your Relationship with this account should be unchanged. + +```json +{ + "id": "8889777", + "following": false, + "showing_reblogs": false, + "followed_by": true, + "blocking": false, + "blocked_by": false, + "muting": false, + "muting_notifications": false, + "requested": false, + "domain_blocking": false, + "endorsed": false +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +No pending follow request from that account ID + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/follow_requests_controller.rb" caption="app/controllers/api/v1/follow_requests_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/followed_tags.md b/content/en/methods/followed_tags.md new file mode 100644 index 00000000..bf9c7768 --- /dev/null +++ b/content/en/methods/followed_tags.md @@ -0,0 +1,126 @@ +--- +title: followed_tags API methods +description: View your followed hashtags. +menu: + docs: + weight: 120 + name: followed_tags + parent: methods-accounts + identifier: methods-followed_tags +aliases: [ + "/methods/followed_tags", + "/api/methods/followed_tags", +] +--- + +## View all followed tags {#get} + +```http +GET https://mastodon.example/api/v1/followed_tags HTTP/1.1 +``` + +**Returns:** Array of [Tag]({{< relref "entities/Tag" >}})\ +**OAuth:** User token + `read:follows`\ +**Version history:**\ +4.0.0 - added\ +4.0.3 - add pagination headers + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 100. + +#### Response +##### 200: OK + +List of followed hashtags + +```json +[ + { + "name": "Test", + "url": "http://mastodon.example/tags/test", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "1", + "uses": "1" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ], + "following": true + }, + // ... +] +``` + +Because TagFollow IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/tags#follow" caption="POST /api/v1/tags/:id/follow" >}} + +{{< page-relref ref="methods/tags#unfollow" caption="POST /api/v1/tags/:id/unfollow" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/followed_tags_controller.rb" caption="app/controllers/api/v1/followed_tags_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/instance.md b/content/en/methods/instance.md index 4494b0b9..26e8db62 100644 --- a/content/en/methods/instance.md +++ b/content/en/methods/instance.md @@ -1,96 +1,195 @@ --- -title: instance -description: Informational endpoint to discover information about a Mastodon website. +title: instance API methods +description: Discover information about a Mastodon website. menu: docs: weight: 70 + name: instance parent: methods identifier: methods-instance +aliases: [ + "/methods/instance", + "/api/methods/instance", +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/instance" title="Fetch instance" >}} -{{< api-method-description >}} + -Information about the server. +## View server information {#v2} -**Returns:** Instance\ +```http +GET https://mastodon.example/api/v2/instance +``` + +Obtain general information about the server. + +**Returns:** [V1::Instance]({{< relref "entities/instance" >}})\ **OAuth:** Public\ **Version history:**\ -1.1.0 - added\ -3.0.0 - requires user token if instance is in whitelist mode\ -3.1.4 - added `invites_enabled` to response +4.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Response +##### 200: OK -```javascript - - "uri": "mastodon.social", +```json +{ + "domain": "mastodon.social", "title": "Mastodon", - "short_description": "Server run by the main developers of the project \"🐘\" It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!", - "description": "Server run by the main developers of the project \"🐘\" It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!", - "email": "staff@mastodon.social", - "version": "3.0.1", - "urls": { - "streaming_api": "wss://mastodon.social" + "version": "4.0.0rc1", + "source_url": "https://github.com/mastodon/mastodon", + "description": "The original server operated by the Mastodon gGmbH non-profit", + "usage": { + "users": { + "active_month": 123122 + } }, - "stats": { - "user_count": 415526, - "status_count": 17085754, - "domain_count": 11834 + "thumbnail": { + "url": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png", + "blurhash": "UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$", + "versions": { + "@1x": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png", + "@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png" + } }, - "thumbnail": "https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png", "languages": [ "en" ], - "registrations": true, - "approval_required": false, - "contact_account": { - "id": "1", - "username": "Gargron", - "acct": "Gargron", - "display_name": "Eugen", - "locked": false, - "bot": false, - "created_at": "2016-03-16T14:34:26.392Z", - "note": "

Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.

", - "url": "https://mastodon.social/@Gargron", - "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg", - "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg", - "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png", - "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png", - "followers_count": 317112, - "following_count": 453, - "statuses_count": 60903, - "last_status_at": "2019-11-26T21:14:44.522Z", - "emojis": [], - "fields": [ - { - "name": "Patreon", - "value": "https://www.patreon.com/mastodon", - "verified_at": null - }, - { - "name": "Homepage", - "value": "https://zeonfederated.com", - "verified_at": "2019-07-15T18:29:57.191+00:00" - } - ] - } + "configuration": { + "urls": { + "streaming": "wss://mastodon.social" + }, + "accounts": { + "max_featured_tags": 10 + }, + "statuses": { + "max_characters": 500, + "max_media_attachments": 4, + "characters_reserved_per_url": 23 + }, + "media_attachments": { + "supported_mime_types": [ + "image/jpeg", + "image/png", + "image/gif", + "image/heic", + "image/heif", + "image/webp", + "video/webm", + "video/mp4", + "video/quicktime", + "video/ogg", + "audio/wave", + "audio/wav", + "audio/x-wav", + "audio/x-pn-wave", + "audio/vnd.wave", + "audio/ogg", + "audio/vorbis", + "audio/mpeg", + "audio/mp3", + "audio/webm", + "audio/flac", + "audio/aac", + "audio/m4a", + "audio/x-m4a", + "audio/mp4", + "audio/3gpp", + "video/x-ms-asf" + ], + "image_size_limit": 10485760, + "image_matrix_limit": 16777216, + "video_size_limit": 41943040, + "video_frame_rate_limit": 60, + "video_matrix_limit": 2304000 + }, + "polls": { + "max_options": 4, + "max_characters_per_option": 50, + "min_expiration": 300, + "max_expiration": 2629746 + }, + "translation": { + "enabled": true + } + }, + "registrations": { + "enabled": false, + "approval_required": false, + "message": null + }, + "contact": { + "email": "staff@mastodon.social", + "account": { + "id": "1", + "username": "Gargron", + "acct": "Gargron", + "display_name": "Eugen 💀", + "locked": false, + "bot": false, + "discoverable": true, + "group": false, + "created_at": "2016-03-16T00:00:00.000Z", + "note": "

Founder, CEO and lead developer @Mastodon, Germany.

", + "url": "https://mastodon.social/@Gargron", + "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count": 133026, + "following_count": 311, + "statuses_count": 72605, + "last_status_at": "2022-10-31", + "noindex": false, + "emojis": [], + "fields": [ + { + "name": "Patreon", + "value": "https://www.patreon.com/mastodon", + "verified_at": null + } + ] + } + }, + "rules": [ + { + "id": "1", + "text": "Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id": "3", + "text": "No incitement of violence or promotion of violent ideologies" + }, + { + "id": "4", + "text": "No harassment, dogpiling or doxxing of other users" + }, + { + "id": "5", + "text": "No content illegal in Germany" + }, + { + "id": "7", + "text": "Do not share intentionally false or misleading information" + } + ] } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/instance/peers" title="List of connected domains" >}} -{{< api-method-description >}} + + +--- + +## List of connected domains {#peers} + +```http +GET https://mastodon.example/api/v1/instance/peers HTTP/1.1 +``` Domains that this instance is aware of. @@ -100,43 +199,72 @@ Domains that this instance is aware of. 2.1.2 - added\ 3.0.0 - requires user token if instance is in whitelist mode -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Headers -```javascript +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response + +##### 200: OK + +```json ["tilde.zone","mspsocial.net",...,"conf.tube"] ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/instance/activity" title="Weekly activity" >}} -{{< api-method-description >}} + +##### 401: Unauthorized + +If the instance is in whitelist mode and the Authorization header is missing or invalid + +```json +{ + "error": "This API requires an authenticated user" +} +``` + +--- + +## Weekly activity {#activity} + +```http +GET https://mastodon.example/api/v1/instance/activity HTTP/1.1 +``` Instance activity over the last 3 months, binned weekly. -**Returns:** Array of Activity\ +**Returns:** Array of Hash\ **OAuth:** Public\ **Version history:**\ 2.1.2 - added\ 3.0.0 - requires user token if instance is in whitelist mode -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Headers -``` +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Each hash in the array will contain the following attributes: + +week +: String (UNIX Timestamp). Midnight at the first day of the week. + +statuses +: String (cast from an integer). The number of Statuses created since the week began. + +logins +: String (cast from an integer). The number of user logins since the week began. + +registrations +: String (cast from an integer). The number of user registrations since the week began. + +```json [ { "week": "1574640000", @@ -212,9 +340,314 @@ Instance activity over the last 3 months, binned weekly. } ] ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} + +##### 401: Unauthorized + +If the instance is in whitelist mode and the Authorization header is missing or invalid + +```json +{ + "error": "This API requires an authenticated user" +} +``` + +--- + +## List of rules {#rules} +```http +GET https://mastodon.example/api/v1/instance/rules HTTP/1.1 +``` + +Rules that the users of this service should follow. + +**Returns:** Array of [Rule]({{< relref "entities/rule" >}})\ +**OAuth:** Public\ +**Version history:**\ +3.4.0 - added + +#### Response +##### 200: OK + +```json +[ + { + "id": "1", + "text": "Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id": "2", + "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id": "3", + "text": "No incitement of violence or promotion of violent ideologies" + }, + { + "id": "4", + "text": "No harassment, dogpiling or doxxing of other users" + }, + { + "id": "5", + "text": "No content illegal in Germany" + }, + { + "id": "7", + "text": "Do not share intentionally false or misleading information" + } +] +``` + +--- + +## View moderated servers {#domain_blocks} + +```http +GET https://mastodon.example/api/v1/instance/domain_block HTTP/1.1 +``` + +Obtain a list of domains that have been blocked. + +**Returns:** Array of [DomainBlock]({{< relref "entities/DomainBlock" >}})\ +**OAuth:** Public, or User token if limited to users\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The complete list of domains blocked by this instance + +```json +[ + { + "domain":"birb.elfenban.de", + "digest":"5d2c6e02a0cced8fb05f32626437e3d23096480b47efbba659b6d9e80c85d280", + "severity":"suspend", + "comment":"Third-party bots" + }, + { + "domain":"birdbots.leptonics.com", + "digest":"ce019d8d32cce8e369ac4367f4dc232103e6f489fbdd247fb99f9c8a646078a4", + "severity":"suspend", + "comment":"Third-party bots" + }, + // ... +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header, if the admin has chosen to show domain blocks to users. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +The admin has chosen to show domain blocks to no one. The response body is empty; only the HTTP 404 error code is relevant. + +```text +``` + +--- + +## View extended description {#extended_description} + +```http +GET https://mastodon.example/api/v1/example HTTP/1.1 +``` + +Obtain an extended description of this server + +**Returns:** [ExtendedDescription]({{< relref "entities/ExtendedDescription" >}})\ +**OAuth:** Public\ +**Version history:**\ +4.0.0 - added + +#### Response +##### 200: OK + +```json +{ + "updated_at":"2022-11-03T04:09:07Z", + "content":"

For inquiries not related specifically to the operation of this server, such as press inquiries, please contact press@joinmastodon.org.

\n\n

Funding

\n\n

This server is crowdfunded by Patreon donations. For a list of sponsors, see joinmastodon.org.

\n\n

Reporting and moderation

\n\n

When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.

\n\n

We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.

\n\n

Impressum

\n\n

Mastodon gGmbH
\nMühlenstraße 8a
\n14167 Berlin
\nGermany

\n\n

E-Mail-Adresse: hello@joinmastodon.org

\n\n

Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)

\n\n

Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260

\n\n

Handelsregister
\nGeführt bei: Amtsgericht Charlottenburg
\nNummer: HRB 230086 B

\n" +} +``` + +--- + +## (DEPRECATED) View server information (V1) {#v1} + +```http +GET https://mastodon.example/api/v1/instance HTTP/1.1 +``` + +Obtain general information about the server. + +**Returns:** [V1::Instance]({{< relref "entities/instance" >}})\ +**OAuth:** Public\ +**Version history:**\ +1.1.0 - added\ +3.0.0 - requires user token if instance is in whitelist mode\ +3.1.4 - added `invites_enabled` to response\ +3.4.0 - added `rules`\ +3.4.2 - added `configuration`\ +4.0.0 - deprecated. added `configuration[accounts]`. + +#### Response + +##### 200: OK + +```json +{ + "uri":"mastodon.social", + "title":"Mastodon", + "short_description":"The original server operated by the Mastodon gGmbH non-profit", + "description":"", + "email":"staff@mastodon.social", + "version":"3.5.3", + "urls":{ + "streaming_api":"wss://mastodon.social" + }, + "stats":{ + "user_count":812303, + "status_count":38151616, + "domain_count":25255 + }, + "thumbnail":"https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png", + "languages":[ + "en" + ], + "registrations":false, + "approval_required":false, + "invites_enabled":true, + "configuration":{ + "statuses":{ + "max_characters":500, + "max_media_attachments":4, + "characters_reserved_per_url":23 + }, + "media_attachments":{ + "supported_mime_types":[ + "image/jpeg", + "image/png", + "image/gif", + "image/webp", + "video/webm", + "video/mp4", + "video/quicktime", + "video/ogg", + "audio/wave", + "audio/wav", + "audio/x-wav", + "audio/x-pn-wave", + "audio/vnd.wave", + "audio/ogg", + "audio/vorbis", + "audio/mpeg", + "audio/mp3", + "audio/webm", + "audio/flac", + "audio/aac", + "audio/m4a", + "audio/x-m4a", + "audio/mp4", + "audio/3gpp", + "video/x-ms-asf" + ], + "image_size_limit":10485760, + "image_matrix_limit":16777216, + "video_size_limit":41943040, + "video_frame_rate_limit":60, + "video_matrix_limit":2304000 + }, + "polls":{ + "max_options":4, + "max_characters_per_option":50, + "min_expiration":300, + "max_expiration":2629746 + } + }, + "contact_account":{ + "id":"1", + "username":"Gargron", + "acct":"Gargron", + "display_name":"Eugen", + "locked":false, + "bot":false, + "discoverable":true, + "group":false, + "created_at":"2016-03-16T00:00:00.000Z", + "note":"\u003cp\u003eFounder, CEO and lead developer \u003cspan class=\"h-card\"\u003e\u003ca href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\"\u003e@\u003cspan\u003eMastodon\u003c/span\u003e\u003c/a\u003e\u003c/span\u003e, Germany.\u003c/p\u003e", + "url":"https://mastodon.social/@Gargron", + "avatar":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "avatar_static":"https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg", + "header":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "header_static":"https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg", + "followers_count":118944, + "following_count":305, + "statuses_count":72309, + "last_status_at":"2022-08-24", + "emojis":[ + + ], + "fields":[ + { + "name":"Patreon", + "value":"\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e", + "verified_at":null + } + ] + }, + "rules":[ + { + "id":"1", + "text":"Sexually explicit or violent media must be marked as sensitive when posting" + }, + { + "id":"2", + "text":"No racism, sexism, homophobia, transphobia, xenophobia, or casteism" + }, + { + "id":"3", + "text":"No incitement of violence or promotion of violent ideologies" + }, + { + "id":"4", + "text":"No harassment, dogpiling or doxxing of other users" + }, + { + "id":"5", + "text":"No content illegal in Germany" + }, + { + "id":"7", + "text":"Do not share intentionally false or misleading information" + } + ] +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances_controller.rb" caption="app/controllers/api/v1/instances_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances/activity_controller.rb" caption="app/controllers/api/v1/instances/activity_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances/peers_controller.rb" caption="app/controllers/api/v1/instances/peers_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/instances/rules_controller.rb" caption="app/controllers/api/v1/instances/rules_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/instance/directory.md b/content/en/methods/instance/directory.md deleted file mode 100644 index 2614df86..00000000 --- a/content/en/methods/instance/directory.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: directory -description: A directory of profiles that your website is aware of. -menu: - docs: - weight: 20 - parent: methods-instance ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/directory" title="View profile directory" >}} -{{< api-method-description >}} - -List accounts visible in the directory. - -**Returns:** Array of Account\ -**OAuth:** Public\ -**Version history:**\ -3.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="offset" type="string" required=false >}} -How many accounts to skip before returning results. Default 0. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -How many accounts to load. Default 40. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="order" type="string" required=false >}} -`active` to sort by most recently posted statuses \(default\) or `new` to sort by most recently created profiles. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="local" type="boolean" required=false >}} -Only return local accounts. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Sample results with limit=2 -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "id": "796927", - "username": "eternalNo3", - "acct": "eternalNo3@best-friends.chat", - "display_name": "ESD＠┓（谷）┏", - ... - }, - { - "id": "787648", - "username": "ariel", - "acct": "ariel@best-friends.chat", - "display_name": "あやっしー🧜🏻‍♀️", - ... - } -] -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/instance/trends.md b/content/en/methods/instance/trends.md deleted file mode 100644 index e0475916..00000000 --- a/content/en/methods/instance/trends.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: trends -description: View hashtags that are currently being used more frequently than usual. -menu: - docs: - weight: 10 - parent: methods-instance ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/trends" title="Trending tags" >}} -{{< api-method-description >}} - -Tags that are being used more frequently within the past week. - -**Returns:** Array of Tag with History\ -**OAuth:** Public\ -**Version history:**\ -3.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="number" required=false >}} -Maximum number of results to return. Defaults to 10. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "name": "hola", - "url": "https://mastodon.social/tags/hola", - "history": [ - { - "day": "1574726400", - "uses": "13", - "accounts": "10" - }, - ... - ] - }, - { - "name": "SaveDotOrg", - "url": "https://mastodon.social/tags/SaveDotOrg", - "history": [ - { - "day": "1574726400", - "uses": "9", - "accounts": "9" - }, - ... - ] - }, - { - "name": "introduction", - "url": "https://mastodon.social/tags/introduction", - "history": [ - { - "day": "1574726400", - "uses": "15", - "accounts": "14" - }, - ... - ] - }, - ... -] -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/lists.md b/content/en/methods/lists.md new file mode 100644 index 00000000..d80560c3 --- /dev/null +++ b/content/en/methods/lists.md @@ -0,0 +1,580 @@ +--- +title: lists API methods +description: >- + View and manage lists. See also: /api/v1/timelines/list/id for loading a list + timeline. +menu: + docs: + weight: 20 + name: lists + parent: methods-timelines + identifier: methods-lists +aliases: [ + "/methods/lists", + "/api/methods/lists", + "/methods/timelines/lists", +] +--- + + + +## View your lists {#get} + +```http +GET https://mastodon.example/api/v1/lists HTTP/1.1 +``` + +Fetch all lists that the user owns. + +**Returns:** Array of [List]({{< relref "entities/list" >}})\ +**OAuth:** User token + `read:lists`\ +**Version history:**\ +2.1.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Use `id` as a parameter for related API calls. + +```json +[ + { + "id": "12249", + "title": "Friends", + "replies_policy": "followed" + }, + { + "id": "13585", + "title": "test", + "replies_policy": "list" + } +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Show a single list {#get-one} + +```http +GET https://mastodon.example/api/v1/lists/:id HTTP/1.1 +``` + +Fetch the list with the given ID. Used for verifying the title of a list, and which replies to show within that list. + +**Returns:** [List]({{< relref "entities/list" >}})\ +**OAuth:** User token + `read:lists`\ +**Version history:**\ +2.1.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the List in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The list 12249 exists and is owned by you + +```json +{ + "id": "12249", + "title": "Friends", + "replies_policy": "followed" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +List does not exist or is not owned by you + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Create a list {#create} + +```http +POST https://mastodon.example/api/v1/lists HTTP/1.1 +``` + +Create a new list. + +**Returns:** [List]({{< relref "entities/list" >}})\ +**OAuth:** User token + `write:lists`\ +**Version history:**\ +2.1.0 - added\ +3.3.0 - added `replies_policy` + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +title +: {{}} String. The title of the list to be created. + +replies_policy +: String. One of `followed`, `list`, or `none`. Defaults to `list`. + +#### Response +##### 200: OK + +A sample list was created with a `title` of "test". + +```json +{ + "id": "13585", + "title": "test", + "replies_policy": "list" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +If the title is missing: + +```json +{ + "error": "Validation failed: Title can't be blank" +} +``` + +If the replies_policy is not understood: + +```json +{ + "error": "'some' is not a valid replies_policy" +} +``` +--> + +--- + +## Update a list {#update} + +```http +PUT https://mastodon.example/api/v1/lists/:id HTTP/1.1 +``` + +Change the title of a list, or which replies to show. + +**Returns:** [List]({{< relref "entities/list" >}})\ +**OAuth:** User token + `write:lists`\ +**Version history:**\ +2.1.0 - added\ +3.3.0 - added `replies_policy` + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the List in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +title +: {{}} String. The title of the list to be created. + +replies_policy +: String. One of `followed`, `list`, or `none`. Defaults to `list`. + +#### Response +##### 200: OK + +The `title` of list 13585 was successfully updated to "testing" + +```json +{ + "id": "13585", + "title": "test", + "replies_policy": "list" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +If the `title` is missing: + +```json +{ + "error": "Validation failed: Title can't be blank" +} +``` + +If the `replies_policy` is not understood: + +```json +{ + "error": "'some' is not a valid replies_policy" +} +``` + +--- + +## Delete a list {#delete} + +```http +DELETE https://mastodon.example/api/v1/lists/:id HTTP/1.1 +``` + +**Returns:** empty object\ +**OAuth:** User token + `write:lists`\ +**Version history:**\ +2.1.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the List in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +List was successfully deleted + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +List does not exist or is not owned by you + + +```json +{ + "error": "Record not found" +} +``` + +--- + +## View accounts in a list {#accounts} + +```http +GET https://mastodon.example/api/v1/lists/:id/accounts HTTP/1.1 +``` + +**Returns:** Array of [Account]({{< relref "entities/account" >}})\ +**OAuth:** User token + `read:lists`\ +**Version history:**\ +2.1.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the List in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results. Defaults to 40. Max 40. Set to 0 in order to get all accounts without pagination. + +#### Response +##### 200: OK + +```json +[ + { + "id": "952529", + "username": "alayna", + "acct": "alayna@desvox.es", + // ... + }, + { + "id": "917388", + "username": "cole", + "acct": "cole@be.cutewith.me", + // ... + }, + { + "id": "869022", + "username": "alayna", + "acct": "alayna@be.cutewith.me", + // ... + }, + { + "id": "832844", + "username": "a9", + "acct": "a9@broadcast.wolfgirl.engineering", + // ... + }, + { + "id": "482403", + "username": "amic", + "acct": "amic@nulled.red", + // ... + } +] +``` + +Because you do not know beforehand which Accounts are included in a List, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +List does not exist or is not owned by you. + + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Add accounts to a list {#accounts-add} + +```http +POST https://mastodon.example/api/v1/lists/:id/accounts HTTP/1.1 +``` + +Add accounts to the given list. Note that the user must be following these accounts. + +**Returns:** empty object\ +**OAuth:** User token + `write:lists`\ +**Version history:**\ +2.1.0 - added + +### Request + +##### Path parameters + +:id +: {{}} String. The ID of the SOMETHING in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +account_ids[] +: {{}} Array of String. The accounts that should be added to the list. + +#### Response +##### 200: OK + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +You are not following a given account ID, or you do not own the list ID, or list/account ID does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +An Account with one of the provided IDs is already in the list + +```json +{ + "error": "Validation failed: Account has already been taken" +} +``` + +--- + +## Remove accounts from list {#accounts-remove} + +```http +DELETE https://mastodon.example/api/v1/lists/:id/accounts HTTP/1.1 +``` + +Remove accounts from the given list. + +**Returns:** empty object\ +**OAuth:** User token + `write:lists`\ +**Version history:**\ +2.1.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the SOMETHING in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +account_ids[] +: {{}} Array of String. The accounts that should be removed from the list. + +#### Response +##### 200: OK + +Account was successfully removed from the list, or it was already not in the list. + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +SOMETHING is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/accounts#lists" caption="GET /api/v1/accounts/:id/lists" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/lists_controller.rb" caption="app/controllers/api/v1/lists_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/lists/accounts_controller.rb" caption="app/controllers/api/v1/lists/accounts_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/markers.md b/content/en/methods/markers.md new file mode 100644 index 00000000..dd386e71 --- /dev/null +++ b/content/en/methods/markers.md @@ -0,0 +1,145 @@ +--- +title: markers API methods +description: Save and restore your position in timelines. +menu: + docs: + weight: 30 + name: markers + parent: methods-timelines + identifier: methods-markers +aliases: [ + "/methods/markers", + "/api/methods/markers", + "/methods/timelines/markers", +] +--- + + + +## Get saved timeline positions {#get} + +```http +GET https://mastodon.example/api/v1/markers HTTP/1.1 +``` + +**Returns:** Hash of timeline key and associated [Marker]({{< relref "entities/Marker" >}})\ +**OAuth:** User token + `read:statuses`\ +**Version history:**\ +3.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +timeline[] +: {{}} Array of String. Specify the timeline(s) for which markers should be fetched. Possible values: `home`, `notifications`. If not provided, an empty object will be returned. + +#### Response +##### 200: OK + +timeline[] = ["home", "notifications"] + +```json +{ + "notifications": { + "last_read_id": "35098814", + "version": 361, + "updated_at": "2019-11-26T22:37:25.239Z" + }, + "home": { + "last_read_id": "103206604258487607", + "version": 468, + "updated_at": "2019-11-26T22:37:25.235Z" + } +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Save your position in a timeline {#create} + +```http +POST https://mastodon.example/api/v1/markers HTTP/1.1 +``` + +**Returns:** [Marker]({{< relref "entities/marker" >}})\ +**OAuth:** User token + `write:statuses`\ +**Version history:**\ +3.0.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +home[last_read_id] +: String. ID of the last status read in the home timeline. + +notifications[last_read_id] +: String. ID of the last notification read. + +#### Response +##### 200: OK + +Calling this API with home[last_read_id] causes a marker to be created for the home timeline. + +```json +{ + "home": { + "last_read_id": "103194548672408537", + "version": 462, + "updated_at": "2019-11-24T19:39:39.337Z" + } +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +### 409: Conflict + +If object is stale while being updated, an error will occur. + +```json +{ + "error": "Conflict during update, please try again" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/timelines#home" caption="GET /api/v1/timelines/home (with `min_id` or `since_id` parameter)" >}} + +{{< page-relref ref="methods/notifications#get" caption="GET /api/v1/notifications (with `min_id` or `since_id` parameter)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/markers_controller.rb" caption="app/controllers/api/v1/markers_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/media.md b/content/en/methods/media.md new file mode 100644 index 00000000..10d14451 --- /dev/null +++ b/content/en/methods/media.md @@ -0,0 +1,496 @@ +--- +title: media API methods +description: >- + Attach media to authored statuses. See Using Mastodon > Posting toots > + Attachments for more information about size and format limits. +menu: + docs: + weight: 10 + name: media + parent: methods-statuses + identifier: methods-media +aliases: [ + "/methods/media", + "/api/methods/media", + "/methods/statuses/media", +] +--- + + + +## Upload media as an attachment (async) {#v2} + +```http +POST https://mastodon.example/api/v2/media HTTP/1.1 +``` + +Creates a media attachment to be used with a new status. The full sized media will be processed asynchronously in the background for large uploads. + +**Returns:** [MediaAttachment]({{< relref "entities/MediaAttachment" >}}), but without a URL\ +**OAuth:** User token + `write:media`\ +**Version history:**\ +3.1.3 - added\ +3.2.0 - add `thumbnail` parameter\ +4.0.0 - Smaller media formats (image) will be processed synchronously and return 200 instead of 202. Larger media formats (video, gifv, audio) will continue to be processed asynchronously and return 202. + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +file +: {{}} Object. The file to be attached, encoded using multipart form data. The file must have a MIME type. + +thumbnail +: Object. The custom thumbnail of the media to be attached, encoded using multipart form data. + +description +: String. A plain-text description of the media, for accessibility purposes. + +focus +: String. Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0. See [Focal points for cropping media thumbnails]({{< relref "api/guidelines#focal-points" >}}) for more information. + +#### Response + +##### 200: OK + +MediaAttachment was created successfully, and the full-size file was processed synchronously. + +```json +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.42, + "y": 0.69 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +##### 202: Accepted + +MediaAttachment was created successfully, but the full-size file is still processing. Note that the MediaAttachment's `url` will still be null, as the media is still being processed in the background. However, the `preview_url` should be available. Use [`GET /api/v1/media/:id`](#get) to check the status of the media attachment. + +```json +{ + "id": "22348641", + "type": "image", + "url": null, + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/cebc6d51be03e509.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.69, + "y": 0.42 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +File or file type is unsupported or invalid + +```json +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` + +##### 500: Server error + +Could not generate a thumbnail for the attachment + +```json +{ + "error": "Error processing thumbnail for uploaded media" +} +``` + +--- + +## Get media attachment {#get} + +```http +GET https://mastodon.example/api/v1/media/:id HTTP/1.1 +``` + +Get a media attachment, before it is attached to a status and posted, but after it is accepted for processing. Use this method to check that the full-sized media has finished processing. + +**Returns:** [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\ +**OAuth:** User token + `write:media`\ +**Version history:**\ +3.1.3 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the MediaAttachment in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +The media file was processed, and a `url` to the processed media is available. + +```json +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.42, + "y": 0.69 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api, but updated", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +##### 206: Partial content + +The media attachment is still being processed + +```json + +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +MediaAttachment is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +There was an error processing the media attachment + + +```json +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` + +--- + +## Update media attachment {#update} + +```http +PUT https://mastodon.example/api/v1/media/:id HTTP/1.1 +``` + +Update a MediaAttachment's parameters, before it is attached to a status and posted. + +**Returns:** [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\ +**OAuth:** User token + `write:media`\ +**Version history:**\ +0.0.0 - added\ +2.3.0 - add `focus` parameter\ +3.2.0 - added `thumbnail` + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the MediaAttachment in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +thumbnail +: Object. The custom thumbnail of the media to be attached, encoded using multipart form data. + +description +: String. A plain-text description of the media, for accessibility purposes. + +focus +: String. Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0. See [Focal points for cropping media thumbnails]({{< relref "api/guidelines#focal-points" >}}) for more information. + +#### Response + +##### 200: OK + +Attachment with an updated `description` + +```json +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.42, + "y": 0.69 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api, but updated", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Attachment is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` + +--- + +## (DEPRECATED) Upload media as an attachment {#v1} + +```http +POST https://mastodon.example/api/v1/media HTTP/1.1 +``` + +Creates an attachment to be used with a new status. This method will return after the full sized media is done processing. + +**Returns:** [MediaAttachment]({{< relref "entities/MediaAttachment" >}})\ +**OAuth:** User token + `write:media`\ +**Version history:**\ +0.0.0 - added\ +2.3.0 - add `focus` parameter\ +3.1.3 - deprecated in favor of [POST /api/v2/media](#v2), which is equal to v1 in all aspects, except it returns HTTP 202, and the returned JSON object has a url of null. This is because while the thumbnail is prepared synchronously, the full version of the media attachment will be processed in the background.\ +3.2.0 - add `thumbnail` parameter + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +file +: {{}} Object. The file to be attached, encoded using multipart form data. The file must have a MIME type. + +thumbnail +: Object. The custom thumbnail of the media to be attached, encoded using multipart form data. + +description +: String. A plain-text description of the media, for accessibility purposes. + +focus +: String. Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0. See [Focal points for cropping media thumbnails]({{< relref "api/guidelines#focal-points" >}}) for more information. + +#### Response +##### 200: OK + +Attachment created successfully. Note that the MediaAttachment will be created even if the file is not understood correctly due to failed processing. + +Sample response for a correct file: + +```json +{ + "id": "22348641", + "type": "image", + "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/cebc6d51be03e509.jpeg", + "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/cebc6d51be03e509.jpeg", + "remote_url": null, + "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", + "meta": { + "focus": { + "x": -0.69, + "y": 0.42 + }, + "original": { + "width": 640, + "height": 480, + "size": "640x480", + "aspect": 1.3333333333333333 + }, + "small": { + "width": 461, + "height": 346, + "size": "461x346", + "aspect": 1.3323699421965318 + } + }, + "description": "test uploaded via api", + "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" +} +``` + +Sample response for an incorrect file, which results in a "missing" url: + +```json +{ + "id": "22348456", + "type": "unknown", + "url": "https://mastodon.social/files/original/missing.png", + "preview_url": "https://mastodon.social/files/small/missing.png", + "remote_url": null, + "text_url": "https://mastodon.social/media/Ao2nvQoQNHROpKgEyoA", + "meta": { + "focus": { + "x": -0.69, + "y": 0.42 + } + }, + "description": "test uploaded via api", + "blurhash": null +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +File or file type is unsupported or invalid + +```json +{ + "error": "Validation failed: File content type is invalid, File is invalid" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/instance" caption="GET /api/v2/instance (for obtaining configuration limits)">}} + +{{< page-relref ref="entities/instance#media_attachments" caption="Instance#configuration[media_attachments]">}} + +{{< page-relref ref="api/guidelines#focal-points" caption="Focal points for cropping media thumbnails" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/media_controller.rb" caption="app/controllers/api/v1/media_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/media_controller.rb" caption="app/controllers/api/v2/media_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/mutes.md b/content/en/methods/mutes.md new file mode 100644 index 00000000..459a7ed5 --- /dev/null +++ b/content/en/methods/mutes.md @@ -0,0 +1,103 @@ +--- +title: mutes API methods +description: View your mutes. See also accounts/:id/{mute,unmute} +menu: + docs: + weight: 30 + name: mutes + parent: methods-accounts + identifier: methods-mutes +aliases: [ + "/methods/mutes", + "/api/methods/mutes", + "/methods/accounts/mutes", +] +--- + + + +## View muted accounts {#get} + +```http +GET https://mastodon.example/api/v1/mutes HTTP/1.1 +``` + +Accounts the user has muted. + +**Returns:** Array of [Account]({{}})\ +**OAuth:** User token + `read:mutes` or `follow`\ +**Version history:**\ +0.0.0 - added\ +3.3.0 - added `mute_expires_at`. both `min_id` and `max_id` can be used at the same time now + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +since_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +min_id +: **Internal parameter.** Use HTTP `Link` header for pagination. + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +Sample response with limit=2. + +```json +[ + { + "id": "963076", + "username": "Simia91", + "acct": "Simia91", + "display_name": "", + // ... + }, + { + "id": "1001524", + "username": "hakogamae", + "acct": "hakogamae", + "display_name": "Hakogamae 🔞", + // ... + } +] +``` + +Because Mute IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. + +```http +Link: ; rel="next", ; rel="prev" +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/accounts#mute" caption="POST /api/v1/accounts/:id/mute" >}} + +{{< page-relref ref="methods/accounts#unmute" caption="POST /api/v1/accounts/:id/unmute" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/mutes_controller.rb" caption="app/controllers/api/v1/mutes_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index a5d4ef77..92eb4f9e 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -1,66 +1,101 @@ --- -title: notifications +title: notifications API methods description: Receive notifications for activity on your account or statuses. menu: docs: weight: 50 + name: notifications parent: methods identifier: methods-notifications +aliases: [ + "/methods/notifications", + "/api/methods/notifications", +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/notifications" title="Get all notifications" >}} -{{< api-method-description >}} + + +## Get all notifications {#get} + +```http +GET https://mastodon.example/api/v1/notifications HTTP/1.1 +``` Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values. -**Returns:** Array of Notification\ +Types to filter include: +- `mention` = Someone mentioned you in their status +- `status` = Someone you enabled notifications for has posted a status +- `reblog` = Someone boosted one of your statuses +- `follow` = Someone followed you +- `follow_request` = Someone requested to follow you +- `favourite` = Someone favourited one of your statuses +- `poll` = A poll you have voted in or created has ended +- `update` = A status you interacted with has been edited +- `admin.sign_up` = Someone signed up (optionally sent to admins) +- `admin.report` = A new report has been filed + +**Returns:** Array of [Notification]({{< relref "entities/Notification" >}})\ **OAuth:** User token + `read:notifications`\ **Version history:**\ 0.0.0 - added\ -2.6.0 - add `min_id`\ -2.9.0 - add `account_id`\ -3.1.0 - add `follow_request` type +2.6.0 - added `min_id`\ +2.9.0 - added `account_id`\ +3.1.0 - added `follow_request` type\ +3.3.0 - added `status` type; both `min_id` and `max_id` can be used at the same time now\ +3.5.0 - added `types`; add `update` and `admin.sign_up` types\ +4.0.0 - added `admin.report` type -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than this ID -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Return results newer than this ID -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than this ID -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results to return \(default 20\) -{{< endapi-method-parameter >}} -{{< api-method-parameter name="exclude_types" type="array" required=false >}} -Array of types to exclude \(`follow`, `favourite`, `reblog`, `mention`, `poll`, `follow_request`\) -{{< endapi-method-parameter >}} -{{< api-method-parameter name="account_id" type="string" required=false >}} -Return only notifications received from this account -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request -Sample call with limit=2. Use the Link header for pagination -{{< endapi-method-response-example-description >}} +##### Headers +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. -```javascript +##### Query parameters + +max_id +: String. Return results older than this ID + +since_id +: String. Return results newer than this ID + +min_id +: String. Return results immediately newer than this ID + +limit +: Integer. Maximum number of results to return. Default: 20. + +types[] +: Array of String. Types to include in the result. + +exclude_types[] +: Array of String. Types to exclude from the results. + +account_id +: String. Return only notifications received from the specified account. + +#### Response + +Sample call with limit=2. + +```http +GET https://mastodon.social/api/v1/notifications?limit=2 HTTP/1.1 +Authorization: Bearer xxx +``` + +##### 200: OK + +The response body contains one page of notifications. You can use the HTTP Link header for further pagination. + +```http Link: ; rel="next", ; +``` +```json [ { "id": "34975861", @@ -70,23 +105,23 @@ Link: ; rel="next" "id": "971724", "username": "zsc", "acct": "zsc", - ... + // ... }, "status": { "id": "103186126728896492", "created_at": "2019-11-23T07:49:01.940Z", "in_reply_to_id": "103186038209478945", "in_reply_to_account_id": "14715", - ... + // ... "content": "

@trwnh sup!

", - ... + // ... "account": { "id": "971724", "username": "zsc", "acct": "zsc", - ... + // ... }, - ... + // ... "mentions": [ { "id": "14715", @@ -95,7 +130,7 @@ Link: ; rel="next" "acct": "trwnh" } ], - ... + // ... } }, { @@ -106,74 +141,69 @@ Link: ; rel="next" "id": "297420", "username": "haskal", "acct": "haskal@cybre.space", - ... + // ... }, "status": { "id": "103186046267791694", "created_at": "2019-11-23T07:28:34.210Z", "in_reply_to_id": "103186044372624124", "in_reply_to_account_id": "297420", - ... + // ... "account": { "id": "14715", "username": "trwnh", "acct": "trwnh", - ... + // ... } } } ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/notifications/:id" title="Get a single notification" >}} -{{< api-method-description >}} + +--- + +## Get a single notification {#get-one} + +```http +GET https://mastodon.example/api/v1/notification/:id HTTP/1.1 +``` View information about a notification with a given ID. -**Returns:** Notification\ +**Returns:** [Notification]({{< relref "entities/Notification" >}})\ **OAuth:** User token + `read:notifications`\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the notification in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Notification in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response + +##### 200: OK A single Notification -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "34975861", "type": "mention", @@ -182,23 +212,23 @@ A single Notification "id": "971724", "username": "zsc", "acct": "zsc", - ... + // ... }, "status": { "id": "103186126728896492", "created_at": "2019-11-23T07:49:01.940Z", "in_reply_to_id": "103186038209478945", "in_reply_to_account_id": "14715", - ... + // ... "content": "

@trwnh sup!

", - ... + // ... "account": { "id": "971724", "username": "zsc", "acct": "zsc", - ... + // ... }, - ... + // ... "mentions": [ { "id": "14715", @@ -207,29 +237,28 @@ A single Notification "acct": "trwnh" } ], - ... + // ... } -}, +} ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/notifications/clear" title="Dismiss all notifications" >}} -{{< api-method-description >}} + +--- + +## Dismiss all notifications {#clear} + +```http +POST https://mastodon.example/api/v1/notifications/clear HTTP/1.1 +``` Clear all notifications from the server. @@ -238,147 +267,131 @@ Clear all notifications from the server. **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Headers -Notifications successfully cleared -{{< endapi-method-response-example-description >}} +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +#### Response -```javascript +##### 200: OK + +Notifications successfully cleared. + +```json {} ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/notifications/:id/dismiss" title="Dismiss a single notification" >}} -{{< api-method-description >}} -Clear a single notification from the server. +--- + +## Dismiss a single notification {#dismiss} + +```http +POST https://mastodon.example/api/v1/notifications/:id/dismiss HTTP/1.1 +``` + +Dismiss a single notification from the server. **Returns:** empty object\ **OAuth:** User token + `write:notifications`\ **Version history:**\ 1.3.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the notification to be cleared -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Notification in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response + +##### 200: OK Notification with given ID successfully dismissed -{{< endapi-method-response-example-description >}} - -```javascript +```json {} ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/notifications/dismiss" title="\(DEPRECATED\) Dismiss a single notification" >}} -{{< api-method-description >}} -Delete a single notification from the server. +--- + +## (REMOVED) Dismiss a single notification {#dismiss-deprecated} + +```http +POST https://mastodon.example/api/v1/notifications/dismiss HTTP/1.1 +``` + +Dismiss a single notification from the server. **Returns:** empty object\ **OAuth:** User token + `write:notifications`\ **Version history**:\ 0.0.0 - available\ +1.3.0 - deprecated in favor of [notifications/:id/dismiss](#dismiss) 3.0.0 - removed -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="id" type="string" required=true >}} -ID of the notification to be cleared, passed as a parameter -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters +id +: {{}} String. The ID of the notification in the database. + +#### Response + +##### 200: OK Notification with given ID successfully dismissed -{{< endapi-method-response-example-description >}} - -```javascript +```json {} ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< page-relref ref="methods/push" caption="push API methods" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/notifications_controller.rb" caption="app/controllers/api/v1/notifications_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/notifications/push.md b/content/en/methods/notifications/push.md deleted file mode 100644 index d479b4d2..00000000 --- a/content/en/methods/notifications/push.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: push -description: >- - Subscribe to and receive push notifications when a server-side notification is - received, via the Web Push API -menu: - docs: - weight: 10 - parent: methods-notifications ---- - -## Web Push API - -Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android’s and Apple’s proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see [Mozilla’s web push server](https://github.com/mozilla-services/autopush), or more practically, see: - -* [toot-relay](https://github.com/DagAgren/toot-relay) -* [PushToFCM](https://github.com/tateisu/PushToFCM) -* [metatext-apns](https://github.com/metabolist/metatext-apns) - -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/push/subscription" title="Subscribe to push notifications" >}} -{{< api-method-description >}} - -Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted. - -**Returns:** PushSubscription\ -**OAuth:** User token + `push`\ -**Version history:**\ -2.4.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="subscription\[endpoint\]" type="string" required=true >}} -Endpoint URL that is called when a notification event occurs. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="subscription\[keys\]\[p256dh\]" type="string" required=true >}} -User agent public key. Base64 encoded string of public key of ECDH key using `prime256v1` curve. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="subscription\[keys\]\[auth\]" type="string" required=true >}} -Auth secret. Base64 encoded string of 16 bytes of random data. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[follow\]" type="boolean" required=false >}} -Receive follow notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[favourite\]" type="boolean" required=false >}} -Receive favourite notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[reblog\]" type="boolean" required=false >}} -Receive reblog notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[mention\]" type="boolean" required=false >}} -Receive mention notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[poll\]" type="boolean" required=false >}} -Receive poll notifications? -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -A new PushSubscription has been generated, which will send the requested alerts to your endpoint. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": 328183, - "endpoint": "https://yourdomain.example/listener", - "alerts": { - "follow": true, - "favourite": true, - "reblog": true, - "mention": true, - "poll": true - }, - "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/push/subscription" title="Get current subscription" >}} -{{< api-method-description >}} - -View the PushSubscription currently associated with this access token. - -**Returns:** PushSubscription\ -**OAuth:** User token + `push`\ -**Version history:**\ -2.4.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": 328183, - "endpoint": "https://yourdomain.example/listener", - "alerts": { - "follow": true, - "favourite": true, - "reblog": true, - "mention": true, - "poll": true - }, - "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -A PushSubscription does not exist for this token. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="put" host="https://mastodon.example" path="/api/v1/push/subscription" title="Change types of notifications" >}} -{{< api-method-description >}} - -Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead. - -**Returns:** PushSubscription\ -**OAuth:** User token + `push`\ -**Version history:**\ -2.4.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="data\[alerts\]\[follow\]" type="boolean" required=false >}} -Receive follow notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[favourite\]" type="boolean" required=false >}} -Receive favourite notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[reblog\]" type="boolean" required=false >}} -Receive reblog notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[mention\]" type="boolean" required=false >}} -Receive mention notifications? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="data\[alerts\]\[poll\]" type="boolean" required=false >}} -Receive poll notifications? -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Updating a PushSubscription to only receive mention alerts -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": 328183, - "endpoint": "https://yourdomain.example/listener", - "alerts": { - "follow": false, - "favourite": false, - "reblog": false, - "mention": true, - "poll": false - }, - "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -No existing PushSubscription for this token -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/push/subscription" title="Remove current subscription" >}} -{{< api-method-description >}} - -Removes the current Web Push API subscription. - -**Returns:** none\ -**OAuth:** User token + `push`\ -**Version history:**\ -2.4.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -PushSubscription successfully deleted or did not exist previously -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/oauth.md b/content/en/methods/oauth.md new file mode 100644 index 00000000..2ba2dc15 --- /dev/null +++ b/content/en/methods/oauth.md @@ -0,0 +1,203 @@ +--- +title: oauth API methods +description: Generate and manage OAuth tokens. +menu: + docs: + weight: 10 + name: oauth + parent: methods-apps + identifier: methods-oauth +aliases: [ + "/methods/oauth", + "/api/methods/oauth", + "/methods/apps/oauth", +] +--- + + + +## Authorize a user {#authorize} + +```http +GET https://mastodon.example/oauth/authorize HTTP/1.1 +``` + +Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested. The authorization code can be used while requesting a token to obtain access to user-level methods. + +**Returns:** String (URL) or HTML response\ +**OAuth:** Public\ +**Version history:**\ +0.1.0 - added\ +2.6.0 - added `force_login`\ +3.5.0 - added `lang` + +#### Request +##### Query parameters + +response_type +: {{}} String. Should be set equal to `code`. + +client_id +: {{}} String. The client ID, obtained during app registration. + +redirect_uri +: {{}} String. Set a URI to redirect the user to. If this parameter is set to `urn:ietf:wg:oauth:2.0:oob` then the authorization code will be shown instead. Must match one of the `redirect_uris` declared during app registration. + +scope +: String. List of requested OAuth scopes, separated by spaces (or by pluses, if using query parameters). Must be a subset of `scopes` declared during app registration. If not provided, defaults to `read`. + +force_login +: Boolean. Forces the user to re-login, which is necessary for authorizing with multiple accounts from the same instance. + +lang +: String. The ISO 639-1 two-letter language code to use while rendering the authorization form. + +#### Response +##### 200: OK + +The authorization code will be returned as a query parameter named `code`. + +```http +redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU +``` + +##### 400: Client error + +If the authorization code is incorrect or has been used already, the request will fail. + +```json +{ + "error": "invalid_grant", + "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." +} +``` + +--- + +## Obtain a token {#token} + +```http +POST https://mastodon.example/oauth/token HTTP/1.1 +``` + +Obtain an access token, to be used during API calls that are not public. + +**Returns:** [Token]({{< relref "entities/token" >}})\ +**OAuth:** Public\ +**Version history:**\ +0.1.0 - added + +#### Request +##### Form data parameters + +grant_type +: {{}} String. Set equal to `authorization_code` if `code` is provided in order to gain user-level access. Otherwise, set equal to `client_credentials` to obtain app-level access only. + +code +: String. A user authorization code, obtained via [GET /oauth/authorize](#authorize). + +client_id +: {{}} String. The client ID, obtained during app registration. + +redirect_uri +: {{}} String. Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the token will be shown instead. Must match one of the `redirect_uris` declared during app registration. + +scope +: String. List of requested OAuth scopes, separated by spaces (or by pluses, if using query parameters). If `code` was provided, then this must be equal to the `scope` requested from the user. Otherwise, it must be a subset of `scopes` declared during app registration. If not provided, defaults to `read`. + +#### Response +##### 200: OK + +Store this access_token for later use with auth-required methods. The token should be passed as an HTTP `Authorization` header when making API calls, with the value `Bearer access_token` + +```json +{ + "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0", + "token_type": "Bearer", + "scope": "read write follow push", + "created_at": 1573979017 +} +``` + +##### 400: Client error + +If you try to request a scope that was not included when registering the app, the request will fail. + +```json +{ + "error": "invalid_scope", + "error_description": "The requested scope is invalid, unknown, or malformed." +} +``` + +##### 401: Unauthorized + +If client_id and client_secret do not match or are invalid, the request will fail. + +```json +{ + "error": "invalid_client", + "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method." +} +``` + +--- + +## Revoke a token {#revoke} + +```http +POST https://mastodon.example/oauth/revoke HTTP/1.1 +``` + +Revoke an access token to make it no longer valid for use. + +**Returns:** empty object\ +**OAuth:** Public\ +**Version history:**\ +x.x.x - added + +#### Request +##### Form data parameters + +client_id +: {{}} String. The client ID, obtained during app registration. + +client_secret +: {{}} String. The client secret, obtained durign app registration. + +token +: {{}} String. The previously obtained token, to be invalidated. + +#### Response +##### 200: OK + +If you own the provided token, the API call will provide an empty response. This operation is idempotent, so calling this API multiple times will still return OK. + +```json +{} +``` + +##### 403: Forbidden + +If you provide a token you do not own, or no token at all, the API call will return a 403 error. + +```json +{ + "error": "unauthorized_client", + "error_description": "You are not authorized to revoke this token" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/oauth/authorizations_controller.rb" caption="app/controllers/oauth/authorizations_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/oauth/authorized_applications_controller.rb" caption="app/controllers/oauth/authorized_applications_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/oauth/tokens_controller.rb" caption="app/controllers/oauth/tokens_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/oembed.md b/content/en/methods/oembed.md index bb27908b..c6d4ed69 100644 --- a/content/en/methods/oembed.md +++ b/content/en/methods/oembed.md @@ -1,44 +1,51 @@ --- -title: oembed +title: oembed API methods description: For generating OEmbed previews. menu: docs: weight: 110 + name: oembed parent: methods + identifier: methods-oembed +aliases: [ + "/methods/oembed", + "/api/methods/oembed", +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/oembed" title="OEmbed as JSON" >}} -{{< api-method-description >}} + + +## Get OEmbed info as JSON {#get} + +```http +GET https://mastodon.example/api/oembed HTTP/1.1 +``` **Returns:** OEmbed metadata\ **OAuth:** Public\ **Version history:**\ 1.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="url" type="string" required=true >}} -URL of a status -{{< endapi-method-parameter >}} -{{< api-method-parameter name="maxwidth" type="number" required=false >}} -width of the iframe. Defaults to 400 -{{< endapi-method-parameter >}} -{{< api-method-parameter name="maxheight" type="number" required=false >}} -height of the iframe. Defaults to null -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Query parameters + +url +: {{}} String. URL of a status. + +maxwidth +: Number. Width of the iframe. Defaults to 400 + +maxheight +: Number. Height of the iframe. Defaults to null + +#### Response +##### 200: OK Represents OEmbed "rich" preview, with associated iframe and metadata. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "type": "rich", "version": "1.0", @@ -53,22 +60,19 @@ Represents OEmbed "rich" preview, with associated iframe and metadata. "height": null } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status not found -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status not found for given URL -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/oembed_controller.rb" caption="app/controllers/api/oembed_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/polls.md b/content/en/methods/polls.md new file mode 100644 index 00000000..5c120d62 --- /dev/null +++ b/content/en/methods/polls.md @@ -0,0 +1,228 @@ +--- +title: polls API methods +description: >- + View and vote on polls attached to statuses. To discover poll ID, you will + need to GET a Status first and then check for a `poll` property. +menu: + docs: + weight: 20 + name: polls + parent: methods-statuses + identifier: methods-polls +aliases: [ + "/methods/polls", + "/api/methods/polls", + "/methods/statuses/polls", +] +--- + + + +## View a poll {#get} + +```http +GET https://mastodon.example/api/v1/polls/:id HTTP/1.1 +``` + +**Returns:** [Poll]({{< relref "entities/poll" >}})\ +**OAuth:** Public if parent status is public. User token + `read:statuses` if parent status is private.\ +**Version history:**\ +2.8.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Poll in the database. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "34830", + "expires_at": "2019-12-05T04:05:08.302Z", + "expired": true, + "multiple": false, + "votes_count": 10, + "voters_count": null, + "voted": true, + "own_votes": [ + 1 + ], + "options": [ + { + "title": "accept", + "votes_count": 6 + }, + { + "title": "deny", + "votes_count": 4 + } + ], + "emojis": [] +} +``` + +##### 404: Not found + +Poll does not exist, or poll's parent status is private + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Vote on a poll {#vote} + +```http +POST https://mastodon.example/api/v1/polls/:id/votes HTTP/1.1 +``` + +**Returns:** [Poll]({{< relref "entities/poll" >}})\ +**OAuth:** User token + `write:statuses`\ +**Version history:**\ +2.8.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Poll in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +choices[] +: {{}} Array of Integer. Provide your own votes as an index for each option (starting from 0). + +#### Response +##### 200: OK + +Poll was voted on + +```json +{ + "id": "34873", + "expires_at": "2019-12-05T11:16:17.426Z", + "expired": false, + "multiple": true, + "votes_count": 5, + "voters_count": null, + "voted": true, + "own_votes": [ + 0, + 2, + 4, + 9, + 6 + ], + "options": [ + { + "title": "option 0", + "votes_count": 1 + }, + { + "title": "option 1", + "votes_count": 0 + }, + { + "title": "option 2", + "votes_count": 1 + }, + { + "title": "option 3", + "votes_count": 0 + }, + { + "title": "option 4", + "votes_count": 1 + }, + { + "title": "option 5", + "votes_count": 0 + }, + { + "title": "option 6", + "votes_count": 1 + }, + { + "title": "option 7", + "votes_count": 0 + }, + { + "title": "option 8", + "votes_count": 0 + }, + { + "title": "option 9", + "votes_count": 1 + } + ], + "emojis": [] +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Poll does not exist, or poll's parent status is private + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +The poll has expired + +```json +{ + "error": "Validation failed: The poll has already ended" +} +``` + +Alternatively, you have already voted + +```json +{ + "error": "Validation failed: You have already voted on this poll" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (`poll` parameter)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/polls_controller.rb" caption="app/controllers/api/v1/polls_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/polls/votes_controller.rb" caption="app/controllers/api/v1/polls/votes_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/preferences.md b/content/en/methods/preferences.md new file mode 100644 index 00000000..5a452300 --- /dev/null +++ b/content/en/methods/preferences.md @@ -0,0 +1,68 @@ +--- +title: preferences API methods +description: Preferred common behaviors to be shared across clients. +menu: + docs: + weight: 110 + name: preferences + parent: methods-accounts + identifier: methods-preferences +aliases: [ + "/methods/preferences", + "/api/methods/preferences", + "/methods/accounts/preferences", +] +--- + + + +## View user preferences {#get} + +```http +GET https://mastodon.example/api/v1/preferences HTTP/1.1 +``` + +Preferences defined by the user in their account settings. + +**Returns:** Preferences by key and value\ +**OAuth:** User token + `read:accounts`\ +**Version history:**\ +2.8.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "posting:default:visibility": "public", + "posting:default:sensitive": false, + "posting:default:language": null, + "reading:expand:media": "default", + "reading:expand:spoilers": false +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/preferences_controller.rb" caption="app/controllers/api/v1/preferences_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/proofs.md b/content/en/methods/proofs.md index 84bfcc31..80bad9db 100644 --- a/content/en/methods/proofs.md +++ b/content/en/methods/proofs.md @@ -1,41 +1,54 @@ --- -title: proofs +title: proofs API methods description: For use by identity providers. menu: docs: weight: 100 + name: proofs parent: methods + identifier: methods-proofs +aliases: [ + "/methods/proofs", + "/api/methods/proofs", + "/methods/accounts/proofs", +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/proofs" title="View identity proof" >}} -{{< api-method-description >}} + + +{{< hint style="danger" >}} +**Deprecated**\ +Identity proofs have been deprecated in 3.5.0 and newer. Previously, the only proof provider was Keybase, but development on Keybase has stalled entirely since it was acquired by Zoom. +{{< /hint >}} + +## (REMOVED) View identity proofs {#get} + +```http +GET https://mastodon.example/api/proofs HTTP/1.1 +``` **Returns:** custom response defined by provider\ **OAuth:** Public\ **Version history:**\ 2.8.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="provider" type="string" required=false >}} -The identity provider to be looked up. Currently only supports `keybase` \(case-sensitive\) -{{< endapi-method-parameter >}} -{{< api-method-parameter name="username" type="string" required=false >}} -The username on the selected identity provider -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Query parameters -`gargron` on `keybase` -{{< endapi-method-response-example-description >}} +provider +: String. The identity provider to be looked up. Currently only supports `keybase` (case-sensitive). +username +: String. The username on the selected identity provider. -```javascript +#### Response +##### 200: OK + +Looking up the `username` "gargron" via the "keybase" `provider` + +```json { "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg", "signatures": [ @@ -46,22 +59,19 @@ The username on the selected identity provider ] } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} + +##### 404: Not found No identity proof found for `username` on `provider` -{{< endapi-method-response-example-description >}} - -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/pull/17045" caption="Remove Keybase integration (#17045)" >}} \ No newline at end of file diff --git a/content/en/methods/push.md b/content/en/methods/push.md new file mode 100644 index 00000000..8613c371 --- /dev/null +++ b/content/en/methods/push.md @@ -0,0 +1,331 @@ +--- +title: push API methods +description: >- + Subscribe to and receive push notifications when a server-side notification is + received, via the Web Push API +menu: + docs: + weight: 10 + name: push + parent: methods-notifications + identifier: methods-push +aliases: [ + "/methods/push", + "/api/methods/push", + "/methods/notifications/push", +] +--- + + + +## About the Web Push API {#about} + +Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android’s and Apple’s proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see [Mozilla’s web push server](https://github.com/mozilla-services/autopush), or more practically, see: + +* [toot-relay](https://github.com/DagAgren/toot-relay) +* [PushToFCM](https://github.com/tateisu/PushToFCM) +* [metatext-apns](https://github.com/metabolist/metatext-apns) + +--- + +## Subscribe to push notifications {#create} + +```http +POST https://mastodon.example/api/v1/push/subscription HTTP/1.1 +``` + +Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted. + +**Returns:** [WebPushSubscription]({{< relref "entities/WebPushSubscription" >}})\ +**OAuth:** User token + `push`\ +**Version history:**\ +2.4.0 - added\ +3.3.0 - added `data[alerts][status]`\ +3.4.0 - added `policy`\ +3.5.0 - added `data[alerts][update]` and `data[alerts][admin.sign_up]`\ +4.0.0 - added `data[alerts][admin.report]` + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +subscription[endpoint] +: {{}} String. The endpoint URL that is called when a notification event occurs. + +subscription[keys][p256dh] +: {{}} String. User agent public key. Base64 encoded string of a public key from a ECDH keypair using the `prime256v1` curve. + +subscription[keys][auth] +: {{}} String. Auth secret. Base64 encoded string of 16 bytes of random data. + +data[alerts][follow] +: Boolean. Receive follow notifications? Defaults to false. + +data[alerts][favourite] +: Boolean. Receive favourite notifications? Defaults to false. + +data[alerts][reblog] +: Boolean. Receive reblog notifications? Defaults to false. + +data[alerts][mention] +: Boolean. Receive mention notifications? Defaults to false. + +data[alerts][poll] +: Boolean. Receive poll notifications? Defaults to false. + +data[alerts][status] +: Boolean. Receive new subscribed account notifications? Defaults to false. + +data[alerts][update] +: Boolean. Receive status edited notifications? Defaults to false. + +data[alerts][admin.sign_up] +: Boolean. Receive new user signup notifications? Defaults to false. Must have a role with the appropriate permissions. + +data[alerts][admin.report] +: Boolean. Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions. + +policy +: String. Specify whether to receive push notifications from `all`, `followed`, `follower`, or `none` users. + +#### Response +##### 200: OK + +A new PushSubscription has been generated, which will send the requested alerts to your endpoint. + +```json +{ + "id": 328183, + "endpoint": "https://yourdomain.example/listener", + "alerts": { + "follow": true, + "favourite": true, + "reblog": true, + "mention": true, + "poll": true + }, + "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Get current subscription {#get} + +```http +GET https://mastodon.example/api/v1/push/subscription HTTP/1.1 +``` + +View the PushSubscription currently associated with this access token. + +**Returns:** [WebPushSubscription]({{< relref "entities/WebPushSubscription" >}})\ +**OAuth:** User token + `push`\ +**Version history:**\ +2.4.0 - added + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": 328183, + "endpoint": "https://yourdomain.example/listener", + "alerts": { + "follow": true, + "favourite": true, + "reblog": true, + "mention": true, + "poll": true + }, + "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +A PushSubscription does not exist for this token. + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Change types of notifications {#update} + +```http +PUT https://mastodon.example/api/v1/push/subscription HTTP/1.1 +``` + +Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead. + +**Returns:** [WebPushSubscription]({{< relref "entities/WebPushSubscription" >}})\ +**OAuth:** User token + `push`\ +**Version history:**\ +2.4.0 - added\ +3.3.0 - added `data[alerts][status]`\ +3.4.0 - added `policy`\ +3.5.0 - added `data[alerts][update]` and `data[alerts][admin.sign_up]`\ +4.0.0 - added `data[alerts][admin.report]` + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +data[alerts][follow] +: Boolean. Receive follow notifications? Defaults to false. + +data[alerts][favourite] +: Boolean. Receive favourite notifications? Defaults to false. + +data[alerts][reblog] +: Boolean. Receive reblog notifications? Defaults to false. + +data[alerts][mention] +: Boolean. Receive mention notifications? Defaults to false. + +data[alerts][poll] +: Boolean. Receive poll notifications? Defaults to false. + +data[alerts][status] +: Boolean. Receive new subscribed account notifications? Defaults to false. + +data[alerts][update] +: Boolean. Receive status edited notifications? Defaults to false. + +data[alerts][admin.sign_up] +: Boolean. Receive new user signup notifications? Defaults to false. Must have a role with the appropriate permissions. + +data[alerts][admin.report] +: Boolean. Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions. + +policy +: String. Specify whether to receive push notifications from `all`, `followed`, `follower`, or `none` users. + +#### Response +##### 200: OK + +Updating a PushSubscription to only receive mention alerts + +```json +{ + "id": 328183, + "endpoint": "https://yourdomain.example/listener", + "alerts": { + "follow": false, + "favourite": false, + "reblog": false, + "mention": true, + "poll": false + }, + "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +No existing PushSubscription for this token + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Remove current subscription {#delete} + +```http +DELETE https://mastodon.example/api/v1/push/subscription HTTP/1.1 +``` + +Removes the current Web Push API subscription. + +**Returns:** none\ +**OAuth:** User token + `push`\ +**Version history:**\ +2.4.0 - added + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response + +##### 200: OK + +PushSubscription successfully deleted or did not exist previously + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/push/subscriptions_controller.rb" caption="app/controllers/api/v1/push/subscriptions_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/reports.md b/content/en/methods/reports.md new file mode 100644 index 00000000..0e32cf6b --- /dev/null +++ b/content/en/methods/reports.md @@ -0,0 +1,155 @@ +--- +title: reports API methods +description: Report problematic users to your moderators. +menu: + docs: + weight: 70 + name: reports + parent: methods-accounts + identifier: methods-reports +aliases: [ + "/methods/reports", + "/api/methods/reports", + "/methods/accounts/reports", +] +--- + + + +## File a report {#post} + +```http +POST https://mastodon.example/api/v1/reports HTTP/1.1 +``` + +**Returns:** [Report]({{< relref "entities/report" >}})\ +**OAuth:** User token + `write:reports`\ +**Version history:**\ +1.1 - added\ +2.3.0 - add `forward` parameter\ +3.5.0 - add `category` and `rule_ids` parameters\ +4.0.0 - `category` is now optional if `rule_ids` is provided + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +account_id +: {{}} String. ID of the account to report. + +status_ids[] +: Array of String. You can attach statuses to the report to provide additional context. + +comment +: String. The reason for the report. Default maximum of 1000 characters. + +forward +: Boolean. If the account is remote, should the report be forwarded to the remote admin? Defaults to false. + +category +: String. Specify if the report is due to `spam`, `violation` of enumerated instance rules, or some `other` reason. Defaults to `other`. Will be set to `violation` if `rule_ids[]` is provided (regardless of any category value you provide). + +rule_ids[] +: Array of Integer. For `violation` category reports, specify the ID of the exact rules broken. Rules and their IDs are available via [GET /api/v1/instance/rules]({{< relref "methods/instance#rules" >}}) and [GET /api/v1/instance]({{< relref "methods/instance#get" >}}). + +#### Response +##### 200: OK + +Sample call with one status ID provided and a category of `spam` with a comment + +```json +{ + "id": "48914", + "action_taken": false, + "action_taken_at": null, + "category": "spam", + "comment": "Spam account", + "forwarded": false, + "created_at": "2022-08-25T09:56:16.763Z", + "status_ids": [ + "108882889550545820" + ], + "rule_ids": null, + "target_account": { + "id": "108366849347798387", + "username": "Baluke", + "acct": "Baluke", + "display_name": "Baluke Dental Studios", + "locked": false, + "bot": false, + "discoverable": false, + "group": false, + "created_at": "2022-05-26T00:00:00.000Z", + "note": "

Baluke Dental Studios is a full service dental lab offering fabrication, staining, and digital services. Advanced technologies and a meticulous process ensure reduced chair time, lower costs, and better patient outcomes with beautiful smiles. Talk to a representative today.

https://baluke.com/

", + "url": "https://mastodon.social/@Baluke", + "avatar": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png", + "avatar_static": "https://files.mastodon.social/accounts/avatars/108/366/849/347/798/387/original/dbcfe99ed5def0f4.png", + "header": "https://static-cdn.mastodon.social/headers/original/missing.png", + "header_static": "https://static-cdn.mastodon.social/headers/original/missing.png", + "followers_count": 0, + "following_count": 0, + "statuses_count": 38, + "last_status_at": "2022-08-25", + "emojis": [], + "fields": [] + } +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Report not filed. + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +Token does not have an authorized user + +```json +{ + "error": "This method requires an authenticated user" +} +``` + +Alternatively, the `category` was set to `violation` but invalid or missing `rule_ids` were provided + +```json +{ + "error": "Validation failed: Rule ids does not reference valid rules" +} +``` + +Alternatively (Mastodon 3.5), the `category` was set to something other than `violation` but some `rule_ids` were provided + +```json +{ + "error": "Validation failed: Rule ids must be blank" +} +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/reports_controller.rb" caption="app/controllers/api/v1/reports_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/scheduled_statuses.md b/content/en/methods/scheduled_statuses.md new file mode 100644 index 00000000..6f70edbc --- /dev/null +++ b/content/en/methods/scheduled_statuses.md @@ -0,0 +1,296 @@ +--- +title: scheduled_statuses API methods +description: Manage statuses that were scheduled to be published at a future date. +menu: + docs: + weight: 30 + name: scheduled_statuses + parent: methods-statuses + identifier: methods-scheduled_statuses +aliases: [ + "/methods/scheduled_statuses", + "/api/methods/scheduled_statuses", + "/methods/statuses/scheduled_statuses", +] +--- + + + +## View scheduled statuses {#get} + +```http +GET https://mastodon.example/api/v1/scheduled_statuses HTTP/1.1 +``` + +**Returns:** Array of [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})\ +**OAuth:** User token + `read:statuses`\ +**Version history:**\ +2.7.0 - added\ +3.3.0 - both `min_id` and `max_id` can be used at the same time now + +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 20. Max 40. + +#### Response +##### 200: OK + +```json +[ + { + "id": "3221", + "scheduled_at": "2019-12-05T12:33:01.000Z", + "params": { + "poll": null, + "text": "test content", + "media_ids": null, + "sensitive": null, + "visibility": null, + "idempotency": null, + "scheduled_at": null, + "spoiler_text": null, + "application_id": 596551, + "in_reply_to_id": null + }, + "media_attachments": [] + } +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## View a single scheduled status {#get-one} + +```http +GET https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1 +``` + +**Returns:** [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})\ +**OAuth:** User token + `read:statuses`\ +**Version history:**\ +2.7.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the ScheduledStatus in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "3221", + "scheduled_at": "2019-12-05T12:33:01.000Z", + "params": { + "poll": null, + "text": "test content", + "media_ids": null, + "sensitive": null, + "visibility": null, + "idempotency": null, + "scheduled_at": null, + "spoiler_text": null, + "application_id": 596551, + "in_reply_to_id": null + }, + "media_attachments": [] +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +ScheduledStatus is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## Update a scheduled status's publishing date {#update} + +```http +PUT https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1 +``` + +**Returns:** [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})\ +**OAuth:** User token + `write:statuses`\ +**Version history:**\ +2.7.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the SOMETHING in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +scheduled_at +: String. ISO 8601 Datetime at which the status will be published. Must be at least 5 minutes into the future. + +#### Response +##### 200: OK + +```json +{ + "id": "3221", + "scheduled_at": "2019-12-05T13:33:01.000Z", + "params": { + "poll": null, + "text": "test content", + "media_ids": null, + "sensitive": null, + "visibility": null, + "idempotency": null, + "scheduled_at": null, + "spoiler_text": null, + "application_id": 596551, + "in_reply_to_id": null + }, + "media_attachments": [] +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +ScheduledStatus is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Scheduled at The scheduled date must be in the future" +} +``` + +--- + +## Cancel a scheduled status {#cancel} + +```http +DELETE https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1 +``` + +**Returns:** empty object\ +**OAuth:** User token + `write:statuses`\ +**Version history:**\ +2.7.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the SOMETHING in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +ScheduledStatus is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (`scheduled_at` parameter)" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/scheduled_statuses_controller.rb" caption="app/controllers/api/v1/scheduled_statuses_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/search.md b/content/en/methods/search.md index a9f18f04..4a2b1f5a 100644 --- a/content/en/methods/search.md +++ b/content/en/methods/search.md @@ -1,72 +1,82 @@ --- -title: search -description: 'Search for content in accounts, statuses and hashtags.' +title: search API methods +description: Search for content in accounts, statuses and hashtags. menu: docs: weight: 60 + name: search parent: methods + identifier: methods-search +aliases: [ + "/methods/search", + "/api/methods/search", +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/v2/search" title="Search results" >}} -{{< api-method-description >}} + -**Returns:** Results\ -**OAuth:** User token + `read:search`\ +## Perform a search {#v2} + +```http +GET https://mastodon.example/api/v2/search HTTP/1.1 +``` + +**Returns:** [Search]({{< relref "entities/Search" >}})\ +**OAuth:** Public (without `resolve` or `offset`), or User token + `read:search`\ **Version history:**\ 2.4.1 - added, limit hardcoded to 5\ -2.8.0 - add type, limit, offset, min_id, max_id, account_id\ -3.0.0 - add `exclude_unreviewed` param +2.8.0 - add `type`, `limit`, `offset`, `min_id`, `max_id`, `account_id`\ +3.0.0 - add `exclude_unreviewed` param\ +3.3.0 - `min_id` and `max_id` can be used together\ +4.0.0 - no longer requires a user token. Without a valid user token, you cannot use the `resolve` or `offset` parameters. -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="account_id" type="string" required=false >}} -If provided, statuses returned will be authored only by this account -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than this id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than this id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="type" type="string" required=false >}} -Enum\(accounts, hashtags, statuses\) -{{< endapi-method-parameter >}} -{{< api-method-parameter name="exclude_unreviewed" type="boolean" required=false >}} -Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="q" type="string" required=true >}} -The search query -{{< endapi-method-parameter >}} -{{< api-method-parameter name="resolve" type="boolean" required=false >}} -Attempt WebFinger lookup. Defaults to false. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="integer" required=false >}} -Maximum number of results to load, per type. Defaults to 20. Max 40. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="offset" type="integer" required=false >}} -Offset in search results. Used for pagination. Defaults to 0. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="following" type="boolean" required=false >}} -Only include accounts that the user is following. Defaults to false. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +q +: {{}} String. The search query. + +type +: String. Specify whether to search for only `accounts`, `hashtags`, `statuses` + +resolve +: Boolean. Attempt WebFinger lookup? Defaults to false. + +following +: Boolean. Only include accounts that the user is following? Defaults to false. + +account_id +: String. If provided, will only return statuses authored by this account. + +exclude_unreviewed +: Boolean. Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags. + +max_id +: String. Return results older than this ID. + +min_id +: String. Return results immediately newer than this ID. + +limit +: Integer. Maximum number of results to return, per type. Defaults to 20. Max 40. + +offset +: Integer. Offset in search results, used for pagination. Defaults to 0. + +#### Response +##### 200: OK Truncated results of a sample search for "cats" with limit=2. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "accounts": [ { @@ -74,32 +84,32 @@ Truncated results of a sample search for "cats" with limit=2. "username": "catstar", "acct": "catstar@catgram.jp", "display_name": "catstar", - ... + // ... }, { "id": "214293", "username": "catsareweird", "acct": "catsareweird", "display_name": "Cats Are Weird", - ... + // ... } ], "statuses": [ { "id": "103085519055545958", "created_at": "2019-11-05T13:23:09.000Z", - ... + // ... "content": "

cats
cats never change

", - ... + // ... }, { "id": "101068121469614510", "created_at": "2018-11-14T06:31:48.000Z", - ... + // ... "spoiler_text": "Cats", - ... + // ... "content": "

Cats are inherently good at self-care.

#cats

", - ... + // ... ], "hashtags": [ { @@ -111,7 +121,7 @@ Truncated results of a sample search for "cats" with limit=2. "uses": "10", "accounts": "9" }, - ... + // ... ] }, { @@ -123,101 +133,102 @@ Truncated results of a sample search for "cats" with limit=2. "uses": "6", "accounts": "5" }, - ... + // ... ] } ] } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/search" title="\(DEPRECATED\) Search results" >}} -{{< api-method-description >}} -**Returns:** Results, but hashtags is an array of strings instead of an array of Tag.\ +--- + +## (REMOVED) Search results (v1) {#v1} + +```http +GET https://mastodon.example/api/v1/search HTTP/1.1 +``` + +**Returns:** [Search]({{< relref "entities/Search" >}}), but `hashtags` is an array of strings instead of an array of Tag.\ **OAuth:** User token + `read:search`\ **Version history:**\ 1.1 - added, limit hardcoded to 5\ 1.5.0 - now requires authentication\ -2.8.0 - added limit, pagination, and account options\ -3.0.0 - removed; use v2 instead +2.4.1 - deprecated in favor of [v2 search](#v2)\ +2.8.0 - added `limit`, pagination, and account options\ +3.0.0 - removed; use [v2 search](#v2) instead -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="q" type="string" required=true >}} -The search query -{{< endapi-method-parameter >}} -{{< api-method-parameter name="resolve" type="string" required=false >}} -Attempt Webfinger lookup. Defaults to false. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Max number of results to load per type. Defaults to 20 -{{< endapi-method-parameter >}} -{{< api-method-parameter name="type" type="string" required=false >}} -Enum\(accounts,hashtags,statuses\) -{{< endapi-method-parameter >}} -{{< api-method-parameter name="offset" type="string" required=false >}} -Offset in search results. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than this id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than this id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="account_id" type="string" required=false >}} -Return statuses only from this account -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +q +: {{}} String. The search query. + +type +: String. Specify whether to search for only `accounts`, `hashtags`, `statuses` + +resolve +: Boolean. Attempt WebFinger lookup? Defaults to false. + +account_id +: String. If provided, will only return statuses authored by this account. + +max_id +: String. Return results older than this ID. + +min_id +: String. Return results immediately newer than this ID. + +limit +: Integer. Maximum number of results to return, per type. Defaults to 20. Max 40. + +offset +: Integer. Offset in search results, used for pagination. Defaults to 0. + +#### Response +##### 200: OK v1 search was deprecated because hashtags were returned as strings instead of as Tag entities. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "accounts": [...], "statuses": [...], "hashtags": ["cats","catsofmastodon"] } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< page-relref ref="methods/accounts#search" caption="GET /api/v1/accounts/search" >}} + +{{< page-relref ref="methods/accounts#lookup" caption="GET /api/v1/accounts/lookup" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/search_controller.rb" caption="app/controllers/api/v2/search_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/statuses.md b/content/en/methods/statuses.md index 1e6b8834..0a46145b 100644 --- a/content/en/methods/statuses.md +++ b/content/en/methods/statuses.md @@ -1,103 +1,108 @@ --- -title: statuses -description: 'Publish, interact, and view information about statuses.' +title: statuses API methods +description: Publish, interact, and view information about statuses. menu: docs: weight: 30 + name: statuses parent: methods identifier: methods-statuses +aliases: [ + "/methods/statuses", + "/api/methods/statuses", +] --- -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses" title="Publish new status" >}} -{{< api-method-description >}} + + +## Publish new status {#create} + +```http +POST https://mastodon.example/api/v1/statuses HTTP/1.1 +``` Post a new status. -**Returns:** Status. When `scheduled_at` is present, ScheduledStatus is returned instead.\ +**Returns:** [Status]({{}}). When `scheduled_at` is present, [ScheduledStatus]({{}}) is returned instead.\ **OAuth:** User + `write:statuses`\ **Version history:**\ 0.0.0 - added\ 2.7.0 - `scheduled_at` added\ 2.8.0 - `poll` added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Idempotency-Key" type="string" required=false >}} -Prevent duplicate submissions of the same status. Idempotency keys are stored for up to 1 hour, and can be any arbitrary string. Consider using a hash or UUID generated client-side. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="status" type="string" required=true >}} -Text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="media_ids\[\]" type="array" required=true >}} -Array of Attachment ids to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="poll\[options\]\[\]" type="array" required=true >}} -Array of possible answers. If provided, `media_ids` cannot be used, and `poll[expires_in]` must be provided. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="poll\[expires_in\]" type="number" required=true >}} -Duration the poll should be open, in seconds. If provided, `media_ids` cannot be used, and `poll[options]` must be provided. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="poll\[multiple\]" type="boolean" required=false >}} -Allow multiple choices? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="poll\[hide_totals\]" type="boolean" required=false >}} -Hide vote counts until the poll ends? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="in_reply_to_id" type="string" required=false >}} -ID of the status being replied to, if status is a reply -{{< endapi-method-parameter >}} -{{< api-method-parameter name="sensitive" type="boolean" required=false >}} -Mark status and attached media as sensitive? -{{< endapi-method-parameter >}} -{{< api-method-parameter name="spoiler_text" type="string" required=false >}} -Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="visibility" type="string" required=false >}} -Visibility of the posted status. Enumerable oneOf public, unlisted, private, direct. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="scheduled_at" type="string" required=false >}} -ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="language" type="string" required=false >}} -ISO 639 language code for this status. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request -Status will be posted with chosen parameters. If scheduled_at is provided, then a ScheduledStatus will be returned instead. -{{< endapi-method-response-example-description >}} +##### Headers +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. -{{< tabs >}} -{{< tab title="status" >}} -```javascript +Idempotency-Key +: Provide this header with any arbitrary string to prevent duplicate submissions of the same status. Consider using a hash or UUID generated client-side. Idempotency keys are stored for up to 1 hour. + +##### Form data parameters + +status +: {{}} String. The text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided. + +media_ids[] +: {{}} Array of String. Include Attachment IDs to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used. + +poll[options][] +: {{}} Array of String. Possible answers to the poll. If provided, `media_ids` cannot be used, and `poll[expires_in]` must be provided. + +poll[expires_in] +: {{}} Integer. Duration that the poll should be open, in seconds. If provided, `media_ids` cannot be used, and `poll[options]` must be provided. + +poll[multiple] +: Boolean. Allow multiple choices? Defaults to false. + +poll[hide_totals] +: Boolean. Hide vote counts until the poll ends? Defaults to false. + +in_reply_to_id +: String. ID of the status being replied to, if status is a reply. + +sensitive +: Boolean. Mark status and attached media as sensitive? Defaults to false. + +spoiler_text +: String. Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field. + +visibility +: String. Sets the visibility of the posted status to `public`, `unlisted`, `private`, `direct`. + +language +: String. ISO 639 language code for this status. + +scheduled_at +: String. ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future. + +#### Response +##### 200: OK + +Status will be posted with chosen parameters: + +```json { "id": "103254962155278888", "created_at": "2019-12-05T11:34:47.196Z", - ... + // ... "content": "

test content

", - ... + // ... "application": { "name": "test app", "website": null }, - ... + // ... } ``` -{{< endtab >}} -{{< tab title="scheduled_at ScheduledStatus" >}} -```javascript +If scheduled_at is provided, then a ScheduledStatus will be returned instead: + +```json { "id": "3221", "scheduled_at": "2019-12-05T12:33:01.000Z", @@ -116,44 +121,57 @@ Status will be posted with chosen parameters. If scheduled_at is provided, then "media_attachments": [] } ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/statuses/:id" title="View specific status" >}} -{{< api-method-description >}} -View information about a status. +##### 401: Unauthorized -**Returns:** Status\ +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Text can't be blank" +} +``` + +--- + +## View a single status {#get} + +```http +GET https://mastodon.example/api/v1/statuses/:id HTTP/1.1 +``` + +Obtain information about a status. + +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\ **Version history:**\ 0.0.0 - added\ 2.7.0 - public statuses no longer require token -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=false >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json { "id": "1", "created_at": "2016-03-16T14:44:31.580Z", @@ -215,72 +233,63 @@ Bearer <user token> "poll": null } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -instance is in whitelist mode -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Instance is in authorized-fetch mode. -```javascript +```json { "error": "This API requires an authenticated user" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private. -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private. -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/statuses/:id" title="Delete status" >}} -{{< api-method-description >}} + +--- + +## Delete a status {#delete} + +```http +DELETE https://mastodon.example/api/v1/statuses/:id HTTP/1.1 +``` Delete one of your own statuses. -**Returns:** Status with source `text` and `media_attachments` or `poll`\ +**Returns:** [Status]({{< relref "entities/status" >}}) with source `text` and `poll` or `media_attachments`\ **OAuth:** User token + `write:statuses`\ **Version history:**\ 0.0.0 - added\ 2.9.0 - return source properties, for use with delete and redraft -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. Must be owned by authenticated account. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request -Note the special properties `text` and `media_attachments` or `poll` which may be used to repost the status, e.g. in case of delete-and-redraft functionality. With POST /api/v1/statuses, use `text` as the value for `status` parameter, `media_attachments[n]["id"]` for the `media_ids` array parameter, and `poll` properties with the corresponding parameters \(e.g. `poll[multiple]` and `poll[options]`, with a new `poll[expires_in]` and `poll[hide_totals]` per user input. -{{< endapi-method-response-example-description >}} +##### Path parameters +:id +: {{}} String. The ID of the Status in the database. -{{< tabs >}} -{{< tab title="with media" >}} -```javascript +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Note the special properties `text` and `poll` or `media_attachments` which may be used to repost the status, e.g. in case of delete-and-redraft functionality. With [POST /api/v1/statuses](#create), use `text` as the value for `status` parameter, `media_attachments[n]["id"]` for the `media_ids` array parameter, and `poll` properties with the corresponding parameters (e.g. `poll[multiple]` and `poll[options]`, with a new `poll[expires_in]` and `poll[hide_totals]` per user input. + +Example of deleting a media post: + +```json { "id": "103254193998341330", "created_at": "2019-12-05T08:19:26.052Z", @@ -311,7 +320,7 @@ Note the special properties `text` and `media_attachments` or `poll` which may b "username": "trwnh", "acct": "trwnh", "display_name": "infinite love ⴳ", - ... + // ... }, "media_attachments": [ { @@ -350,10 +359,10 @@ Note the special properties `text` and `media_attachments` or `poll` which may b "poll": null } ``` -{{< endtab >}} -{{< tab title="with poll" >}} -```javascript +Example of deleting a poll: + +```json { "id": "103254222827484720", "created_at": "2019-12-05T08:26:45.958Z", @@ -384,7 +393,7 @@ Note the special properties `text` and `media_attachments` or `poll` which may b "username": "trwnh", "acct": "trwnh", "display_name": "infinite love ⴳ", - ... + // ... }, "media_attachments": [], "mentions": [], @@ -414,69 +423,58 @@ Note the special properties `text` and `media_attachments` or `poll` which may b } } ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status already deleted, does not exist, or is not owned by you -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status is not owned by you or does not exist -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/statuses/:id/context" title="Parent and child statuses" >}} -{{< api-method-description >}} + +--- + +## Get parent and child statuses in context {#context} + +```http +GET https://mastodon.example/api/v1/statuses/:id/context HTTP/1.1 +``` View statuses above and below this status in the thread. -**Returns:** Context\ +**Returns:** [Context]({{< relref "entities/context" >}})\ **OAuth:** Public for public statuses. User token + `read:statuses` for private statuses.\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=false >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json { "ancestors": [ { @@ -484,21 +482,21 @@ Bearer <user token> "created_at": "2019-11-23T19:44:00.124Z", "in_reply_to_id": null, "in_reply_to_account_id": null, - ... + // ... }, { "id": "103188971072973252", "created_at": "2019-11-23T19:52:23.398Z", "in_reply_to_id": "103188938570975982", "in_reply_to_account_id": "634458", - ... + // ... }, { "id": "103188982235527758", "created_at": "2019-11-23T19:55:08.208Z", "in_reply_to_id": "103188971072973252", "in_reply_to_account_id": "14715", - ... + // ... } ], "descendants": [ @@ -507,964 +505,1199 @@ Bearer <user token> "created_at": "2019-11-23T20:06:36.011Z", "in_reply_to_id": "103189005915505698", "in_reply_to_account_id": "634458", - ... + // ... } ] } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status is private or does not exist -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/statuses/:id/reblogged_by" title="Boosted by" >}} -{{< api-method-description >}} + +--- + +## See who boosted a status {#reblogged_by} + +```http +GET https://mastodon.example/api/v1/statuses/:id/reblogged_by HTTP/1.1 +``` View who boosted a given status. -**Returns:** Array of Account\ -**OAuth:** Public +**Returns:** Array of [Account]({{< relref "entities/account" >}})\ +**OAuth:** Public for public statuses. User token + `read:statuses` for private statuses. **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +A list of statuses that boosted the status + +```json [ { "id": "711345", "username": "Norman_Doors", "acct": "Norman_Doors@witches.live", - ... + // ... }, - ... + // ... ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private. -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/statuses/:id/favourited_by" title="Favourited by" >}} -{{< api-method-description >}} + +--- + +## See who favourited a status {#favourited_by} + +```http +GET https://mastodon.example/api/v1/statuses/:id/favourited_by HTTP/1.1 +``` View who favourited a given status. -**Returns:** Array of Account\ -**OAuth:** Public\ +**Returns:** Array of [Account]({{< relref "entities/account" >}})\ +**OAuth:** Public for public statuses. User token + `read:statuses` for private statuses.\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +A list of accounts who favourited the status + +```json [ { "id": "828600", "username": "fructose_dealer", "acct": "fructose_dealer@radical.town", - ... + // ... }, - ... + // ... ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/favourite" title="Favourite" >}} -{{< api-method-description >}} + +--- + +## Favourite a status {#favourite} + +```http +POST https://mastodon.example/api/v1/statuses/:id/favourite HTTP/1.1 +``` Add a status to your favourites list. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:favourites`\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Status favourited or was already favourited -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": true, "reblogged": false, "muted": false, "bookmarked": false, "pinned": false, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized -```javascript +Invalid or missing Authorization header. + +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/unfavourite" title="Undo favourite" >}} -{{< api-method-description >}} + +--- + +## Undo favourite of a status {#unfavourite} + +```http +POST https://mastodon.example/api/v1/statuses/:id/unfavourite HTTP/1.1 +``` Remove a status from your favourites list. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:favourites`\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Status unfavourited or was already not favourited -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": false, "muted": false, "bookmarked": false, "pinned": false, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/reblog" title="Boost" >}} -{{< api-method-description >}} -Reshare a status. +--- -**Returns:** Status\ +## Boost a status {#boost} + +```http +POST https://mastodon.example/api/v1/statuses/:id/reblog HTTP/1.1 +``` + +Reshare a status on your own profile. + +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:statuses`\ **Version history:**\ 0.0.0 - added\ 2.8.0 - add `visibility` parameter -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="visibility" type="string" required=false >}} -any visibility except limited or direct \(i.e. public, unlisted, private\). Defaults to public. Currently unused in UI. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +visibility +: String. Any visibility except `limited` or `direct` (i.e. `public`, `unlisted`, `private`). Defaults to public. Currently unused in UI. + +#### Response +##### 200: OK Status has been reblogged. Note that the top-level id has changed. The id of the boosted status is now inside the `reblog` property. The top-level id is the id of the reblog itself. Also note that reblogs cannot be pinned. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "103254401326800919", "created_at": "2019-12-05T09:12:09.625Z", - ... + // ... "favourited": false, "reblogged": true, "muted": false, "bookmarked": false, - ... + // ... "reblog": { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": true, "muted": false, "bookmarked": false, "pinned": false, - ... + // ... }, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/unreblog" title="Undo boost" >}} -{{< api-method-description >}} + +--- + +## Undo boost of a status {#unreblog} + +```http +POST https://mastodon.example/api/v1/statuses/:id/unreblog HTTP/1.1 +``` Undo a reshare of a status. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:statuses`\ **Version history:**\ 0.0.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request -Status no longer reblogged -{{< endapi-method-response-example-description >}} +##### Path parameters +:id +: {{}} String. The ID of the Status in the database. -```javascript +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Status unboosted or was already not boosted + +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": false, "muted": false, "bookmarked": false, "pinned": false, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status deleted, does not exist, or no reblog exists -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private -```javascript +```json { - "error": "Record not found" + "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/bookmark" title="Bookmark" >}} -{{< api-method-description >}} + +--- + +## Bookmark a status {#bookmark} + +```http +POST https://mastodon.example/api/v1/statuses/:id/bookmark HTTP/1.1 +``` Privately bookmark a status. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:bookmarks`\ **Version history:**\ 3.1.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the status in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request -Status bookmarked -{{< endapi-method-response-example-description >}} +##### Path parameters +:id +: {{}} String. The ID of the Status in the database. -```javascript +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Status bookmarked or was already bookmarked + +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": false, "muted": false, "bookmarked": true, "pinned": false, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +--- -```javascript -{ - "error": "Record not found" -} +## Undo bookmark of a status {#unbookmark} + +```http +POST https://mastodon.example/api/v1/statuses/:id/unbookmark HTTP/1.1 ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/unbookmark" title="Undo bookmark" >}} -{{< api-method-description >}} Remove a status from your private bookmarks. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:bookmarks`\ **Version history:**\ 3.1.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name="id" type="string" required=true >}} -ID of the status in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Status was unbookmarked or was already not bookmarked + +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": false, "muted": false, "bookmarked": false, "pinned": false, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, is private, or was already not bookmarked -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private. -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/mute" title="Mute conversation" >}} -{{< api-method-description >}} + +--- + +## Mute a conversation {#mute} + +```http +POST https://mastodon.example/api/v1/statuses/:id/mute HTTP/1.1 +``` Do not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:mutes`\ **Version history:**\ 1.4.2 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Status's conversation muted, or was already muted -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": false, "muted": true, "bookmarked": false, "pinned": false, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 404: Not found -```javascript +Status does not exist or is private. + +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/unmute" title="Unmute conversation" >}} -{{< api-method-description >}} + +--- + +## Unmute a conversation {#unmute} + +```http +POST https://mastodon.example/api/v1/statuses/:id/unmute HTTP/1.1 +``` Start receiving notifications again for the thread that this status is part of. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:mutes`\ **Version history:**\ 1.4.2 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the Status in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Status's conversation unmuted, or was already unmuted -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": false, "muted": false, "bookmarked": false, "pinned": false, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 404: Not found -```javascript +Status does not exist or is private. + +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/pin" title="Pin to profile" >}} -{{< api-method-description >}} + +--- + +## Pin status to profile {#pin} + +```http +POST https://mastodon.example/api/v1/statuses/:id/pin HTTP/1.1 +``` Feature one of your own public statuses at the top of your profile. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:accounts`\ **Version history:**\ -1.6.0 - added +1.6.0 - added\ +3.5.0 - you can now pin private posts -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. The status should be public and authored by the authorized account. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The local ID of the Status in the database. The status should be authored by the authorized account. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Status pinned. Note the status is not a reblog and its authoring account is your own. -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": false, "muted": false, "bookmarked": false, "pinned": true, - ... + // ... "reblog": null, - ... + // ... "account": { "id": "14715", "username": "trwnh", "acct": "trwnh", - ... + // ... }, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or you are not authorized to see it. -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private. -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} -Status is not owned by you, or is not public. You cannot pin one of your private statuses because private statuses cannot be fetched from remote sites, and must be delivered. -{{< endapi-method-response-example-description >}} +##### 422: Unprocessable entity +Status is not owned by you: -{{< tabs >}} -{{< tab title="Not yours" >}} -```javascript +```json { - "error": "Validation failed: Someone else's toot cannot be pinned" + "error": "Validation failed: Someone else's post cannot be pinned" } ``` -{{< endtab >}} -{{< tab title="Private" >}} -```javascript +Prior to 3.5.0, you could not pin one of your private statuses because private statuses could not be fetched from remote sites, and must have been delivered. (3.5.0 added a mechanism to fetch statuses on behalf of an account.) + +```json { "error": "Validation failed: Non-public toot cannot be pinned" } ``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/statuses/:id/unpin" title="Unpin to profile" >}} -{{< api-method-description >}} + +--- + +## Unpin status from profile {#unpin} + +```http +POST https://mastodon.example/api/v1/statuses/:id/unpin HTTP/1.1 +``` Unfeature a status from the top of your profile. -**Returns:** Status\ +**Returns:** [Status]({{< relref "entities/status" >}})\ **OAuth:** User token + `write:accounts`\ **Version history:**\ 1.6.0 - added -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -Local ID of a status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:id +: {{}} String. The local ID of the Status in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK Status unpinned, or was already not pinned -{{< endapi-method-response-example-description >}} - -```javascript +```json { "id": "99734435964706331", "created_at": "2018-03-23T17:38:40.700Z", - ... + // ... "favourited": false, "reblogged": false, "muted": false, "bookmarked": false, "pinned": false, - ... + // ... "reblog": null, - ... + // ... "account": { "id": "14715", "username": "trwnh", "acct": "trwnh", - ... + // ... }, - ... + // ... } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private. -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- -## Deprecated methods +## Edit a status {#edit} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/statuses/:id/card" title="Preview card" >}} -{{< api-method-description >}} +```http +PUT https://mastodon.example/api/v1/statuses/:id HTTP/1.1 +``` -**Returns:** Card\ -**OAuth:** Public\ +Edit a given status to change its text, sensitivity, media attachments, or poll. Note that editing a poll's options will reset the votes. + +**Returns:** [Status]({{< relref "entities/status" >}})\ +**OAuth:** User token + `write:statuses`\ +**Version history:**\ +3.5.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The ID of the SOMETHING in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Form data parameters + +status +: String. The plain text content of the status. + +spoiler_text +: String. The plain text subject or content warning of the status. + +sensitive +: Boolean. Whether the status should be marked as sensitive. + +media_ids[] +: Array of String. Include Attachment IDs to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used. + +poll[options][] +: Array of String. Possible answers to the poll. If provided, `media_ids` cannot be used, and `poll[expires_in]` must be provided. + +poll[expires_in] +: Integer. Duration that the poll should be open, in seconds. If provided, `media_ids` cannot be used, and `poll[options]` must be provided. + +poll[multiple] +: Boolean. Allow multiple choices? Defaults to false. + +poll[hide_totals] +: Boolean. Hide vote counts until the poll ends? Defaults to false. + +#### Response +##### 200: OK + +Status has been successfully edited. + +```json +{ + "id": "108942703571991143", + "created_at": "2022-09-04T23:22:13.704Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + "uri": "https://mastodon.social/users/trwnh/statuses/108942703571991143", + "url": "https://mastodon.social/@trwnh/108942703571991143", + "replies_count": 3, + "reblogs_count": 1, + "favourites_count": 6, + "edited_at": "2022-09-05T00:33:20.309Z", + "favourited": false, + "reblogged": false, + "muted": false, + "bookmarked": false, + "pinned": false, + "content": "

this is a status that has been edited multiple times to change the text, add a poll, and change poll options.

", + "filtered": [], + "reblog": null, + "application": { + "name": "SubwayTooter", + "website": null + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Status does not exist, is private, or is not owned by you. + +```json +{ + "error": "Record not found" +} +``` + +##### 422: Unprocessable entity + +```json +{ + "error": "Validation failed: Text can't be blank" +} +``` + +--- + +## View edit history of a status {#history} + +```http +GET https://mastodon.example/api/v1/statuses/:id/history HTTP/1.1 +``` + +Get all known versions of a status, including the initial and current states. + +**Returns:** Array of [StatusEdit]({{< relref "entities/statusedit" >}})\ +**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\ +**Version history:**\ +3.5.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The local ID of the Status in the database. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +[ + { + "content": "

this is a status that will be edited

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-04T23:22:13.704Z", + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + }, + { + "content": "

this is a status that has been edited

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-04T23:22:42.555Z", + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + }, + { + "content": "

this is a status that has been edited twice

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-04T23:22:55.956Z", + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + }, + { + "content": "

this is a status that has been edited three times. this time a poll has been added.

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-05T00:01:48.160Z", + "poll": { + "options": [ + { + "title": "cool" + }, + { + "title": "uncool" + }, + { + "title": "spiderman" + } + ] + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + }, + { + "content": "

this is a status that has been edited three times. this time a poll has been added.

", + "spoiler_text": "", + "sensitive": false, + "created_at": "2022-09-05T00:03:32.480Z", + "poll": { + "options": [ + { + "title": "cool" + }, + { + "title": "uncool" + }, + { + "title": "spiderman (this option has been changed)" + } + ] + }, + "account": { + "id": "14715", + "username": "trwnh", + "acct": "trwnh", + "display_name": "infinite love ⴳ", + // ... + }, + "media_attachments": [], + "emojis": [] + } +] +``` + +##### 404: Not found + +Status does not exist or is private. + +```json +{ + "error": "Record not found" +} +``` + +--- + +## View status source {#source} + +```http +GET https://mastodon.example/api/v1/statuses/:id/source HTTP/1.1 +``` + +Obtain the source properties for a status so that it can be edited. + +**Returns:** [StatusSource]({{< relref "entities/statussource" >}})\ +**OAuth:** App token + `read:statuses`\ +**Version history:**\ +3.5.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The local ID of the Status in the database. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "id": "108942703571991143", + "text": "this is a status that will be edited", + "spoiler_text": "" +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 404: Not found + +Status does not exist or is private. + +```json +{ + "error": "Record not found" +} +``` + +--- + +## (DEPRECATED) Fetch preview card {#card} + +```http +GET https://mastodon.example/api/v1/statuses/:id/card HTTP/1.1 +``` + +**Returns:** [PreviewCard]({{< relref "entities/PreviewCard" >}})\ +**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\ **Version history:**\ 0.0.0 - added\ 2.6.0 - deprecated in favor of card property inlined on Status entity\ 3.0.0 - removed -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the status in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +#### Request +##### Path parameters -```javascript +:id +: {{}} String. The local ID of the Status in the database. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json { "url": "https://www.youtube.com/watch?v=OMv_EPMED8Y", "title": "♪ Brand New Friend (Christmas Song!)", @@ -1481,22 +1714,37 @@ ID of the status in the database "embed_url": "" } ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -Status does not exist, is deleted, or is private -{{< endapi-method-response-example-description >}} +##### 404: Not found +Status does not exist or is private. -```javascript +```json { "error": "Record not found" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses_controller.rb" caption="app/controllers/api/v1/statuses_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/bookmarks_controller.rb" caption="app/controllers/api/v1/statuses/bookmarks_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/favourited_by_accounts_controller.rb" caption="app/controllers/api/v1/statuses/favourited_by_accounts_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/favourites_controller.rb" caption="app/controllers/api/v1/statuses/favourites_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/histories_controller.rb" caption="app/controllers/api/v1/statuses/histories_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/mutes_controller.rb" caption="app/controllers/api/v1/statuses/mutes_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/pins_controller.rb" caption="app/controllers/api/v1/statuses/pins_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/reblogged_by_accounts_controller.rb" caption="app/controllers/api/v1/statuses/reblogged_by_accounts_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/reblogs_controller.rb" caption="app/controllers/api/v1/statuses/reblogs_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/sources_controller.rb" caption="app/controllers/api/v1/statuses/sources_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/statuses/media.md b/content/en/methods/statuses/media.md deleted file mode 100644 index 3558e099..00000000 --- a/content/en/methods/statuses/media.md +++ /dev/null @@ -1,397 +0,0 @@ ---- -title: media -description: >- - Attach media to authored statuses. See Using Mastodon > Posting toots > - Attachments for more information about size and format limits. -menu: - docs: - weight: 10 - parent: methods-statuses ---- - -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/media" title="Upload media as attachment" >}} -{{< api-method-description >}} - -Creates an attachment to be used with a new status. - -**Returns:** Attachment\ -**OAuth:** User token + `write:media`\ -**Version history:**\ -0.0.0 - added\ -2.3.0 - add `focus` parameter\ -3.1.3 - deprecated in favor of `POST /api/v2/media`, which is equal to v1 in all aspects, except it returns HTTP 202, and the returned JSON object has a url of null, because while the thumbnail is prepared synchronously, the full version of the media attachment will be processed in the background\ -3.2.0 - add `thumbnail` parameter - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="file" type="object" required=true >}} -The file to be attached, using multipart form data. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="thumbnail" type="object" required=false >}} -The custom thumbnail of the media to be attached, using multipart form data. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="description" type="string" required=false >}} -A plain-text description of the media, for accessibility purposes. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="focus" type="string" required=false >}} -Two floating points \(x,y\), comma-delimited, ranging from -1.0 to 1.0 (see "Focal points" below) -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Attachment created successfully. Note that the Attachment will be created even if the file is not understood correctly. -{{< endapi-method-response-example-description >}} - - -{{< tabs >}} -{{< tab title="file correct" >}} -```javascript -{ - "id": "22348641", - "type": "image", - "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/cebc6d51be03e509.jpeg", - "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/cebc6d51be03e509.jpeg", - "remote_url": null, - "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", - "meta": { - "focus": { - "x": -0.69, - "y": 0.42 - }, - "original": { - "width": 640, - "height": 480, - "size": "640x480", - "aspect": 1.3333333333333333 - }, - "small": { - "width": 461, - "height": 346, - "size": "461x346", - "aspect": 1.3323699421965318 - } - }, - "description": "test uploaded via api", - "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" -} -``` -{{< endtab >}} - -{{< tab title="file not correct" >}} -```javascript -{ - "id": "22348456", - "type": "unknown", - "url": "https://mastodon.social/files/original/missing.png", - "preview_url": "https://mastodon.social/files/small/missing.png", - "remote_url": null, - "text_url": "https://mastodon.social/media/Ao2nvQoQNHROpKgEyoA", - "meta": { - "focus": { - "x": -0.69, - "y": 0.42 - } - }, - "description": "test uploaded via api", - "blurhash": null -} -``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -File or file type is unsupported or invalid -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Validation failed: File content type is invalid, File is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/media/:id" title="Update attachment" >}} -{{< api-method-description >}} - -Get an Attachment, before it is attached to a status and posted, but after it is accepted for processing. - -**Returns:** Attachment\ -**OAuth:** User token + `write:media`\ -**Version history:**\ -3.1.3 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the Attachment entity to be updated -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="file" type="object" required=false >}} -The file to be attached, using multipart form data. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="description" type="string" required=false >}} -A plain-text description of the media, for accessibility purposes. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="focus" type="string" required=false >}} -Two floating points \(x,y\), comma-delimited ranging from -1.0 to 1.0 -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -Attachment has been processed -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "22348641", - "type": "image", - "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", - "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", - "remote_url": null, - "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", - "meta": { - "focus": { - "x": -0.42, - "y": 0.69 - }, - "original": { - "width": 640, - "height": 480, - "size": "640x480", - "aspect": 1.3333333333333333 - }, - "small": { - "width": 461, - "height": 346, - "size": "461x346", - "aspect": 1.3323699421965318 - } - }, - "description": "test uploaded via api, but updated", - "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=206 >}} -{{< api-method-response-example-description >}} - -Attachment is not yet ready -{{< endapi-method-response-example-description >}} - - -```javascript - -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -Attachment does not exist, is deleted, or was not created by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -Error processing the media attachment -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Validation failed: File content type is invalid, File is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - -{{< api-method method="put" host="https://mastodon.example" path="/api/v1/media/:id" title="Update attachment" >}} -{{< api-method-description >}} - -Update an Attachment, before it is attached to a status and posted. - -**Returns:** Attachment\ -**OAuth:** User token + `write:media`\ -**Version history:**\ -0.0.0 - added\ -3.2.0 - added `thumbnail` - - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -The id of the Attachment entity to be updated -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="file" type="object" required=false >}} -The file to be attached, using multipart form data. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="thumbnail" type="object" required=false >}} -The custom thumbnail of the media to be attached, using multipart form data. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="description" type="string" required=false >}} -A plain-text description of the media, for accessibility purposes. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="focus" type="string" required=false >}} -Two floating points \(x,y\), comma-delimited ranging from -1.0 to 1.0 -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "22348641", - "type": "image", - "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg", - "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg", - "remote_url": null, - "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ", - "meta": { - "focus": { - "x": -0.42, - "y": 0.69 - }, - "original": { - "width": 640, - "height": 480, - "size": "640x480", - "aspect": 1.3333333333333333 - }, - "small": { - "width": 461, - "height": 346, - "size": "461x346", - "aspect": 1.3323699421965318 - } - }, - "description": "test uploaded via api, but updated", - "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -Attachment does not exist, is deleted, or was not created by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -File or file type is unsupported or invalid -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Validation failed: File content type is invalid, File is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - -## Focal points - -Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. [See this guide on how focal points are defined.](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point) In summary, floating points range from -1.0 to 1.0, left-to-right or bottom-to-top. \(0,0\) is the center of the image. \(0.5, 0.5\) would be in the center of the upper-right quadrant. \(-0.5, -0.5\) would be in the center of the lower-left quadrant. For reference, thumbnails in the Mastodon frontend are most commonly 16:9. - -{{< figure src="/assets/focal-points.jpg" caption="A demonstration of various focal points and their coordinates." >}} - diff --git a/content/en/methods/statuses/polls.md b/content/en/methods/statuses/polls.md deleted file mode 100644 index 8106e9b8..00000000 --- a/content/en/methods/statuses/polls.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: polls -description: >- - View and vote on polls attached to statuses. To discover poll ID, you will - need to GET a Status first and then check for a `poll` property. -menu: - docs: - weight: 20 - parent: methods-statuses ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/polls/:id" title="View a poll" >}} -{{< api-method-description >}} - -**Returns:** Poll\ -**OAuth:** Public if parent status is public. User token + `read:statuses` if parent status is private.\ -**Version history:**\ -2.8.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the poll in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "34830", - "expires_at": "2019-12-05T04:05:08.302Z", - "expired": true, - "multiple": false, - "votes_count": 10, - "voters_count": null, - "voted": true, - "own_votes": [ - 1 - ], - "options": [ - { - "title": "accept", - "votes_count": 6 - }, - { - "title": "deny", - "votes_count": 4 - } - ], - "emojis": [] -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -Poll does not exist, or poll's parent status is private -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/polls/:id/votes" title="Vote on a poll" >}} -{{< api-method-description >}} - -**Returns:** Poll\ -**OAuth:** User token + `write:statuses`\ -**Version history:**\ -2.8.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the poll in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="choices\[\]" type="array" required=true >}} -Array of own votes containing index for each option \(starting from 0\) -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Poll was voted on -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "34873", - "expires_at": "2019-12-05T11:16:17.426Z", - "expired": false, - "multiple": true, - "votes_count": 5, - "voters_count": null, - "voted": true, - "own_votes": [ - 0, - 2, - 4, - 9, - 6 - ], - "options": [ - { - "title": "option 0", - "votes_count": 1 - }, - { - "title": "option 1", - "votes_count": 0 - }, - { - "title": "option 2", - "votes_count": 1 - }, - { - "title": "option 3", - "votes_count": 0 - }, - { - "title": "option 4", - "votes_count": 1 - }, - { - "title": "option 5", - "votes_count": 0 - }, - { - "title": "option 6", - "votes_count": 1 - }, - { - "title": "option 7", - "votes_count": 0 - }, - { - "title": "option 8", - "votes_count": 0 - }, - { - "title": "option 9", - "votes_count": 1 - } - ], - "emojis": [] -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -Poll does not exist, or poll's parent status is private -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -Already voted or poll is expired -{{< endapi-method-response-example-description >}} - - -{{< tabs >}} -{{< tab title="already voted" >}} -```javascript -{ - "error": "Validation failed: You have already voted on this poll" -} -``` -{{< endtab >}} - -{{< tab title="expired" >}} -```javascript -{ - "error": "Validation failed: The poll has already ended" -} -``` -{{< endtab >}} -{{< endtabs >}} -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/statuses/scheduled_statuses.md b/content/en/methods/statuses/scheduled_statuses.md deleted file mode 100644 index b2e3549c..00000000 --- a/content/en/methods/statuses/scheduled_statuses.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -title: scheduled_statuses -description: Schedule statuses for your instance to publish later. -menu: - docs: - weight: 30 - parent: methods-statuses ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/scheduled_statuses" title="View scheduled statuses" >}} -{{< api-method-description >}} - -**Returns:** Array of ScheduledStatus\ -**OAuth:** User token + `read:statuses`\ -**Version history:**\ -2.7.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="number" required=false >}} -Max number of results to return. Defaults to 20. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than ID -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Return results newer than ID -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than ID -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "id": "3221", - "scheduled_at": "2019-12-05T12:33:01.000Z", - "params": { - "poll": null, - "text": "test content", - "media_ids": null, - "sensitive": null, - "visibility": null, - "idempotency": null, - "scheduled_at": null, - "spoiler_text": null, - "application_id": 596551, - "in_reply_to_id": null - }, - "media_attachments": [] - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/scheduled_statuses/:id" title="View a single scheduled status" >}} -{{< api-method-description >}} - -**Returns:** ScheduledStatus\ -**OAuth:** User token + `read:statuses`\ -**Version history:**\ -2.7.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the scheduled status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "3221", - "scheduled_at": "2019-12-05T12:33:01.000Z", - "params": { - "poll": null, - "text": "test content", - "media_ids": null, - "sensitive": null, - "visibility": null, - "idempotency": null, - "scheduled_at": null, - "spoiler_text": null, - "application_id": 596551, - "in_reply_to_id": null - }, - "media_attachments": [] -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="put" host="https://mastodon.example" path="/api/v1/scheduled_statuses/:id" title="Schedule a status" >}} -{{< api-method-description >}} - -**Returns:** ScheduledStatus\ -**OAuth:** User token + `write:statuses`\ -**Version history:**\ -2.7.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the Status to be scheduled -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="scheduled_at" type="string" required=false >}} -ISO 8601 Datetime at which the status will be published. Must be at least 5 minutes into the future. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "3221", - "scheduled_at": "2019-12-05T13:33:01.000Z", - "params": { - "poll": null, - "text": "test content", - "media_ids": null, - "sensitive": null, - "visibility": null, - "idempotency": null, - "scheduled_at": null, - "spoiler_text": null, - "application_id": 596551, - "in_reply_to_id": null - }, - "media_attachments": [] -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Validation failed: Scheduled at The scheduled date must be in the future" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/scheduled_statuses/:id" title="Cancel a scheduled status" >}} -{{< api-method-description >}} - -**Returns:** empty object\ -**OAuth:** User token + `write:statuses`\ -**Version history:**\ -2.7.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the scheduled status in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -No ScheduledStatus at that id, or you do not own it -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/streaming.md b/content/en/methods/streaming.md new file mode 100644 index 00000000..c804393c --- /dev/null +++ b/content/en/methods/streaming.md @@ -0,0 +1,716 @@ +--- +title: streaming API methods +description: >- + Subscribe to server-sent events for real-time updates via a long-lived HTTP + connection or via WebSocket. +menu: + docs: + weight: 40 + name: streaming + parent: methods-timelines + identifier: methods-streaming +aliases: [ + "/methods/streaming", + "/api/methods/streaming", + "/methods/timelines/streaming", +] +--- + + + +## Event types and payloads {#events} + +`update` +: A new Status has appeared. Payload contains a [Status]({{< relref "entities/Status" >}}) cast to a string. Available since v1.0.0 + +`delete` +: A status has been deleted. Payload contains the String ID of the deleted Status. Available since v1.0.0 + +`notification` +: A new notification has appeared. Payload contains a [Notification]({{< relref "entities/Notification" >}}) cast to a string. Available since v1.4.2 + +`filters_changed` +: Keyword filters have been changed. Either does not contain a payload (for WebSocket connections), or contains an undefined payload (for HTTP connections). Available since v2.4.3 + +`conversation` +: A direct conversation has been updated. Payload contains a [Conversation]({{< relref "entities/Conversation" >}}) cast to a string. Available since v2.6.0 + +`announcement` +: An announcement has been published. Payload contains an [Announcement]({{< relref "entities/Announcement" >}}) cast to a string. Available since v3.1.0 + +`announcement.reaction` +: An announcement has received an emoji reaction. Payload contains a Hash (with `name`, `count`, and `announcement_id`) cast to a string. Available since v3.1.0 + +`announcement.delete` +: An announcement has been deleted. Payload contains the String ID of the deleted Announcement. Available since v3.1.0 + +`status.update` +: A Status has been edited. Payload contains a [Status]({{< relref "entities/Status" >}}) cast to a string. Available since v3.5.0 + +`encrypted_message` +: An encrypted message has been received. Implemented in v3.2.0 but currently unused + +## Streaming timelines/categories {#streams} + +`public` +: All public posts known to the server. Analogous to the federated timeline. Available since v1.0.0 + +`public:media` +: All public posts known to the server, filtered for media attachments. Analogous to the federated timeline with "only media" enabled. Available since v2.4.0 + +`public:local` +: All public posts originating from this server. Analogous to the local timeline. Available since v1.1 + +`public:local:media` +: All public posts originating from this server, filtered for media attachments. Analogous to the local timeline with "only media" enabled. Available since v2.4.0 + +`public:remote` +: All public posts originating from other servers. Available since v3.1.4 + +`public:remote:media` +: All public posts originating from other servers, filtered for media attachments. Available since v3.1.4 + +`hashtag` +: All public posts using a certain hashtag. Available since v1.0.0 + +`hashtag:local` +: All public posts using a certain hashtag, originating from this server. Available since v1.1 + +`user` +: Events related to the current user, such as home feed updates and notifications. Available since v1.0.0 + +`user:notification` +: Notifications for the current user. Available since v1.4.2 + +`list` +: Updates to a specific list. Available since v2.1.0 + +`direct` +: Updates to direct conversations. Available since v2.4.0 + +--- + +## About HTTP server-sent events {#http} + +Your application can use a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer; in other words, the HTTP connection is kept open and receives new data periodically. + +The stream will contain events as well as heartbeat comments. Lines that begin with a colon (`:`) can be ignored by parsers. For example, the connection may be kept alive with a heartbeat comment: + +```text +:thump +``` + +Generally, events have this structure: + +```text +event: +data: +``` + +--- + +## Check if the server is alive {#health} + +```http +GET https://mastodon.example/api/v1/streaming/health HTTP/1.1 +``` + +Verify that the streaming service is alive before connecting to it + +**Returns:** String\ +**OAuth:** Public\ +**Version history:**\ +2.5.0 - added + +#### Response +##### 200: OK + +The streaming service is alive + +```text +OK +``` + +--- + +## Watch your home timeline and notifications {#user} + +```http +GET https://mastodon.example/api/v1/streaming/user HTTP/1.1 +``` + +Returns events that are relevant to the authorized user, i.e. home timeline and notifications + +**Returns:** `update`, `delete`, `notification`, `filters_changed`, `announcement`, `announcement.reaction`, `announcement.delete`, `status.update`\ +**OAuth:** User token + `read:statuses` + `read:notifications`\ +**Version history:**\ +1.0.0 - added\ +1.4.2 - now returns `notification`\ +2.4.3 - now returns `filters_changed`\ +3.1.0 - now returns `announcement`, `announcement.reaction`, `announcement.delete`\ +3.5.0 - now returns `status.update` + + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Events + +An example update to the home timeline: + +```text +event: update +data: {"id":"108914327388663283","created_at":"2022-08-30T23:05:46.839Z","in_reply_to_id":"108914298452377720","in_reply_to_account_id":"107946650784398271","sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","url":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@disarray glad i was able to help","filtered":[],"reblog":null,"account":{"id":"464472","username":"freon","acct":"freon@letsalllovela.in","display_name":"freon","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2018-08-18T00:00:00.000Z","note":"tech archaeologist, unix weenie
#nobot","url":"https://letsalllovela.in/users/freon","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","header":"https://files.mastodon.social/cache/accounts/headers/000/464/472/original/2e94bd33745f86a6.gif","header_static":"https://files.mastodon.social/cache/accounts/headers/000/464/472/static/2e94bd33745f86a6.png","followers_count":37,"following_count":41,"statuses_count":18442,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"pronouns","value":"emacs/xemacs (or he/they)","verified_at":null},{"name":"age","value":"23.66667","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"107946650784398271","username":"disarray","url":"https://pl.nulled.red/users/disarray","acct":"disarray@pl.nulled.red"}],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +An example notification: + +```text +event: notification +data: {"id":"68739215","type":"mention","created_at":"2022-08-30T23:09:54.070Z","account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":12,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"mastodon","value":"@trwnh@mastodon.social","verified_at":null}]},"status":{"id":"108914343542683797","created_at":"2022-08-30T23:09:52.359Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://pl.nulled.red/objects/64b196c6-3bc5-44d5-8ffb-f760235ee6ca","url":"https://pl.nulled.red/objects/64b196c6-3bc5-44d5-8ffb-f760235ee6ca","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@trwnh test","filtered":[],"reblog":null,"account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":12,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"mastodon","value":"@trwnh@mastodon.social","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"14715","username":"trwnh","url":"https://mastodon.social/@trwnh","acct":"trwnh"}],"tags":[],"emojis":[],"card":null,"poll":null}} +``` + +An example filter change: + +```text +event: filters_changed +data: undefined +``` + +An example announcement: + +```text +event: announcement +data: {"id":"1","content":"

test

","starts_at":null,"ends_at":null,"all_day":true,"published_at":"2022-11-15T15:55:22.452Z","updated_at":"2022-11-15T15:55:22.528Z","mentions":[],"statuses":[],"tags":[],"emojis":[],"reactions":[]} +``` + +An example announcement reaction: + +```text +event: announcement.reaction +data: {"name":"🤔","count":1,"announcement_id":"1"} +``` + +An example announcement delete: + +```text +event: announcement.delete +data: 1 +``` + +An example status edit: + +```text +event: status.update +data: {"id":"109348677773283527","created_at":"2022-11-15T16:06:48.410Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"http://mastodon.local/users/admin/statuses/109348677773283527","url":"http://mastodon.local/@admin/109348677773283527","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:07:29.023Z","content":"

edited

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"109334860508022726","username":"admin","acct":"admin","display_name":"","locked":false,"bot":false,"discoverable":null,"group":false,"created_at":"2022-11-13T00:00:00.000Z","note":"","url":"http://mastodon.local/@admin","avatar":"http://mastodon.local/avatars/original/missing.png","avatar_static":"http://mastodon.local/avatars/original/missing.png","header":"http://mastodon.local/headers/original/missing.png","header_static":"http://mastodon.local/headers/original/missing.png","followers_count":0,"following_count":0,"statuses_count":4,"last_status_at":"2022-11-15","noindex":false,"emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"pinned":false,"filtered":[]} +``` + +--- + +## Watch your notifications {#notification} + +```http +GET https://mastodon.example/api/v1/streaming/user/notification HTTP/1.1 +``` + +Returns events for received notifications + +**Returns:** `notification`\ +**OAuth:** User token + `read:statuses` + `read:notifications`\ +**Version history:**\ +1.4.2 - added + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Events + +An example notification: + +```text +event: notification +data: {"id":"68739215","type":"mention","created_at":"2022-08-30T23:09:54.070Z","account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":12,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"mastodon","value":"@trwnh@mastodon.social","verified_at":null}]},"status":{"id":"108914343542683797","created_at":"2022-08-30T23:09:52.359Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://pl.nulled.red/objects/64b196c6-3bc5-44d5-8ffb-f760235ee6ca","url":"https://pl.nulled.red/objects/64b196c6-3bc5-44d5-8ffb-f760235ee6ca","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@trwnh test","filtered":[],"reblog":null,"account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/5396d516ae170bb0.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":12,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"mastodon","value":"@trwnh@mastodon.social","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"14715","username":"trwnh","url":"https://mastodon.social/@trwnh","acct":"trwnh"}],"tags":[],"emojis":[],"card":null,"poll":null}} +``` + +--- + +## Watch the federated timeline {#public} + +```http +GET https://mastodon.example/api/v1/streaming/public HTTP/1.1 +``` + +Returns all public statuses + +**Returns:** `update`, `delete`, `status.update`\ +**OAuth:** Public, or app token + `read:statuses`\ +**Version history:**\ +1.0.0 - added\ +2.4.0 - add `only_media` parameter\ +3.5.0 - now returns `status.update` + +#### Request +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +only_media +: Boolean. If true, return only statuses with media attachments. + +#### Events + +An example update to the federated timeline: + +```text +event: update +data: {"id":"108914354907984653","created_at":"2022-08-30T23:12:47.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mstdn.jp/users/aiueohisama/statuses/108914354891945610","url":"https://mstdn.jp/@aiueohisama/108914354891945610","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

処女の子が「処女だからキモい絡み方しちゃうかもだけど許して🥺」なんて言ってるのわたしは見たことない、童貞の甘えだよそれは 嫌われたくないなら最低限のマナーくらい身につけた方がいい

","reblog":null,"account":{"id":"272619","username":"aiueohisama","acct":"aiueohisama@mstdn.jp","display_name":"💎🌻陽菜💙💛","locked":false,"bot":false,"discoverable":false,"group":false,"created_at":"2017-04-15T00:00:00.000Z","note":"

とっても素直で真面目なOLでし！

","url":"https://mstdn.jp/@aiueohisama","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/272/619/original/573669a325c87b8b.jpeg","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/272/619/original/573669a325c87b8b.jpeg","header":"https://files.mastodon.social/cache/accounts/headers/000/272/619/original/5d5dad59a9fd1531.jpeg","header_static":"https://files.mastodon.social/cache/accounts/headers/000/272/619/original/5d5dad59a9fd1531.jpeg","followers_count":182,"following_count":20,"statuses_count":1128,"last_status_at":"2022-08-30","emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"filter_results":[]} +``` + +An example delete: + +```text +event: delete +data: 107214471804101576 +``` + +An example status edit: + +```text +event: status.update +data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://ruby.social/users/chrismo/statuses/109348684454557541","url":"https://ruby.social/@chrismo/109348684454557541","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:10:43.000Z","content":"

#musicTuesday

Here's a solo #piano track of mine called Gravity Assist

#neoclassical (#jazz ish)

https://cstudios.bandcamp.com/track/celestia-gravity-assist-no-19-var-2

","reblog":null,"account":{"id":"795442","username":"chrismo","acct":"chrismo@ruby.social","display_name":"chrismo","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2019-04-25T00:00:00.000Z","note":"

i mash keys

","url":"https://ruby.social/@chrismo","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","header":"https://static-cdn.mastodon.social/headers/original/missing.png","header_static":"https://static-cdn.mastodon.social/headers/original/missing.png","followers_count":40,"following_count":62,"statuses_count":42,"last_status_at":"2022-11-15","emojis":[],"fields":[{"name":"web","value":"clabs.org","verified_at":null},{"name":"github","value":"github.com/chrismo","verified_at":null},{"name":"twitter","value":"twitter.com/the_chrismo","verified_at":null},{"name":"bandcamp","value":"cstudios.bandcamp.com","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"MUSICTUESDAY","url":"https://mastodon.social/tags/MUSICTUESDAY"},{"name":"piano","url":"https://mastodon.social/tags/piano"},{"name":"neoclassical","url":"https://mastodon.social/tags/neoclassical"},{"name":"jazz","url":"https://mastodon.social/tags/jazz"}],"emojis":[],"card":null,"poll":null} +``` + +--- + +## Watch the local timeline {#public-local} + +```http +GET https://mastodon.example/api/v1/streaming/public/local HTTP/1.1 +``` + +Returns all local public statuses + +**Returns:** `update`, `delete`, `status.update`\ +**OAuth:** Public, or app token + `read:statuses`\ +**Version history:**\ +1.1.0 - added\ +2.4.0 - add `only_media` parameter\ +3.5.0 - now returns `status.update` + +#### Request +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +only_media +: Boolean. If true, return only statuses with media attachments. + +#### Events + +An example update to the local timeline: + +```text +event: update +data: {"id":"108914398911648589","created_at":"2022-08-30T23:23:58.863Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/trwnh/statuses/108914398911648589","url":"https://mastodon.social/@trwnh/108914398911648589","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

test

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"14715","username":"trwnh","acct":"trwnh","display_name":"infinite love ⴳ","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2016-11-24T00:00:00.000Z","note":"

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

","url":"https://mastodon.social/@trwnh","avatar":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","avatar_static":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","header":"https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg","header_static":"https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg","followers_count":2520,"following_count":266,"statuses_count":59817,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"Website","value":"https://trwnh.com","verified_at":"2019-08-29T04:14:55.571+00:00"},{"name":"Portfolio","value":"https://abdullahtarawneh.com","verified_at":"2021-02-11T20:34:13.574+00:00"},{"name":"Fan of:","value":"Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)","verified_at":null},{"name":"What to expect:","value":"talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +An example delete: + +```text +event: delete +data: 108914398911648589 +``` + +An example status edit: + +``` +event: status.update +data: {"id":"109348699525106378","created_at":"2022-11-15T16:12:20.310Z","in_reply_to_id":"109348674754176227","in_reply_to_account_id":"30437","sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/gregpak/statuses/109348699525106378","url":"https://mastodon.social/@gregpak/109348699525106378","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:12:41.694Z","content":"

By default, in Feedly it just shows a thumbnail of the images in a post, though. And NetNewsWire doesn't show any image, boo! Gotta find an RSS reader that'll show a full sized image automatically without requiring a clickthrough... any suggestions would be very welcome, thanks!

","reblog":null,"account":{"id":"30437","username":"gregpak","acct":"gregpak","display_name":"Greg Pak","locked":false,"bot":false,"discoverable":false,"group":false,"created_at":"2017-04-02T00:00:00.000Z","note":"

Comic book writer & filmmaker. Mech Cadet Yu, Planet Hulk, Darth Vader, Ronin Island, Princess Who Saved. Get vaxxed, get out the vote. He/Him.
#Comics #ComicBooks #writing #AmWriting #photography #BelieveInFilm

","url":"https://mastodon.social/@gregpak","avatar":"https://files.mastodon.social/accounts/avatars/000/030/437/original/9a71f06d6e285f32.jpg","avatar_static":"https://files.mastodon.social/accounts/avatars/000/030/437/original/9a71f06d6e285f32.jpg","header":"https://files.mastodon.social/accounts/headers/000/030/437/original/1f589d01e13340bc.jpg","header_static":"https://files.mastodon.social/accounts/headers/000/030/437/original/1f589d01e13340bc.jpg","followers_count":2307,"following_count":279,"statuses_count":818,"last_status_at":"2022-11-15","noindex":false,"emojis":[],"fields":[{"name":"Website/Blog","value":"https://gregpak.com/","verified_at":"2022-11-04T19:59:52.817+00:00"},{"name":"Newsletter","value":"https://gregpak.com/newsletter","verified_at":"2022-11-04T19:59:58.287+00:00"},{"name":"Shop","value":"https://gregpakshop.com/pages/about-us","verified_at":"2022-11-07T05:50:02.310+00:00"}]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +--- + +## Watch for remote statuses {#public-remote} + +```http +GET https://mastodon.example/api/v1/streaming/public/remote HTTP/1.1 +``` + +Returns all public statuses from remote servers. + +**Returns:** `update`, `delete`, `status.update`\ +**OAuth:** Public, or app token + `read:statuses`\ +**Version history:**\ +3.1.4 - added\ +3.5.0 - now returns `status.update` + +#### Request +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +only_media +: Boolean. If true, return only statuses with media attachments. + +#### Events + +An example update: + +```text +event: update +data: {"id":"108914354907984653","created_at":"2022-08-30T23:12:47.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mstdn.jp/users/aiueohisama/statuses/108914354891945610","url":"https://mstdn.jp/@aiueohisama/108914354891945610","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

処女の子が「処女だからキモい絡み方しちゃうかもだけど許して🥺」なんて言ってるのわたしは見たことない、童貞の甘えだよそれは 嫌われたくないなら最低限のマナーくらい身につけた方がいい

","reblog":null,"account":{"id":"272619","username":"aiueohisama","acct":"aiueohisama@mstdn.jp","display_name":"💎🌻陽菜💙💛","locked":false,"bot":false,"discoverable":false,"group":false,"created_at":"2017-04-15T00:00:00.000Z","note":"

とっても素直で真面目なOLでし！

","url":"https://mstdn.jp/@aiueohisama","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/272/619/original/573669a325c87b8b.jpeg","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/272/619/original/573669a325c87b8b.jpeg","header":"https://files.mastodon.social/cache/accounts/headers/000/272/619/original/5d5dad59a9fd1531.jpeg","header_static":"https://files.mastodon.social/cache/accounts/headers/000/272/619/original/5d5dad59a9fd1531.jpeg","followers_count":182,"following_count":20,"statuses_count":1128,"last_status_at":"2022-08-30","emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"filter_results":[]} +``` + +An example delete: + +```text +event: delete +data: 107214471804101576 +``` + +An example status edit: + +```text +event: status.update +data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://ruby.social/users/chrismo/statuses/109348684454557541","url":"https://ruby.social/@chrismo/109348684454557541","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:10:43.000Z","content":"

#musicTuesday

Here's a solo #piano track of mine called Gravity Assist

#neoclassical (#jazz ish)

https://cstudios.bandcamp.com/track/celestia-gravity-assist-no-19-var-2

","reblog":null,"account":{"id":"795442","username":"chrismo","acct":"chrismo@ruby.social","display_name":"chrismo","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2019-04-25T00:00:00.000Z","note":"

i mash keys

","url":"https://ruby.social/@chrismo","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","header":"https://static-cdn.mastodon.social/headers/original/missing.png","header_static":"https://static-cdn.mastodon.social/headers/original/missing.png","followers_count":40,"following_count":62,"statuses_count":42,"last_status_at":"2022-11-15","emojis":[],"fields":[{"name":"web","value":"clabs.org","verified_at":null},{"name":"github","value":"github.com/chrismo","verified_at":null},{"name":"twitter","value":"twitter.com/the_chrismo","verified_at":null},{"name":"bandcamp","value":"cstudios.bandcamp.com","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"MUSICTUESDAY","url":"https://mastodon.social/tags/MUSICTUESDAY"},{"name":"piano","url":"https://mastodon.social/tags/piano"},{"name":"neoclassical","url":"https://mastodon.social/tags/neoclassical"},{"name":"jazz","url":"https://mastodon.social/tags/jazz"}],"emojis":[],"card":null,"poll":null} +``` + +--- + +## Watch the public timeline for a hashtag {#hashtag} + +```http +GET https://mastodon.example/api/v1/streaming/hashtag HTTP/1.1 +``` + +Returns all public statuses for a particular hashtag + +**Returns:** `update`, `delete`, `status.update`\ +**OAuth:** Public, or app token + `read:statuses`\ +**Version history:**\ +1.0.0 - added\ +3.5.0 - now returns `status.update` + +#### Request +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +tag +: {{}} String. The name of the hashtag to watch. + +#### Events + +An example update to the hashtag timeline: + +```text +event: update +data: {"id":"108914430312582020","created_at":"2022-08-30T23:31:58.006Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/trwnh/statuses/108914430312582020","url":"https://mastodon.social/@trwnh/108914430312582020","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

#test

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"14715","username":"trwnh","acct":"trwnh","display_name":"infinite love ⴳ","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2016-11-24T00:00:00.000Z","note":"

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

","url":"https://mastodon.social/@trwnh","avatar":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","avatar_static":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","header":"https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg","header_static":"https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg","followers_count":2520,"following_count":266,"statuses_count":59817,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"Website","value":"https://trwnh.com","verified_at":"2019-08-29T04:14:55.571+00:00"},{"name":"Portfolio","value":"https://abdullahtarawneh.com","verified_at":"2021-02-11T20:34:13.574+00:00"},{"name":"Fan of:","value":"Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)","verified_at":null},{"name":"What to expect:","value":"talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"test","url":"https://mastodon.social/tags/test"}],"emojis":[],"card":null,"poll":null} +``` + +An example delete: + +```text +event: delete +data: 108914430312582020 +``` + +An example status edit: + +```text +event: status.update +data: {"id":"109348684737626801","created_at":"2022-11-15T16:08:30.000Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://ruby.social/users/chrismo/statuses/109348684454557541","url":"https://ruby.social/@chrismo/109348684454557541","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":"2022-11-15T16:10:43.000Z","content":"

#musicTuesday

Here's a solo #piano track of mine called Gravity Assist

#neoclassical (#jazz ish)

https://cstudios.bandcamp.com/track/celestia-gravity-assist-no-19-var-2

","reblog":null,"account":{"id":"795442","username":"chrismo","acct":"chrismo@ruby.social","display_name":"chrismo","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2019-04-25T00:00:00.000Z","note":"

i mash keys

","url":"https://ruby.social/@chrismo","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/795/442/original/12084217a7eb7513.png","header":"https://static-cdn.mastodon.social/headers/original/missing.png","header_static":"https://static-cdn.mastodon.social/headers/original/missing.png","followers_count":40,"following_count":62,"statuses_count":42,"last_status_at":"2022-11-15","emojis":[],"fields":[{"name":"web","value":"clabs.org","verified_at":null},{"name":"github","value":"github.com/chrismo","verified_at":null},{"name":"twitter","value":"twitter.com/the_chrismo","verified_at":null},{"name":"bandcamp","value":"cstudios.bandcamp.com","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"MUSICTUESDAY","url":"https://mastodon.social/tags/MUSICTUESDAY"},{"name":"piano","url":"https://mastodon.social/tags/piano"},{"name":"neoclassical","url":"https://mastodon.social/tags/neoclassical"},{"name":"jazz","url":"https://mastodon.social/tags/jazz"}],"emojis":[],"card":null,"poll":null} +``` + +--- + +## Watch the local timeline for a hashtag {#hashtag-local} + +```http +GET https://mastodon.example/api/v1/streaming/hashtag/local HTTP/1.1 +``` + +Returns all local public statuses for a particular hashtag + +**Returns:** `update`, `delete`, `status.update`\ +**OAuth:** Public, or app token + `read:statuses`\ +**Version history:**\ +1.1.0 - added\ +3.5.0 - now returns `status.update` + +#### Request +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +tag +: {{}} String. The name of the hashtag to watch. + +#### Events + +An example update to the local hashtag timeline: + +```text +event: update +data: {"id":"108914430312582020","created_at":"2022-08-30T23:31:58.006Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/trwnh/statuses/108914430312582020","url":"https://mastodon.social/@trwnh/108914430312582020","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

#test

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"14715","username":"trwnh","acct":"trwnh","display_name":"infinite love ⴳ","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2016-11-24T00:00:00.000Z","note":"

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

","url":"https://mastodon.social/@trwnh","avatar":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","avatar_static":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","header":"https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg","header_static":"https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg","followers_count":2520,"following_count":266,"statuses_count":59817,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"Website","value":"https://trwnh.com","verified_at":"2019-08-29T04:14:55.571+00:00"},{"name":"Portfolio","value":"https://abdullahtarawneh.com","verified_at":"2021-02-11T20:34:13.574+00:00"},{"name":"Fan of:","value":"Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)","verified_at":null},{"name":"What to expect:","value":"talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"test","url":"https://mastodon.social/tags/test"}],"emojis":[],"card":null,"poll":null} +``` + +An example delete: + +```text +event: delete +data: 108914430312582020 +``` + +An example status edit: + +```text +event: status.update +data: {"id":"108914430312582020","created_at":"2022-08-30T23:32:12.006Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://mastodon.social/users/trwnh/statuses/108914430312582020","url":"https://mastodon.social/@trwnh/108914430312582020","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"content":"

#test but edited

","reblog":null,"application":{"name":"Web","website":null},"account":{"id":"14715","username":"trwnh","acct":"trwnh","display_name":"infinite love ⴳ","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2016-11-24T00:00:00.000Z","note":"

i have approximate knowledge of many things. perpetual student. (nb/ace/they)

xmpp/email: a@trwnh.com
https://trwnh.com
help me live: https://liberapay.com/trwnh or paypal

- my triggers are moths and glitter
- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise
- dm me if i did something wrong, so i can improve
- purest person on fedi, do not lewd in my presence

","url":"https://mastodon.social/@trwnh","avatar":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","avatar_static":"https://files.mastodon.social/accounts/avatars/000/014/715/original/e430cc93d56f5ac2.png","header":"https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg","header_static":"https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg","followers_count":2520,"following_count":266,"statuses_count":59817,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"Website","value":"https://trwnh.com","verified_at":"2019-08-29T04:14:55.571+00:00"},{"name":"Portfolio","value":"https://abdullahtarawneh.com","verified_at":"2021-02-11T20:34:13.574+00:00"},{"name":"Fan of:","value":"Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)","verified_at":null},{"name":"What to expect:","value":"talking about various things i find interesting, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people! and to spill my thoughts.","verified_at":null}]},"media_attachments":[],"mentions":[],"tags":[{"name":"test","url":"https://mastodon.social/tags/test"}],"emojis":[],"card":null,"poll":null} +``` + +--- + +## Watch for list updates {#list} + +```http +GET https://mastodon.example/api/v1/streaming/list HTTP/1.1 +``` + +Returns statuses for a list + +**Returns:** `update`, `delete`, `status.update`\ +**OAuth:** User token + `read:statuses`\ +**Version history:**\ +2.1.0 - added\ +3.5.0 - now returns `status.update` + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +list +: {{}} String. The ID of the list to watch. + +#### Events + +An example update to the list timeline: + +```text +event: update +data: {"id":"108914327388663283","created_at":"2022-08-30T23:05:46.839Z","in_reply_to_id":"108914298452377720","in_reply_to_account_id":"107946650784398271","sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","url":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@disarray glad i was able to help","filtered":[],"reblog":null,"account":{"id":"464472","username":"freon","acct":"freon@letsalllovela.in","display_name":"freon","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2018-08-18T00:00:00.000Z","note":"tech archaeologist, unix weenie
#nobot","url":"https://letsalllovela.in/users/freon","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","header":"https://files.mastodon.social/cache/accounts/headers/000/464/472/original/2e94bd33745f86a6.gif","header_static":"https://files.mastodon.social/cache/accounts/headers/000/464/472/static/2e94bd33745f86a6.png","followers_count":37,"following_count":41,"statuses_count":18442,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"pronouns","value":"emacs/xemacs (or he/they)","verified_at":null},{"name":"age","value":"23.66667","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"107946650784398271","username":"disarray","url":"https://pl.nulled.red/users/disarray","acct":"disarray@pl.nulled.red"}],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +An example delete: + +```text +event: delete +data: 108914398911648589 +``` + +An example status edit: + +```text +event: status.update +data: {"id":"108914327388663283","created_at":"2022-08-30T23:05:53.839Z","in_reply_to_id":"108914298452377720","in_reply_to_account_id":"107946650784398271","sensitive":false,"spoiler_text":"","visibility":"unlisted","language":null,"uri":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","url":"https://letsalllovela.in/objects/e9cebb0c-7c75-414f-9608-20b5628e52d7","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"@disarray glad i was able to help","filtered":[],"reblog":null,"account":{"id":"464472","username":"freon","acct":"freon@letsalllovela.in","display_name":"freon","locked":false,"bot":false,"discoverable":true,"group":false,"created_at":"2018-08-18T00:00:00.000Z","note":"tech archaeologist, unix weenie
#nobot","url":"https://letsalllovela.in/users/freon","avatar":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/000/464/472/original/bfc518d70cf6f13a.png","header":"https://files.mastodon.social/cache/accounts/headers/000/464/472/original/2e94bd33745f86a6.gif","header_static":"https://files.mastodon.social/cache/accounts/headers/000/464/472/static/2e94bd33745f86a6.png","followers_count":37,"following_count":41,"statuses_count":18442,"last_status_at":"2022-08-30","emojis":[],"fields":[{"name":"pronouns","value":"emacs/xemacs (or he/they)","verified_at":null},{"name":"age","value":"23.66667","verified_at":null}]},"media_attachments":[],"mentions":[{"id":"107946650784398271","username":"disarray","url":"https://pl.nulled.red/users/disarray","acct":"disarray@pl.nulled.red"}],"tags":[],"emojis":[],"card":null,"poll":null} +``` + +--- + +## Watch for direct messages {#direct} + +```http +GET https://mastodon.example/api/v1/streaming/direct HTTP/1.1 +``` + +Returns events for received direct messages. + +**Returns:** `conversation`\ +**OAuth:** User token + `read:statuses`\ +**Version history:**\ +2.4.0 - added\ +2.6.0 - now returns `conversation` instead of `update` + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Events + +#### Events + +An example conversation being updated: + +```text +event: conversation +data: {"id":"819516","unread":true,"accounts":[{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/975674b2caa61034.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/975674b2caa61034.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":362,"last_status_at":"2022-11-13","emojis":[],"fields":[]}],"last_status":{"id":"109346889330629417","created_at":"2022-11-15T08:31:57.476Z","in_reply_to_id":null,"in_reply_to_account_id":null,"sensitive":false,"spoiler_text":"","visibility":"direct","language":null,"uri":"https://pl.nulled.red/objects/c869c5be-c184-4706-a45d-3459d9aa711c","url":"https://pl.nulled.red/objects/c869c5be-c184-4706-a45d-3459d9aa711c","replies_count":0,"reblogs_count":0,"favourites_count":0,"edited_at":null,"favourited":false,"reblogged":false,"muted":false,"bookmarked":false,"content":"test @trwnh","filtered":[],"reblog":null,"account":{"id":"108892712797543112","username":"a","acct":"a@pl.nulled.red","display_name":"a","locked":false,"bot":true,"discoverable":false,"group":false,"created_at":"2022-08-27T00:00:00.000Z","note":"a (pleroma edition)","url":"https://pl.nulled.red/users/a","avatar":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/975674b2caa61034.png","avatar_static":"https://files.mastodon.social/cache/accounts/avatars/108/892/712/797/543/112/original/975674b2caa61034.png","header":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","header_static":"https://files.mastodon.social/cache/accounts/headers/108/892/712/797/543/112/original/f61d0382356caa0e.png","followers_count":0,"following_count":0,"statuses_count":362,"last_status_at":"2022-11-13","emojis":[],"fields":[]},"media_attachments":[],"mentions":[{"id":"14715","username":"trwnh","url":"https://mastodon.social/@trwnh","acct":"trwnh"}],"tags":[],"emojis":[],"card":null,"poll":null}} +``` + +--- + +## Establishing a WebSocket connection {#websocket} + +```http +wss://mastodon.example/api/v1/streaming +``` + +**Returns:** Stream of [Event](#events)\ +**OAuth:** Public, or user token + `read` (or `read:statuses` and/or `read:notifications`)\ +**Version history:**\ +3.3.0 - added + +Open a multiplexed WebSocket connection to receive events. + +##### Parameters + +{{< hint style="info" >}} +Query parameters are recommended for single-purpose connections, but parameters may also be provided by sending a JSON-encoded payload over the WebSocket connection with `type` parameter. + +Example subscription to local statuses containing the hashtag `#foo`: + +```json +{ "type": "subscribe", "stream": "hashtag:local", "tag": "foo" } +``` + +Example unsubscription from user updates: + +```json +{ "type": "unsubscribe", "stream": "user" } +``` +{{}} + +access_token +: {{}} String. A user-authorized OAuth token. + +stream +: {{}} String. The stream to watch for events. See [Streams](#streams) for possible values. + +list +: String. When `stream` is set to `list`, use this parameter to specify the list ID. + +tag +: String. When `stream` is set to `hashtag` or `hashtag:local`, use this parameter to specify the tag name. + +type +: String. For JSON-encoded payloads sent to the server, specify either `subscribe` or `unsubscribe` in order to manage the events that you wish to receive. + + +##### Events + +Events are JSON-encoded. If an invalid access token is provided, the connection will be closed immediately. If your server has enabled limited federation mode or authorized-fetch mode, then an access token must be provided in order to receive events. + +An example update to the public timeline: + +```json +{ + "stream": [ + "public" + ], + "event": "update", + "payload": "{\"id\":\"108913983692647032\",\"created_at\":\"2022-08-30T21:38:22.000Z\",\"in_reply_to_id\":\"108913981098896721\",\"in_reply_to_account_id\":\"1081104\",\"sensitive\":false,\"spoiler_text\":\"\",\"visibility\":\"public\",\"language\":\"en\",\"uri\":\"https://fosstodon.org/users/tobtobxx/statuses/108913983628474640\",\"url\":\"https://fosstodon.org/@tobtobxx/108913983628474640\",\"replies_count\":0,\"reblogs_count\":0,\"favourites_count\":0,\"edited_at\":null,\"content\":\"

And now I can't exit the inner nvim because I mapped escape to the parent vim instance 😂

\",\"reblog\":null,\"account\":{\"id\":\"1081104\",\"username\":\"tobtobxx\",\"acct\":\"tobtobxx@fosstodon.org\",\"display_name\":\"TobTobXX\",\"locked\":false,\"bot\":false,\"discoverable\":true,\"group\":false,\"created_at\":\"2020-01-10T00:00:00.000Z\",\"note\":\"

Young tech enthusiast. Likes software (and also general, just not work-) minimalsim. Constantly trying to escape big-tech software.
Other hobbies include making music, stargazing, math and recently chess, but there's a lot that piques my interest and a lot left to learn out there.

„Of course, every house is constructed by someone, but the one who constructed all things is God.“ (Hebrews 3:4 [nwt18])

\",\"url\":\"https://fosstodon.org/@tobtobxx\",\"avatar\":\"https://files.mastodon.social/cache/accounts/avatars/001/081/104/original/230a8d0fb54e249b.png\",\"avatar_static\":\"https://files.mastodon.social/cache/accounts/avatars/001/081/104/original/230a8d0fb54e249b.png\",\"header\":\"https://static-cdn.mastodon.social/headers/original/missing.png\",\"header_static\":\"https://static-cdn.mastodon.social/headers/original/missing.png\",\"followers_count\":150,\"following_count\":216,\"statuses_count\":2447,\"last_status_at\":\"2022-08-30\",\"emojis\":[],\"fields\":[{\"name\":\"📍 Lives in:\",\"value\":\"Switzerland (CET: UTC+1 or CEST: UTC+2)\",\"verified_at\":null},{\"name\":\"🔑 GPG key:\",\"value\":\"EA23 42C5 3EBF 2A2D 985C 416A 12AC 3D47 52E2 FA2E\",\"verified_at\":null}]},\"media_attachments\":[],\"mentions\":[],\"tags\":[],\"emojis\":[],\"card\":null,\"poll\":null}" +} +``` + +{{< hint style="warning" >}} +Note that while the event is JSON-encoded, the `payload` is string-encoded and escaped, so it must be parsed and loaded as JSON from that string. +{{}} + +An example delete event from the public timeline: + +```json +{ + "stream": [ + "public" + ], + "event": "delete", + "payload": "106692867363994015" +} +``` + +An example filter change by the user: + +```json +{ + "stream": [ + "user" + ], + "event": "filters_changed" +} +``` + +{{< hint style="warning" >}} +Note that the `payload` property is not present for `filters_changed` events. +{{}} + +## See also + +### Streaming server + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/streaming/index.js" caption="streaming/index.js" }} + +### Backend event publishing + +Streaming timelines are maintained in Redis, and are published to Redis via `redis.publish()` + +#### Status events + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/fan_out_on_write_service.rb" caption="app/services/fan_out_on_write_service.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/remove_status_service.rb" caption="app/services/remove_status_service.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/batched_remove_status_service.rb" caption="app/services/batched_remove_status_service.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_conversation_worker.rb" caption="app/workers/push_conversation_worker.rb" }} + +#### User events + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/lib/feed_manager.rb" caption="app/lib/feed_manager.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_update_worker.rb" caption="app/workers/push_update_worker.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/services/notify_service.rb" caption="app/services/notify_service.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/custom_filter.rb" caption="app/models/custom_filter.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/publish_scheduled_announcement_worker.rb" caption="app/workers/publish_scheduled_announcement_worker.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/publish_announcement_reaction_worker.rb" caption="app/workers/publish_announcement_reaction_worker.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/unpublish_announcement_worker.rb" caption="app/workers/unpublish_announcement_worker.rb" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/workers/push_encrypted_message_worker.rb" caption="app/workers/push_encrypted_message_worker.rb" }} + +### Streaming client + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/stream.js" caption="app/javascript/mastodon/stream.js" }} + +{{ caption-link url="https://github.com/mastodon/mastodon/blob/main/app/javascript/mastodon/actions/streaming.js" caption="app/javascript/mastodon/actions/streaming.js" }} \ No newline at end of file diff --git a/content/en/methods/suggestions.md b/content/en/methods/suggestions.md new file mode 100644 index 00000000..833d44ea --- /dev/null +++ b/content/en/methods/suggestions.md @@ -0,0 +1,201 @@ +--- +title: suggestions API methods +description: >- + Server-generated suggestions on who to follow, based on previous positive + interactions. +menu: + docs: + weight: 120 + name: suggestions + parent: methods-accounts + identifier: methods-suggestions +aliases: [ + "/methods/suggestions", + "/api/methods/suggestions", + "/methods/accounts/suggestions", +] +--- + + + +## View follow suggestions (v2) {#v2} + +```http +GET https://mastodon.example/api/v2/suggestions HTTP/1.1 +``` + +Accounts that are promoted by staff, or that the user has had past positive interactions with, but is not yet following. + +**Returns:** Array of [Suggestion]({{< relref "entities/Suggestion" >}})\ +**OAuth:** User token + `read`\ +**Version history:**\ +3.4.0 - added + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +```json +[ + { + "source": "past_interactions", + "account": { + "id": "784058", + "username": "katie", + "acct": "katie@pleroma.voidlurker.net", + // ... + }, + // ... + { + "source": "global", + "account": { + "id": "108194863260762493", + "username": "thunderbird", + "acct": "thunderbird@mastodon.online", + // ... + } +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## Remove a suggestion {#remove} + +```http +DELETE https://mastodon.example/api/v1/suggestions/:account_id HTTP/1.1 +``` + +Remove an account from follow suggestions. + +**Returns:** n/a\ +**OAuth:** User token + `read`\ +**Version history:**\ +2.4.3 - added + +#### Request + +##### Path parameters + +:account_id +: {{}} String. The ID of the Account in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +A successful call will return an empty object. Note the call will be successful even if the account id provided is invalid or is not a suggested account. + +```json +{} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## (DEPRECATED) View follow suggestions (v1) {#v1} + +```http +GET https://mastodon.example/api/v1/suggestions HTTP/1.1 +``` + +Accounts the user has had past positive interactions with, but is not yet following. + +**Returns:** Array of [Account]({{< relref "entities/Account" >}})\ +**OAuth:** User token + `read`\ +**Version history:**\ +2.4.3 - added\ +3.4.0 - deprecated + +#### Request +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 40. + +#### Response +##### 200: OK + +```json +[ + { + "id": "332766", + "username": "kaniini", + "acct": "kaniini@pleroma.site", + // ... + }, + { + "id": "689455", + "username": "interneteh", + "acct": "interneteh@sunbeam.city", + // ... + }, + { + "id": "764276", + "username": "Dee", + "acct": "Dee@fedi.underscore.world", + // ... + }, + // ... +] +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/accounts#follow" caption="POST /api/v1/accounts/:id/follow" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/suggestions_controller.rb" caption="app/controllers/api/v2/suggestions_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/suggestions_controller.rb" caption="app/controllers/api/v1/suggestions_controller.rb" >}} + diff --git a/content/en/methods/tags.md b/content/en/methods/tags.md new file mode 100644 index 00000000..6eaa87dc --- /dev/null +++ b/content/en/methods/tags.md @@ -0,0 +1,281 @@ +--- +title: tags API methods +description: View information about or follow/unfollow hashtags. +menu: + docs: + weight: 120 + name: tags + parent: methods-accounts + identifier: methods-tags +aliases: [ + "/methods/tags", + "/api/methods/tags", +] +--- + +## View information about a single tag {#get} + +```http +GET https://mastodon.example/api/v1/tags/:id HTTP/1.1 +``` + +Show a hashtag and its associated information + +**Returns:** [Tag]({{< relref "entities/Tag" >}})\ +**OAuth:** Public, or User token\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The name of the hashtag. + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +```json +{ + "name": "Test", + "url": "http://mastodon.example/tags/test", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "1", + "uses": "1" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ], + "following": false +} +``` + +--- + +## Follow a hashtag {#follow} + +```http +POST https://mastodon.example/api/v1/tags/:id/follow HTTP/1.1 +``` + +Follow a hashtag. Posts containing a followed hashtag will be inserted into your home timeline. + +**Returns:** [Tag]({{< relref "entities/Tag" >}})\ +**OAuth:** User token + `write:follows`\ +**Version history:**\ +4.0.0 - added\ +4.0.3 - this action is now idempotent + +#### Request + +##### Path parameters + +:id +: {{}} String. The name of the hashtag. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Tag has been successfully followed + +```json +{ + "name": "Test", + "url": "http://mastodon.example/tags/test", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "1", + "uses": "1" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ], + "following": true +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +##### 422: Unprocessable entity + +Prior to 4.0.3: Tag was already followed + +```json +{ + "error": "Duplicate record" +} +``` + +--- + +## Unfollow a hashtag {#unfollow} + +```http +POST https://mastodon.example/api/v1/tags/:id/unfollow HTTP/1.1 +``` + +Unfollow a hashtag. Posts containing this hashtag will no longer be inserted into your home timeline. + +**Returns:** [Tag]({{< relref "entities/Tag" >}})\ +**OAuth:** User token + `write:follows`\ +**Version history:**\ +4.0.0 - added + +#### Request + +##### Path parameters + +:id +: {{}} String. The name of the hashtag. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +#### Response +##### 200: OK + +Tag has been successfully unfollowed, or was already unfollowed + +```json +{ + "name": "Test", + "url": "http://mastodon.example/tags/test", + "history": [ + { + "day": "1668556800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668470400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668384000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668297600", + "accounts": "1", + "uses": "1" + }, + { + "day": "1668211200", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668124800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1668038400", + "accounts": "0", + "uses": "0" + } + ], + "following": false +} +``` + +##### 401: Unauthorized + +Invalid or missing Authorization header. + +```json +{ + "error": "The access token is invalid" +} +``` + +--- + +## See also + +{{< page-relref ref="methods/followed_tags#get" caption="GET /api/v1/followed_tags" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/tags_controller.rb" caption="app/controllers/api/v1/tags_controller.rb" >}} + diff --git a/content/en/methods/timelines.md b/content/en/methods/timelines.md index dc5d27f5..ecc61e4f 100644 --- a/content/en/methods/timelines.md +++ b/content/en/methods/timelines.md @@ -1,17 +1,29 @@ --- -title: timelines +title: timelines API methods description: Read and view timelines of statuses. menu: docs: weight: 40 + name: timelines parent: methods identifier: methods-timelines +aliases: [ + "/methods/timelines", + "/api/methods/timelines", +] --- -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/timelines/public" title="Public timeline" >}} -{{< api-method-description >}} + -**Returns:** Array of Status\ +## View public timeline {#public} + +```http +GET https://mastodon.example/api/v1/timelines/public HTTP/1.1 +``` + +**Returns:** Array of [Status]({{}})\ **OAuth:** Public. Requires app token + `read:statuses` if the instance has disabled public preview.\ **Version history:**\ 0.0.0 - added\ @@ -21,69 +33,71 @@ menu: 3.1.4 - added `remote`\ 3.3.0 - both `min_id` and `max_id` can be used at the same time now -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="local" type="boolean" required=false >}} -Show only local statuses? Defaults to false. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="remote" type="boolean" required=false >}} -Show only remote statuses? Defaults to false. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="only_media" type="boolean" required=false >}} -Show only statuses with media attached? Defaults to false. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than this id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Return results newer than this id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than this id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="integer" required=false >}} -Maximum number of results to return. Defaults to 20. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +local +: Boolean. Show only local statuses? Defaults to false. + +remote +: Boolean. Show only remote statuses? Defaults to false. + +only_media +: Boolean. Show only statuses with media attached? Defaults to false. + +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 20. Max 40. + +#### Response +##### 200: OK Sample API call with limit=2 -{{< endapi-method-response-example-description >}} - -```javascript +```json [ { "id": "103206804533200177", "created_at": "2019-11-26T23:27:31.000Z", - ... + // ... "visibility": "public", - ... + // ... }, { "id": "103206804086086361", "created_at": "2019-11-26T23:27:32.000Z", - ... + // ... "visibility": "public", - ... + // ... } ] ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/timelines/tag/:hashtag" title="Hashtag timeline" >}} -{{< api-method-description >}} + +--- + +## View hashtag timeline {#tag} + +```http +GET https://mastodon.example/api/v1/timelines/tag/:hashtag HTTP/1.1 +``` View public statuses containing the given hashtag. -**Returns:** Array of Status\ +**Returns:** Array of [Status]({{}})\ **OAuth:** Public. Requires app token + `read:statuses` if the instance has disabled public preview.\ **Version history:**\ 0.0.0 - added\ @@ -92,69 +106,69 @@ View public statuses containing the given hashtag. 3.0.0 - auth is required if public preview is disabled\ 3.3.0 - both `min_id` and `max_id` can be used at the same time now -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":hashtag" type="string" required=true >}} -Content of a \#hashtag, not including \# symbol. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="local" type="boolean" required=false >}} -If true, return only local statuses. Defaults to false. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="only_media" type="boolean" required=false >}} -If true, return only statuses with media attachments. Defaults to false. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than this ID. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Return results newer than this ID. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than this ID. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="integer" required=false >}} -Maximum number of results to return. Defaults to 20. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:hashtag +: {{}} String. The name of the hashtag (not including the \# symbol). + +##### Headers + +Authorization +: Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +local +: Boolean. Return only local statuses? Defaults to false. + +only_media +: Boolean. Return only statuses with media attachments? Defaults to false. + +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 20. Max 40. + +#### Response +##### 200: OK Sample timeline for the hashtag \#cats and limit=2 -{{< endapi-method-response-example-description >}} - -```javascript +```json [ { "id": "103206185588894565", "created_at": "2019-11-26T20:50:15.866Z", - ... + // ... "visibility": "public", - ... + // ... "content": "

#cats

", - ... + // ... "tags": [ { "name": "cats", "url": "https://mastodon.social/tags/cats" } ], - ... + // ... }, { "id": "103203659567597966", "created_at": "2019-11-26T10:07:49.000Z", - ... + // ... "visibility": "public", - ... + // ... "content": "

Caught on the hop. 😺

#Qualitätskatzen #cats #mastocats #catsofmastodon #Greece #Agistri
(photo: @kernpanik | license: CC BY-NC-SA 4.0)

", - ... + // ... "tags": [ { "name": "qualitätskatzen", @@ -181,238 +195,244 @@ Sample timeline for the hashtag \#cats and limit=2 "url": "https://mastodon.social/tags/agistri" } ], - ... + // ... } ] ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/timelines/home" title="Home timeline" >}} -{{< api-method-description >}} + +##### 404: Not found + +Hashtag does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## View home timeline {#home} + +```http +GET https://mastodon.example/api/v1/timelines/home HTTP/1.1 +``` View statuses from followed users. -**Returns:** Array of Status\ +**Returns:** Array of [Status]({{}})\ **OAuth:** User + `read:statuses`\ **Version history:**\ 0.0.0 - added\ 2.6.0 - add `min_id`\ 3.3.0 - both `min_id` and `max_id` can be used at the same time now -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Return results newer than id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than id -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results to return. Defaults to 20. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="local" type="boolean" required=false >}} -Return only local statuses? -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 20. Max 40. + +#### Response +##### 200: OK Statuses in your home timeline will be returned -{{< endapi-method-response-example-description >}} - -```javascript +```json [ { "id": "103206791453397862", "created_at": "2019-11-26T23:24:13.113Z", - ... + // ... }, - ... + // ... ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=206 >}} -{{< api-method-response-example-description >}} + +##### 206: Partial content Home feed is regenerating -{{< endapi-method-response-example-description >}} - +```text ``` -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized +Invalid or missing Authorization header. -```javascript +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/timelines/list/:list_id" title="List timeline" >}} -{{< api-method-description >}} + +--- + +## View list timeline {#list} + +```http +GET https://mastodon.example/api/v1/timelines/list/:list_id HTTP/1.1 +``` View statuses in the given list timeline. -**Returns:** Array of Status\ +**Returns:** Array of [Status]({{}})\ **OAuth:** User token + `read:lists`\ **Version history:**\ 2.1.0 - added\ 2.6.0 - add `min_id`\ 3.3.0 - both `min_id` and `max_id` can be used at the same time now -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":list_id" type="string" required=true >}} -Local ID of the list in the database. -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than this ID. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Return results newer than this ID. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than this ID. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="integer" required=false >}} -Maximum number of results to return. Defaults to 20.Return results older than this ID. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request + +##### Path parameters + +:list_id +: {{}} String. Local ID of the List in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. + +##### Query parameters + +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 20. Max 40. + +#### Response +##### 200: OK Statuses in this list will be returned. -{{< endapi-method-response-example-description >}} - -```javascript +```json [ { "id": "103206791453397862", "created_at": "2019-11-26T23:24:13.113Z", - ... + // ... }, - ... + // ... ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized -```javascript +Invalid or missing Authorization header. + +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="" path="/api/v1/timelines/direct" title="\[DEPRECATED\] Direct timeline" >}} -{{< api-method-description >}} + +##### 404: Not found + +List is not owned by you or does not exist + +```json +{ + "error": "Record not found" +} +``` + +--- + +## (DEPRECATED) View direct timeline {#direct} + +```http +GET https://mastodon.example/api/v1/timelines/direct HTTP/1.1 +``` View statuses with a "direct" privacy, from your account or in your notifications. -**Returns:** Array of Status\ +**Returns:** Array of [Status]({{}})\ **OAuth:** User token + `read:statuses`\ **Version history:**\ x.x.x - added\ -2.6.0 - add `min_id`. deprecated in favor of conversations\ +2.6.0 - add `min_id`. deprecated in favor of [Conversations API]({{}})\ 3.0.0 - removed -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results to return. Defaults to 20. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than ID -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Return results newer than ID -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than ID -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} +#### Request +##### Headers -Statuses with direct visibility, authored by you or mentioning you. Statuses are not grouped by conversation, but are simply returned in chronological order. -{{< endapi-method-response-example-description >}} +Authorization +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +##### Query parameters -```javascript +max_id +: String. Return results older than ID. + +since_id +: String. Return results newer than ID. + +min_id +: String. Return results immediately newer than ID. + +limit +: Integer. Maximum number of results to return. Defaults to 20. Max 40. + +#### Response +##### 200: OK + +Statuses with direct visibility, authored by you or mentioning you. Statuses are not grouped by conversation, but are returned in chronological order. + +```json [ { "id": "103206185588894565", "created_at": "2019-11-26T20:50:15.866Z", - ... + // ... "visibility": "direct", - ... + // ... }, - ... + // ... ] ``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} +##### 401: Unauthorized -```javascript +Invalid or missing Authorization header. + +```json { "error": "The access token is invalid" } ``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} +--- +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/home_controller.rb" caption="app/controllers/api/v1/timelines/home_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/list_controller.rb" caption="app/controllers/api/v1/timelines/list_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/public_controller.rb" caption="app/controllers/api/v1/timelines/public_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/timelines/tag_controller.rb" caption="app/controllers/api/v1/timelines/tag_controller.rb" >}} \ No newline at end of file diff --git a/content/en/methods/timelines/conversations.md b/content/en/methods/timelines/conversations.md deleted file mode 100644 index b2b468c2..00000000 --- a/content/en/methods/timelines/conversations.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -title: conversations -description: >- - Direct conversations with other participants. (Currently, just threads - containing a post with "direct" visibility.) -menu: - docs: - weight: 10 - parent: methods-timelines ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/conversations" title="Show conversation" >}} -{{< api-method-description >}} - -**Returns:** Array of Conversation\ -**OAuth:** User token + `read:statuses`\ -**Version history:**\ -2.6.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="limit" type="string" required=false >}} -Maximum number of results. Defaults to 20. Max 40. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Return results older than this ID. Use HTTP Link header to paginate. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Return results newer than this ID. Use HTTP Link header to paginate. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="min_id" type="string" required=false >}} -Return results immediately newer than this ID. Use HTTP Link header to paginate. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Truncated sample results of an API call with limit=2 -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "id": "418450", - "unread": true, - "accounts": [ - { - "id": "482403", - "username": "amic", - "acct": "amic@nulled.red", - ... - } - ], - "last_status": { - "id": "103196583826321184", - "created_at": "2019-11-25T04:08:24.000Z", - "in_reply_to_id": "103196540587943467", - "in_reply_to_account_id": "14715", - ... - } - }, - { - "id": "418374", - "unread": false, - "accounts": [ - { - "id": "464472", - "username": "freon", - "acct": "freon@letsalllovela.in", - ... - } - ], - "last_status": { - "id": "103195253010396431", - "created_at": "2019-11-24T22:29:56.331Z", - "in_reply_to_id": "103195239650546339", - "in_reply_to_account_id": "14715", - ... - } - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/conversations/:id" title="Remove conversation" >}} -{{< api-method-description >}} - -**Returns:** empty object\ -**OAuth:** User token + `write:conversations`\ -**Version history:**\ -2.6.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the conversation in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -An empty object will be returned. -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authentication header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -The conversation does not exist, or is not owned by you. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/conversations/:id/read" title="Mark as read" >}} -{{< api-method-description >}} - -**Returns:** Conversation\ -**OAuth:** User token + `write:conversations`\ -**Version history:**\ -2.6.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=false >}} -ID of the conversation in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -The value of `unread` has been changed to false. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "418450", - "unread": false, - "accounts": [ - { - "id": "482403", - ... - } - ], - "last_status": { - "id": "103196583826321184", - ... - } -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -The conversation does not exist, or is not owned by you. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/timelines/lists.md b/content/en/methods/timelines/lists.md deleted file mode 100644 index 2ad71985..00000000 --- a/content/en/methods/timelines/lists.md +++ /dev/null @@ -1,587 +0,0 @@ ---- -title: lists -description: >- - View and manage lists. See also: /api/v1/timelines/list/id for loading a list - timeline. -menu: - docs: - weight: 20 - parent: methods-timelines ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/lists" title="Show user's lists" >}} -{{< api-method-description >}} - -Fetch all lists that the user owns. - -**Returns:** Array of List\ -**OAuth:** User token + `read:lists`\ -**Version history:**\ -2.1.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Use id as a parameter for related API calls. -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "id": "12249", - "title": "Friends", - "replies_policy": "followed" - }, - { - "id": "13585", - "title": "test", - "replies_policy": "list" - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/lists/:id" title="Show a single list" >}} -{{< api-method-description >}} - -Fetch the list with the given ID. Used for verifying the title of a list, and which replies to show within that list. - -**Returns:** List\ -**OAuth:** User token + `read:lists`\ -**Version history:**\ -2.1.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the list in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -The list 12249 exists and is owned by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "12249", - "title": "Friends", - "replies_policy": "followed" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -If the ID does not exist or is not owned by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/lists" title="Create a list" >}} -{{< api-method-description >}} - -Create a new list. - -**Returns:** List\ -**OAuth:** User token + `write:lists`\ -**Version history:**\ -2.1.0 - added\ -3.3.0 - added `replies_policy` - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="title" type="string" required=true >}} -The title of the list to be created. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="replies_policy" type="string" required=false >}} -Enumerable oneOf `followed` `list` `none`. Defaults to `list`. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -A list was created successfully with title=test -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "13585", - "title": "test", - "replies_policy": "list" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="put" host="https://mastodon.example" path="/api/v1/lists/:id" title="Update a list" >}} -{{< api-method-description >}} - -Change the title of a list, or which replies to show. - -**Returns:** List\ -**OAuth:** User token + `write:lists`\ -**Version history:**\ -2.1.0 - added\ -3.3.0 - added `replies_policy` - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the list in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="title" type="string" required=false >}} -The title of the list to be updated. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="replies_policy" type="string" required=false >}} -Enumerable oneOf `followed` `list` `none`. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -The title of list 13585 was successfully updated to title=testing -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "id": "13585", - "title": "testing", - "replies_policy": "list" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -If the title is blank -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Validation failed: Title can't be blank" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/lists/:id" title="Delete a list" >}} -{{< api-method-description >}} - -**Returns:** empty object\ -**OAuth:** User token + `write:lists`\ -**Version history:**\ -2.1.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the list in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -An empty object will be returned if the list was successfully deleted -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -ID does not exist or is not owned by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - -## Accounts in a list - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/lists/:id/accounts" title="View accounts in list" >}} -{{< api-method-description >}} - -**Returns:** Array of Account\ -**OAuth:** User token + `read:lists`\ -**Version history:**\ -2.1.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the list in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="max_id" type="string" required=false >}} -Internal parameter. Use HTTP Link header for pagination. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="since_id" type="string" required=false >}} -Internal parameter. Use HTTP Link header for pagination. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="limit" type="number" required=false >}} -Maximum number of results. Defaults to 40. Max 40. Set to 0 in order to get all accounts without pagination. Pagination is done with the HTTP Link header. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -[ - { - "id": "952529", - ... - }, - { - "id": "917388", - ... - }, - { - "id": "869022", - ... - }, - { - "id": "832844", - ... - }, - { - "id": "482403", - ... - } -] -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -The list ID does not exist or is not owned by you -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/lists/:id/accounts" title="Add accounts to list" >}} -{{< api-method-description >}} - -Add accounts to the given list. Note that the user must be following these accounts. - -**Returns:** empty object\ -**OAuth:** User token + `write:lists`\ -**Version history:**\ -2.1.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the list in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="account_ids" type="array" required=true >}} -Array of account IDs to add to the list. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -You are not following a given account ID, or you do not own the list ID, or list/account ID does not exist -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=422 >}} -{{< api-method-response-example-description >}} - -Account is already in list -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Validation failed: Account has already been taken" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/lists/:id/accounts" title="Remove accounts from list" >}} -{{< api-method-description >}} - -Remove accounts from the given list. - -**Returns:** empty object\ -**OAuth:** User token + `write:lists`\ -**Version history:**\ -2.1.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-path-parameters >}} -{{< api-method-parameter name=":id" type="string" required=true >}} -ID of the list in the database -{{< endapi-method-parameter >}} -{{< endapi-method-path-parameters >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="account_ids" type="array" required=true >}} -Array of account IDs to remove from the list. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Account was successfully removed from the list, or it was already not in the list. -{{< endapi-method-response-example-description >}} - - -```javascript -{} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=404 >}} -{{< api-method-response-example-description >}} - -List ID is not owned by you or does not exist -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Record not found" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/timelines/markers.md b/content/en/methods/timelines/markers.md deleted file mode 100644 index 2609a29a..00000000 --- a/content/en/methods/timelines/markers.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: markers -description: Save and restore your position in timelines. -menu: - docs: - weight: 30 - parent: methods-timelines ---- - -{{< api-method method="get" host="https://mastodon.example" path="/api/v1/markers" title="Get saved timeline position" >}} -{{< api-method-description >}} - -**Returns:** Marker\ -**OAuth:** User token + `read:statuses`\ -**Version history:**\ -3.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-query-parameters >}} -{{< api-method-parameter name="timeline" type="array" required=true >}} -Array of markers to fetch. String enum anyOf `home`, `notifications`. If not provided, an empty object will be returned. -{{< endapi-method-parameter >}} -{{< endapi-method-query-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -timeline\[\] = \["home", "notifications"\] -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "notifications": { - "last_read_id": "35098814", - "version": 361, - "updated_at": "2019-11-26T22:37:25.239Z" - }, - "home": { - "last_read_id": "103206604258487607", - "version": 468, - "updated_at": "2019-11-26T22:37:25.235Z" - } -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} -{{< api-method method="post" host="https://mastodon.example" path="/api/v1/markers" title="Save position in timeline" >}} -{{< api-method-description >}} - -**Returns:** Marker\ -**OAuth:** User token + `write:statuses`\ -**Version history:**\ -3.0.0 - added - -{{< endapi-method-description >}} -{{< api-method-spec >}} -{{< api-method-request >}} -{{< api-method-headers >}} -{{< api-method-parameter name="Authorization" type="string" required=true >}} -Bearer <user token> -{{< endapi-method-parameter >}} -{{< endapi-method-headers >}} -{{< api-method-form-data-parameters >}} -{{< api-method-parameter name="home\[last_read_id\]" type="string" required=false >}} -ID of the last status read in the home timeline. -{{< endapi-method-parameter >}} -{{< api-method-parameter name="notifications\[last_read_id\]" type="string" required=false >}} -ID of the last notification read. -{{< endapi-method-parameter >}} -{{< endapi-method-form-data-parameters >}} -{{< endapi-method-request >}} -{{< api-method-response >}} -{{< api-method-response-example httpCode=200 >}} -{{< api-method-response-example-description >}} - -Calling this API with home\[last_read_id\] causes a marker to be created for the home timeline. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "home": { - "last_read_id": "103194548672408537", - "version": 462, - "updated_at": "2019-11-24T19:39:39.337Z" - } -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=401 >}} -{{< api-method-response-example-description >}} - -Invalid or missing Authorization header -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "The access token is invalid" -} -``` -{{< endapi-method-response-example >}} -{{< api-method-response-example httpCode=409 >}} -{{< api-method-response-example-description >}} - -If object is stale while being updated, an error will occur. -{{< endapi-method-response-example-description >}} - - -```javascript -{ - "error": "Conflict during update, please try again" -} -``` -{{< endapi-method-response-example >}} -{{< endapi-method-response >}} -{{< endapi-method-spec >}} -{{< endapi-method >}} - - diff --git a/content/en/methods/timelines/streaming.md b/content/en/methods/timelines/streaming.md deleted file mode 100644 index f0c4389f..00000000 --- a/content/en/methods/timelines/streaming.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: streaming -description: >- - Subscribe to server-sent events for real-time updates via a long-lived HTTP - connection or via WebSocket. -menu: - docs: - weight: 40 - parent: methods-timelines ---- - -Your application can use a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer, i.e. the HTTP connection is kept open and receives new data periodically. - -Alternatively, a WebSocket connection can also be established. - -## Server-sent events \(HTTP\) - -### Endpoints - -#### GET /api/v1/streaming/health - -Returns `OK` when streaming service is fine. Added in 2.5.0 - -#### GET /api/v1/streaming/user - -Returns events that are relevant to the authorized user, i.e. home timeline and notifications - -#### GET /api/v1/streaming/public - -Returns all public statuses - -#### GET /api/v1/streaming/public/local - -Returns all local statuses - -#### GET /api/v1/streaming/hashtag?tag=:hashtag - -Returns all public statuses for a particular hashtag - -#### GET /api/v1/streaming/hashtag/local?tag=:hashtag - -Returns all local statuses for a particular hashtag - -#### GET /api/v1/streaming/list?list=:list_id - -Returns statuses for a list - -#### GET /api/v1/streaming/direct - -Returns all direct messages - -### Stream contents - -The stream will contain events as well as heartbeat comments. Lines that begin with a colon \(`:`\) can be ignored by parsers, they are simply there to keep the connection open. Events have this structure: - -```text -event: name -data: payload -``` - -## WebSocket - -For WebSockets, there is only one URL path \(`/api/v1/streaming`\). The access token as well as the endpoint you are interested in must be provided with query params, respectively `access_token` and `stream`. Query params `list` and `tag` are likewise supported for relevant endpoints. - -Possible `stream` values: - -* `user` -* `public` -* `public:local` -* `hashtag` -* `hashtag:local` -* `list` -* `direct` - -## Event types - -| Event | Description | What’s in the payload | -| :--- | :--- | :--- | -| `update` | A new status has appeared | [Status]({{< relref "../../entities/status.md" >}}) | -| `notification` | A new notification has appeared | [Notification]({{< relref "../../entities/notification.md" >}}) | -| `delete` | A status has been deleted | ID of the deleted status | -| `filters_changed` | Keyword filters have been changed | | - -The payload is JSON-encoded. - -{{< hint style="info" >}} - -In case of `filters_changed` event, `payload` is not defined. -{{< /hint >}} - - diff --git a/content/en/methods/trends.md b/content/en/methods/trends.md new file mode 100644 index 00000000..1eef610f --- /dev/null +++ b/content/en/methods/trends.md @@ -0,0 +1,218 @@ +--- +title: trends API methods +description: View hashtags that are currently being used more frequently than usual. +menu: + docs: + weight: 10 + name: trends + parent: methods-instance + identifier: methods-trends +aliases: [ + "/methods/trends", + "/api/methods/trends", + "/methods/instance/trends", +] +--- + + + +## View trending tags {#tags} + +```http +GET https://mastodon.example/api/v1/trends/tags HTTP/1.1 +``` + +Tags that are being used more frequently within the past week. + +**Returns:** Array of [REST::Tag]({{< relref "entities/tag" >}})\ +**OAuth:** Public\ +**Version history:**\ +3.0.0 - added\ +3.5.0 - method signature changed from `GET /api/v1/trends` to `GET /api/v1/trends/tags`. The former is a deprecated alias that may be removed in the future. + +#### Request + +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 10. + +#### Response +##### 200: OK + +```json +[ + { + "name": "hola", + "url": "https://mastodon.social/tags/hola", + "history": [ + { + "day": "1574726400", + "uses": "13", + "accounts": "10" + }, + // ... + ] + }, + { + "name": "SaveDotOrg", + "url": "https://mastodon.social/tags/SaveDotOrg", + "history": [ + { + "day": "1574726400", + "uses": "9", + "accounts": "9" + }, + // ... + ] + }, + { + "name": "introduction", + "url": "https://mastodon.social/tags/introduction", + "history": [ + { + "day": "1574726400", + "uses": "15", + "accounts": "14" + }, + // ... + ] + }, + // ... +] +``` + +--- + +## View trending statuses {#statuses} + +```http +GET https://mastodon.example/api/v1/trends/statuses HTTP/1.1 +``` + +Statuses that have been interacted with more than others. + +**Returns:** Array of [Status]({{< relref "entities/status" >}})\ +**OAuth:** Public\ +**Version history:**\ +3.5.0 - added + +#### Request +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 10. + +#### Response +##### 200: OK + +```json +[ + { + "id": "108910940413327534", + "created_at": "2022-08-30T08:44:26.366Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + // ... + "content": "

In order to prevent such incidents from happening in the future, we are implementing a fixed set of internal guidelines which must be met before any media content can be shared on our social media platforms. The distribution of material which promotes a message of racism or sexism is unacceptable. We can do better and in the future we will do better.

We apologize again for this incident and can assure you that it will not happen again.

Your Tutanota Team

", + // ... + }, + // ... +] +``` + +--- + +## View trending links {#links} + +```http +GET https://mastodon.example/api/v1/trends/links HTTP/1.1 +``` + +Links that have been shared more than others. + +**Returns:** Array of [Trends::Link]({{< relref "entities/PreviewCard#trends-link" >}})\ +**OAuth:** Public\ +**Version history:**\ +3.5.0 - added + +#### Request +##### Query parameters + +limit +: Integer. Maximum number of results to return. Defaults to 10. + +#### Response +##### 200: OK + +```json +[ + { + "url": "https://www.nbcnews.com/specials/plan-your-vote-2022-elections/index.html", + "title": "Plan Your Vote: 2022 Elections", + "description": "Everything you need to know about the voting rules where you live, including registration, mail-in voting, changes since 2020, and more.", + "type": "link", + "author_name": "NBC News", + "author_url": "", + "provider_name": "NBC News", + "provider_url": "", + "html": "", + "width": 400, + "height": 225, + "image": "https://files.mastodon.social/cache/preview_cards/images/045/027/478/original/0783d5e91a14fd49.jpeg", + "embed_url": "", + "blurhash": "UcQmF#ay~qofj[WBj[j[~qof9Fayofofayay", + "history": [ + { + "day": "1661817600", + "accounts": "7", + "uses": "7" + }, + { + "day": "1661731200", + "accounts": "23", + "uses": "23" + }, + { + "day": "1661644800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661558400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661472000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661385600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661299200", + "accounts": "0", + "uses": "0" + } + ] + }, + // ... +] +``` + +--- + +## See also + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/trends/links_controller.rb" caption="app/controllers/api/v1/trends/links_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/trends/statuses_controller.rb" caption="app/controllers/api/v1/trends/statuses_controller.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/trends/tags_controller.rb" caption="app/controllers/api/v1/trends/tags_controller.rb" >}} \ No newline at end of file diff --git a/content/en/spec/activitypub.md b/content/en/spec/activitypub.md index 2b0770d7..df0658e1 100644 --- a/content/en/spec/activitypub.md +++ b/content/en/spec/activitypub.md @@ -13,17 +13,30 @@ Sample payloads will be added at a future date. ## Status federation {#status} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/activity.rb" caption="app/lib/activitypub/activity.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/activitypub/activity.rb" caption="app/lib/activitypub/activity.rb" >}} ### Supported activities for statuses -* Create = transformed into a status and saved into database -* Delete = removes a status from the database -* Like = transformed into a favourite on a status -* Announce = transformed into a boost on a status -* Flag = transformed into a report to the moderation team. -* Update = only supported on polls. Used to refresh vote count. -* Undo = undo a previous Like or Announce. +Create +: Transformed into a status and saved into database + +Delete +: Removes a status from the database + +Like +: Transformed into a favourite on a status + +Announce +: Transformed into a boost on a status + +Flag +: Transformed into a report to the moderation team. + +Update +: Refresh vote count on polls. As of Mastodon 3.5.0: edit statuses. + +Undo +: Undo a previous Like or Announce. ### Payloads @@ -32,7 +45,7 @@ The first-class Object types supported by Mastodon are `Note` and `Question`. * Notes are transformed into regular statuses. * Questions are transformed into a poll status. -Some other Object types are converted as best as possible. The transformer uses `content` if available, or `name` if not, in order to generate status text. The `url` will be appended. The `summary` property will be used as the CW text. The `icon` will be used as a thumbnail. +Some other Object types are converted as best as possible: * Article * Page @@ -41,41 +54,171 @@ Some other Object types are converted as best as possible. The transformer uses * Video * Event +The transformer uses `content` if available, or `name` if not, in order to generate status text. The `url` will be appended. The `summary` property will be used as the CW text. The `icon` will be used as a thumbnail. + +### Properties used + +content +: Used as status text + +name +: Used as status text, if `content` is not provided on a transformed Object type + +summary +: Used as CW text + +sensitive +: Used to determine whether status media or text should be hidden by default + +inReplyTo +: Used for threading a status as a reply to another status + +published +: Used as status date + +url +: Used for status permalinks, and also appended to status text for transformed Objects + +attributedTo +: Used to determine the profile which authored the status + +to/cc +: Used to determine audience and visibility of a status. + - Public statuses have the `as:Public` magic collection in `to` + - Unlisted statuses have the `as:Public` magic collection in `cc` + - Followers-only statuses have an actor's follower collection in `to` or `cc`, but do not include the `as:Public` magic collection + - Private statuses have actors in `to` or `cc`, at least one of which is not `Mention`ed in `tag` + - Direct statuses have actors in `to` or `cc`, all of which are `Mention`ed in `tag` + +tag +: Used to mark up mentions and hashtags. + +tag[].type +: Either `Mention` or `Hashtag` is currently supported + +tag[].name +: The plain-text Webfinger address of a profile Mention (`@user` or `@user@domain`), or the plain-text Hashtag (`#tag`) + +tag[].href +: The URL of the actor or tag + +attachment +: Used to include attached images, videos, or audio. + +attachment[].url +: Used to fetch the media attachment + +attachment[].summary +: Used as media description + +attachment[].blurhash +: Used to generate a blurred preview image corresponding to the colors used within the image. See [Blurhash](#blurhash) for more details. + +replies +: A Collection of statuses that are in reply to the current status. Up to 5 replies from the same server will be fetched upon discovery of a remote status, in order to resolve threads more fully. On Mastodon's side, the first page contains self-replies, and additional pages contain replies from other people. + +#### Poll-specific properties + +endTime +: The timestamp for when voting will close on the poll + +closed +: The timestamp for when voting closed on the poll. The timestamp will likely match the `endTime` timestamp. If this property is present, the poll is assumed to be closed. + +votersCount +: How many people have voted in the poll. Distinct from how many votes have been cast (in the case of multiple-choice polls) + +oneOf +: Single-choice poll options + +anyOf +: Multiple-choice poll options + +oneOf/anyOf[].name +: The poll option's text + +oneOf/anyOf[].replies.totalItems +: The poll option's vote count + ## Profile federation {#profile} ### Supported activities for profiles -* Follow = Indicate interest in receiving status updates from a profile. -* Accept/Reject = used to approve or deny Follow activities. Unlocked accounts will automatically reply with an Accept, while locked accounts can manually choose whether to approve or deny a follow request. -* Add/Remove = manage pinned posts and featured collections. -* Block = Signal to a remote server that they should hide your profile from that user. Not guaranteed. -* Flag = report user -* Update = refresh account details -* Move = migrate followers from one account to another. Requires alsoKnownAs to be set in both directions. -* Delete = remove an account from the database, as well as all of their statuses. -* Undo = undo a previous Follow, Accept Follow, or Block. +Follow +: Indicate interest in receiving status updates from a profile. + +Accept/Reject +: Used to approve or deny Follow activities. Unlocked accounts will automatically reply with an Accept, while locked accounts can manually choose whether to approve or deny a follow request. + +Add/Remove +: Manage pinned posts and featured collections. + +Block +: Signal to a remote server that they should hide your profile from that user. Not guaranteed. + +Flag +: Report user + +Update +: Refresh account details + +Move +: Migrate followers from one account to another. Requires alsoKnownAs to be set in both directions. + +Delete +: Remove an account from the database, as well as all of their statuses. + +Undo +: Undo a previous Follow, Accept Follow, or Block. ### Properties used -| Property | Interpretation | -| :--- | :--- | -| preferredUsername | Used for Webfinger lookup. Must be unique on the domain, and must correspond to a Webfinger `acct:` URI. | -| name | Used as profile display name. | -| summary | Used as profile bio. | -| type | Assumed to be Person. If type is Application or Service, it will be interpreted as a bot flag. | -| url | Used as profile link. | -| icon | Used as profile avatar. | -| image | Used as profile header. | -| manuallyApprovesFollowers | Will be shown as a locked account. | -| discoverable | Will be shown in the profile directory. See [Discoverability flag]({{< relref "activitypub.md#discoverable" >}}). | -| publicKey | Required for signatures. See [Public key]({{< relref "activitypub.md#public-key" >}}). | -| featured | Pinned posts. See [Featured collection]({{< relref "activitypub.md#featured" >}}). | -| attachment | Used for profile fields. See [Profile metadata]({{< relref "activitypub.md#profile-metadata" >}}) and [Identity proofs]({{< relref "activitypub.md#identityproof" >}}). | -| alsoKnownAs | Required for Move activity. | +preferredUsername +: Used for Webfinger lookup. Must be unique on the domain, and must correspond to a Webfinger `acct:` URI. + +name +: Used as profile display name. + +summary +: Used as profile bio. + +type +: Assumed to be Person. If type is Application or Service, it will be interpreted as a bot flag. + +url +: Used as profile link. + +icon +: Used as profile avatar. + +image +: Used as profile header. + +manuallyApprovesFollowers +: Will be shown as a locked account. + +discoverable +: Will be shown in the profile directory. See [Discoverability flag](#discoverable). + +publicKey +: Required for signatures. See [Public key](#publicKey). + +featured +: Pinned posts. See [Featured collection](#featured). + +attachment +: Used for profile fields. See [Profile metadata](#PropertyValue) and [Identity proofs](#IdentityProof). + +alsoKnownAs +: Required for Move activity. + +published +: When the profile was created. + ## HTML sanitization {#sanitization} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/sanitize_config.rb" caption="app/lib/sanitize\_config.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/sanitize_config.rb" caption="app/lib/sanitize\_config.rb" >}} Mastodon sanitizes incoming HTML in order to not break assumptions for API client developers. Supported elements include `

`, ``, `
`, and ``. Unsupported elements will be converted to `

`.The sanitizer will keep classes if they begin with microformats prefixes or are semantic classes: @@ -91,9 +234,9 @@ Some other Object types are converted as best as possible. The transformer uses ## JSON-LD Namespacing {#namespaces} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/adapter.rb" caption="app/lib/activitypub/adapter.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/activitypub/adapter.rb" caption="app/lib/activitypub/adapter.rb" >}} -### Mastodon extensions \(`toot:`\) {#toot} +### Mastodon extensions (`toot:`) {#toot} Contains definitions for Mastodon features. @@ -107,7 +250,7 @@ Contains definitions for Mastodon features. * toot:suspended * toot:votersCount -### ActivityStreams extensions \(`as:`\) {#as} +### ActivityStreams extensions (`as:`) {#as} Contains ActivityStreams extended properties that have been proposed but not officially adopted yet. @@ -117,9 +260,9 @@ Contains ActivityStreams extended properties that have been proposed but not off * as:movedTo * as:sensitive -### W3ID Security Vocabulary \(`sec:`\) {#sec} +### W3ID Security Vocabulary (`sec:`) {#sec} -Contains properties used for HTTPS Signatures and Linked Data Signatures. Also used for identity proofs. See [Security]({{< relref "security.md" >}}) for more information. +Contains properties used for HTTPS Signatures and Linked Data Signatures. Also used for identity proofs. See [Security]({{< relref "spec/security" >}}) for more information. * sec:publicKey * sec:publicKeyPem @@ -136,7 +279,7 @@ Contains a collection of terms from various namespaces, used for Linked Data Sig * sec:signature * sec:signatureValue -### schema.org extensions \(`schema:`\) {#schema} +### schema.org extensions (`schema:`) {#schema} Contains properties used for profile metadata. @@ -147,9 +290,9 @@ Contains properties used for profile metadata. ### Public key {#publicKey} -Public keys are used for HTTPS Signatures and Linked Data Signatures. This is implemented using an extra property `publicKey` on actor objects. See [Security]({{< relref "security.md" >}}) for more information. Example: +Public keys are used for HTTPS Signatures and Linked Data Signatures. This is implemented using an extra property `publicKey` on actor objects. See [Security]({{< relref "spec/security" >}}) for more information. Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -167,9 +310,9 @@ Public keys are used for HTTPS Signatures and Linked Data Signatures. This is im ### Featured collection {#featured} -What is known in Mastodon as “pinned toots”, or statuses that are always featured at the top of people’s profiles, is implemented using an extra property `featured` on the actor object that points to a `Collection` of objects. Example: +What is known in Mastodon as “pinned statuses”, or statuses that are always featured at the top of people’s profiles, is implemented using an extra property `featured` on the actor object that points to a `Collection` of objects. Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -192,7 +335,7 @@ What is known in Mastodon as “pinned toots”, or statuses that are always fea Mastodon allows users to feature specific hashtags on their profile for easy browsing, as a discoverability mechanism. This is implemented using an extra property `featuredTags` on the actor object that points to a `Collection` of `Hashtag` objects specifically. -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -215,7 +358,7 @@ Mastodon allows users to feature specific hashtags on their profile for easy bro Mastodon supports arbitrary emojis, that is, small images uploaded by admins and invokable via shortcodes. For this, an `Emoji` type is used. These emojis are listed in the `tag` property just like `Mention` and `Hashtag` objects, since they are entities that affect how the text is rendered. Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -245,9 +388,9 @@ Mastodon supports arbitrary emojis, that is, small images uploaded by admins and ### Focal points {#focalPoint} -Mastodon supports setting a focal point on uploaded images, so that wherever that image is displayed, the focal point stays in view. This is implemented using an extra property `focalPoint` on `Image` objects. The property is simply an array of two floating points between -1.0 and 1.0, with 0,0 being the center of the image, the first value being x \(-1.0 is the left edge, +1.0 is the right edge\) and the second value being y \(-1.0 is the bottom edge, +1.0 is the top edge\). See [Focal points]({{< relref "../methods/statuses/media.md#focal-points" >}}) for more information. Example: +Mastodon supports setting a focal point on uploaded images, so that wherever that image is displayed, the focal point stays in view. This is implemented using an extra property `focalPoint` on `Image` objects. The property is an array of two floating points between -1.0 and 1.0, with 0,0 being the center of the image, the first value being x (-1.0 is the left edge, +1.0 is the right edge) and the second value being y (-1.0 is the bottom edge, +1.0 is the top edge). See [API Guidelines > Focal points]({{< relref "api/guidelines#focal-points" >}}) for more information. Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -277,11 +420,15 @@ Mastodon supports setting a focal point on uploaded images, so that wherever tha } ``` +{{< figure src="/assets/focal-points.jpg" caption="A demonstration of various focal points and their coordinates." >}} + +The focal point of (-0.55, 0.43) in the example above corresponds to a point 55% to the left of center and 43% above center. This focal point should remain visible within the cropped thumbnail, if any cropping is done. + ### Blurhash {#blurhash} Mastodon generates colorful preview thumbnails for attachments. This is implemented using an extra property `blurhash` on `Image` objects. The property is a string generated by the [BlurHash algorithm](https://blurha.sh). Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -309,7 +456,7 @@ Mastodon generates colorful preview thumbnails for attachments. This is implemen Mastodon supports arbitrary profile fields containing name-value pairs. This is implemented using the `attachment` property on actor objects, with objects in the array having a type of `PropertyValue` and a `value` property, both from the schema.org namespace. Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -337,9 +484,13 @@ Mastodon supports arbitrary profile fields containing name-value pairs. This is ### Identity proofs {#IdentityProof} +{{< hint style="warning" >}} +This property is currently unused/deprecated due to the removal of Keybase support in Mastodon 3.5: +{{}} + Mastodon supports integration with identity providers to prove that a profile is linked to a certain identity. This is implemented using the `attachment` property on actor objects, with objects in the array having a type of `IdentityProof` from the Mastodon namespace. The object also includes `signatureAlgorithm` and `signatureValue` from the W3ID Security Vocabulary namespace. Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -366,7 +517,7 @@ Mastodon supports integration with identity providers to prove that a profile is Mastodon allows users to opt-in or opt-out of discoverability features like the profile directory. This flag may also be used as an indicator of the user's preferences toward being included in external discovery services, such as search engines or other indexing tools. If you are implementing such a tool, it is recommended that you respect this property if it is present. This is implemented using an extra property `discoverable` on objects. Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -385,7 +536,7 @@ Mastodon allows users to opt-in or opt-out of discoverability features like the Mastodon reports whether a user was locally suspended, for better handling of these accounts. Suspended accounts in Mastodon return empty data. If a remote account is marked as suspended, it cannot be unsuspended locally. Suspended accounts can be targeted by activities such as Update, Undo, Reject, and Delete. This functionality is implemented using an extra property `suspended` on objects. Example: -```javascript +```json { "@context": [ "https://www.w3.org/ns/activitystreams", @@ -404,7 +555,7 @@ Mastodon reports whether a user was locally suspended, for better handling of th ### Secure mode {#secure-mode} -When a Mastodon server runs in secure mode, all cross-server HTTP requests to it must be signed (in other words, even `GET` requests to public resources). That way, the Mastodon server can choose to reject requests from servers it has blocked and avoid "leaking" public information. Mastodon itself uses a dedicated system actor to sign such HTTP requests. See [Security](../security) for more details on HTTP signatures. +When a Mastodon server runs in secure mode, all cross-server HTTP requests to it must be signed (in other words, even `GET` requests to public resources). That way, the Mastodon server can choose to reject requests from servers it has blocked and avoid "leaking" public information. Mastodon itself uses a dedicated system actor to sign such HTTP requests. See [Security]({{< relref "spec/security" >}}) for more details on HTTP signatures. Secure mode is the foundation upon which "limited federation mode" is built. A Mastodon server in limited federation mode will only federate with servers its admin has explicitly allowed, and reject all other requests. @@ -421,7 +572,7 @@ When delivering a message to a remote user, an optional `Collection-Synchronizat Example: ```http -POST https://mastodon.social/users/foo/inbox +POST https://mastodon.social/users/foo/inbox HTTP/1.1 Collection-Synchronization: collectionId="https://social.sitedethib.com/users/Thib/followers", url="https://social.sitedethib.com/users/Thib/followers_synchronization", @@ -431,7 +582,7 @@ Collection-Synchronization: When a remote user attempts to GET the partial collection `url`, this request must be signed with HTTP signatures. Example: ```http -GET https://social.sitedethib.com/users/Thib/followers_synchronization +GET https://social.sitedethib.com/users/Thib/followers_synchronization HTTP/1.1 Signature: ... # a signature from an account on mastodon.social { @@ -442,5 +593,4 @@ Signature: ... # a signature from an account on mastodon.social "https://mastodon.social/users/Gargron" ] } -``` - +``` \ No newline at end of file diff --git a/content/en/spec/bearcaps.md b/content/en/spec/bearcaps.md index 29c958c0..9e8cddc4 100644 --- a/content/en/spec/bearcaps.md +++ b/content/en/spec/bearcaps.md @@ -22,8 +22,8 @@ Bearcaps allow for a way to link to a resource with the token included, like so: bear:?t=&u=https://example.com/foo' ``` -To translate a bearcap to an HTTP request, simply make a request to the `u` parameter and attach the `t` parameter as a `Bearer` token in the `Authorization` header. +To translate a bearcap to an HTTP request, make a request to the `u` parameter and attach the `t` parameter as a `Bearer` token in the `Authorization` header. ## How are bearcaps used in Mastodon? {#usage} -As of v3.3.0, Mastodon supports dereferencing bearcaps in a received Activity. Bearcap are not used for sending any Activity yet. +As of v3.3.0, Mastodon supports dereferencing bearcaps in a received Activity. Bearcaps are not used for sending any Activity yet. diff --git a/content/en/spec/microformats.md b/content/en/spec/microformats.md index 1705b7ec..862f3503 100644 --- a/content/en/spec/microformats.md +++ b/content/en/spec/microformats.md @@ -9,17 +9,17 @@ menu: ## What are microformats? {#intro} -[Microformats 2.0](https://microformats.io/) is a standard used to embed metadata directly within an HTML document. Rather than needing to use an API for read-only purposes, a web page can simply be parsed for certain CSS classes in order to extract information that you have already fetched simply by viewing the page, rather than having to separately request that same information from an API. The use of microformats classes allows for semantic parsing of data within a given web page, and can be used to generate feeds, cards, or representations of that data. +[Microformats 2.0](https://microformats.io/) is a standard used to embed metadata directly within an HTML document. Rather than needing to use an API for read-only purposes, a web page can be parsed for certain CSS classes in order to extract information that you have already fetched just by viewing the page, rather than having to separately request that same information from an API. The use of microformats classes allows for semantic parsing of data within a given web page, and can be used to generate feeds, cards, or representations of that data. ## Microformats classes {#classes} All microformats classes use a prefix. The prefix indicates the type of the element, independent of hierarchy. These are the microformats classes as used in Mastodon's codebase. -### Root elements \(`h-*`\) {#h} +### Root elements (`h-*`) {#h} #### `h-feed` {#h-feed} -Represents a stream of entries. Attached to a profile's toots. Also attached to the parent thread within detailed status views. +Represents a stream of entries. Attached to a profile's statuses. Also attached to the parent thread within detailed status views. #### `h-entry` {#h-entry} @@ -33,7 +33,7 @@ Represents a reference to another online publication. Attached to a boost. Also Represents a person or organization. Attached to the container of display name, username, and avatar. Also attached to mentions. -### Plain-text properties \(`p-*`\) {#p} +### Plain-text properties (`p-*`) {#p} #### `p-author` {#p-author} @@ -57,7 +57,7 @@ Within h-entry of a detailed status, represents a post that is a reblog and also Within `h-entry` of a detailed status, represents statuses that are direct children. -### URL properties \(`u-*`\) {#u} +### URL properties (`u-*`) {#u} #### `u-photo` {#u-photo} @@ -72,13 +72,13 @@ Within `h-entry` or `h-cite`, represents a universally unique identifier. Attach Within `h-entry` or `h-cite`, represents the status permalink. Attached to timestamp link. Within `h-card`, represents the profile permalink. Attached to display name link. -### Datetime properties \(`dt-*`\) {#dt} +### Datetime properties (`dt-*`) {#dt} #### `dt-published` {#dt-published} Within `h-entry` or `h-cite`, represents the date and time at which the status was published. Attached to `data` element with `value` attribute. -### Element tree \(`e-*`\) {#e} +### Element tree (`e-*`) {#e} #### `e-content` {#e-content} diff --git a/content/en/spec/oauth.md b/content/en/spec/oauth.md index 26d85c94..14261b4e 100644 --- a/content/en/spec/oauth.md +++ b/content/en/spec/oauth.md @@ -17,25 +17,25 @@ Mastodon supports the following OAuth 2 flows: * **Password grant flow**: For bots and other single-user applications * **Client credentials flow**: For applications that do not act on behalf of users -To obtain an OAuth token for a Mastodon website, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to [acquire a client id/secret]({{< relref "../methods/apps/#create-an-application" >}}) and then [proceed with normal OAuth 2]({{< relref "../methods/apps/oauth.md" >}}). +To obtain an OAuth token for a Mastodon website, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to [acquire a client id/secret]({{< relref "methods/apps#create" >}}) and then [proceed with normal OAuth 2]({{< relref "methods/oauth" >}}). ## OAuth 2 endpoints implemented {#implementation} -The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2. For more information on how to use these endpoints, see the [API documentation for OAuth.]({{< relref "../methods/apps/oauth.md" >}}) +The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2. For more information on how to use these endpoints, see the [API documentation for OAuth.]({{< relref "methods/oauth" >}}) -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/config/initializers/doorkeeper.rb" caption="Doorkeeper config initializer" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/config/initializers/doorkeeper.rb" caption="Doorkeeper config initializer" >}} -### [GET /oauth/authorize]({{< relref "../methods/apps/oauth.md#authorize-a-user" >}}) +### [GET /oauth/authorize]({{< relref "methods/oauth#authorize" >}}) Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested. -### [POST /oauth/token]({{< relref "../methods/apps/oauth.md#obtain-a-token" >}}) {#post-oauth-token} +### [POST /oauth/token]({{< relref "methods/oauth#token" >}}) {#post-oauth-token} Obtain an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC. -### [POST /oauth/revoke]({{< relref "../methods/apps/oauth.md#revoke-token" >}}) {#post-oauth-revoke} +### [POST /oauth/revoke]({{< relref "methods/oauth#revoke" >}}) {#post-oauth-revoke} -Post here with client credentials to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC \(RFC 7009\). +Post here with client credentials to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC (RFC 7009). ## Common gotchas {#gotchas} diff --git a/content/en/spec/security.md b/content/en/spec/security.md index 066a666e..56387732 100644 --- a/content/en/spec/security.md +++ b/content/en/spec/security.md @@ -9,7 +9,7 @@ menu: ## HTTP Signatures {#http} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/request.rb" caption="app/lib/request.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/request.rb" caption="app/lib/request.rb" >}} [HTTP Signatures](https://w3c-dvcg.github.io/http-signatures/) is a specification for signing HTTP messages by using a \`Signature:\` header with your HTTP request. Mastodon requires the use of HTTP Signatures in order to validate that any activity received was authored by the actor generating it. When secure mode is enabled, all GET requests require HTTP signatures as well. @@ -28,9 +28,9 @@ Signature: signature="Y2FiYW...IxNGRiZDk4ZA==" ``` -The `keyId` should correspond to the actor and the key being used to generate the `signature`, whose value is equal to all parameters in `headers` concatenated together and signed by the key, then Base64-encoded. See [ActivityPub > Public key]({{< relref "activitypub.md#public-key" >}}) for more information on actor keys. An example key looks like this: +The `keyId` should correspond to the actor and the key being used to generate the `signature`, whose value is equal to all parameters in `headers` concatenated together and signed by the key, then Base64-encoded. See [ActivityPub > Public key]({{< relref "activitypub#publicKey" >}}) for more information on actor keys. An example key looks like this: -```javascript +```json "publicKey": { "id": "https://my-example.com/actor#main-key", "owner": "https://my-example.com/actor", @@ -75,7 +75,7 @@ This request is functionally equivalent to saying that `https://my-example.com/a ### Verifying HTTP signatures {#http-verify} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/controllers/concerns/signature_verification.rb" caption="app/controllers/concerns/signature\_verification.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/controllers/concerns/signature_verification.rb" caption="app/controllers/concerns/signature\_verification.rb" >}} Consider the following request: @@ -97,18 +97,18 @@ Mastodon verifies the signature using the following algorithm: ## Linked Data Signatures {#ld} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/linked_data_signature.rb" caption="app/lib/activitypub/linked\_data\_signature.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/activitypub/linked_data_signature.rb" caption="app/lib/activitypub/linked\_data\_signature.rb" >}} [Linked Data Signatures 1.0](https://w3c-dvcg.github.io/ld-signatures/) is a specification for attaching cryptographic signatures to JSON-LD documents. LD Signatures are not used widely within Mastodon, but they are used in the following situations: -* When running a [self-destruct]({{< relref "../admin/tootctl.md#tootctl-self-destruct" >}}) sequence to send Delete activities to all known peers, the payload will use LD Signatures because HTTP Signatures will not be available. Receiving servers will process the signature by validating it against the locally cached actor key, since the HTTP server will no longer be hosting old actor information. +* When running a [self-destruct]({{< relref "admin/tootctl#tootctl-self-destruct" >}}) sequence to send Delete activities to all known peers, the payload will use LD Signatures because HTTP Signatures will not be available. Receiving servers will process the signature by validating it against the locally cached actor key, since the HTTP server will no longer be hosting old actor information. * When accepting activities from a relay. Public activities can optionally be sent to a relay with LD Signatures, and any server subscribing to a relay does not have to manually refetch the activity from the origin. This prevents having potentially infinite servers attempt to load the status from your instance. ### Creating LD signatures {#ld-sign} To create a signature, Mastodon uses the keypair attached to an actor at `https://mastodon.example/users/username#main-key`. It then creates an SHA256 hash of the document, signs it with the keypair, and Base64-strict-encodes the resulting output to derive a `signatureValue`. The following hash is merged into the JSON-LD document: -```javascript +```json "signature": { "type": "RsaSignature2017", "creator": "https://mastodon.example/users/username#main-key", diff --git a/content/en/spec/webfinger.md b/content/en/spec/webfinger.md index 9a07f8eb..34075fc7 100644 --- a/content/en/spec/webfinger.md +++ b/content/en/spec/webfinger.md @@ -21,10 +21,10 @@ Enter WebFinger. WebFinger as described in [RFC 7033](https://tools.ietf.org/htm Suppose we want to lookup the user `@Gargron` hosted on the `mastodon.social` website. -Simply make a request to that domain's `/.well-known/webfinger` endpoint, with the `resource` query parameter set to an `acct:` URI. +Just make a request to that domain's `/.well-known/webfinger` endpoint, with the `resource` query parameter set to an `acct:` URI. {{< code title="https://mastodon.social/.well-known/webfinger?resource=acct:gargron@mastodon.social" >}} -```javascript +```json { "subject": "acct:Gargron@mastodon.social", "aliases": [ @@ -56,7 +56,7 @@ You can parse this JSON response to find a link with your desired type. For Acti This way, we have translated `@Gargron@mastodon.social` to `https://mastodon.social/users/Gargron` and we can now interact over ActivityPub by referring to this URI as `id` where appropriate. {{< code title="Sample activity" >}} -```javascript +```json { "id": "https://social.example/activities/1", "type": "Create", @@ -71,5 +71,5 @@ This way, we have translated `@Gargron@mastodon.social` to `https://mastodon.soc ``` {{< /code >}} -Note in the above example that `social.example` does not use the same URI structure as Mastodon. Thus, we cannot simply guess the actor `id` given only the username and domain. However, if `social.example` supports WebFinger, then we can get this `id`simply by requesting `https://social.example/.well-known/webfinger?resource=acct:username@social.example`and parsing the response for a link with the `application/activity+json` type. +Note in the above example that `social.example` does not use the same URI structure as Mastodon. Thus, we cannot guess the actor `id` given only the username and domain. However, if `social.example` supports WebFinger, then we can get this `id` by requesting `https://social.example/.well-known/webfinger?resource=acct:username@social.example`and parsing the response for a link with the `application/activity+json` type. diff --git a/content/en/user/discoverability.md b/content/en/user/discoverability.md index 09f80646..9481c2d7 100644 --- a/content/en/user/discoverability.md +++ b/content/en/user/discoverability.md @@ -23,9 +23,9 @@ You can choose to feature profiles of people that you are following. Go to that ## Pinned posts {#pinned} -{{< figure src="/assets/pinned.jpg" caption="A pinned toot by mastodon.social/@gargron" >}} +{{< figure src="/assets/pinned.jpg" caption="A pinned post by mastodon.social/@gargron" >}} -You can choose to feature up to 5 of your own public posts at the top of your profile. Go to the status dropdown menu and click "Pin on profile". When you pin a toot, it will appear at the top of your "toots" tab, before all other chronological status updates. +You can choose to feature up to 5 of your own public posts at the top of your profile. Go to the status dropdown menu and click "Pin on profile". When you pin a post, it will appear at the top of your "posts" tab, before all other chronological status updates. ## Profile directory {#directory} @@ -33,7 +33,7 @@ You can choose to feature up to 5 of your own public posts at the top of your pr The profile directory shows all accounts that have opted into being shown in the directory, and can be used to quickly find profiles that you may be interested in following. -The profile directory can be sorted either by recent activity \(the most recently published status\), or by new arrivals \(the most recently created accounts\). The directory can also be filtered to show only local accounts, or to show all known accounts that your website is aware of. +The profile directory can be sorted either by recent activity (the most recently published status), or by new arrivals (the most recently created accounts). The directory can also be filtered to show only local accounts, or to show all known accounts that your website is aware of. -Profiles appear as cards that include a user's display name, address, account bio, and some brief stats such as how many toots they've published, how many followers they have, and the time of their last published status. +Profiles appear as cards that include a user's display name, address, account bio, and some brief stats such as how many posts they've published, how many followers they have, and the time of their last published status. diff --git a/content/en/user/moderating.md b/content/en/user/moderating.md index 7048a7fa..c2f2bd25 100644 --- a/content/en/user/moderating.md +++ b/content/en/user/moderating.md @@ -25,7 +25,7 @@ This is the string that will be matched. The keyword will be searched for in any ### Expire after {#filter-expire} -Optionally only apply the filter for a limited amount of time. Expired filters are not automatically deleted, but can be reactivated by setting a new expiry date \(or changing it back to "never" expire\). +Optionally only apply the filter for a limited amount of time. Expired filters are not automatically deleted, but can be reactivated by setting a new expiry date (or changing it back to "never" expire). ### Filter contexts {#filter-context} @@ -105,4 +105,4 @@ If you block an entire server: {{< figure src="/assets/report-modal.jpg" caption="The report modal allows selecting example statuses, adding a note, and forwarding reports." >}} -If you see a status or user that is violating the rules of your website, you can report that user to your site's moderators. Clicking the "report" option on the user dropdown or status dropdown will open the report modal. Here, you can \(and should\) add a note about why you are reporting this account. You can attach certain problematic statuses for additional context on why you are reporting the account, and if their conduct is violating the rules of the remote website, you can also choose to forward the report to their site's moderators. +If you see a status or user that is violating the rules of your website, you can report that user to your site's moderators. Clicking the "report" option on the user dropdown or status dropdown will open the report modal. Here, you can (and should) add a note about why you are reporting this account. You can attach certain problematic statuses for additional context on why you are reporting the account, and if their conduct is violating the rules of the remote website, you can also choose to forward the report to their site's moderators. diff --git a/content/en/user/moving.md b/content/en/user/moving.md index 760fddf0..24ed3a27 100644 --- a/content/en/user/moving.md +++ b/content/en/user/moving.md @@ -13,7 +13,7 @@ menu: At any time you want, you can go to Settings > Export and download a CSV file for your current followed accounts, your currently created lists, your currently blocked accounts, your currently muted accounts, and your currently blocked domains. Your following, blocking, muting, and domain-blocking lists can be imported at Settings > Import, where they can either be merged or overwritten. -Requesting an archive of your toots and media can be done once every 7 days, and can be downloaded in ActivityPub JSON format. Mastodon currently does not support importing toots or media due to technical limitations, but your archive can be viewed by any software that understands how to parse ActivityPub documents. +Requesting an archive of your posts and media can be done once every 7 days, and can be downloaded in ActivityPub JSON format. Mastodon currently does not support importing posts or media due to technical limitations, but your archive can be viewed by any software that understands how to parse ActivityPub documents. ## Redirecting or moving your profile {#migration} @@ -29,7 +29,7 @@ Redirecting your account disables posting from that account and displays a "prof {{< figure src="/assets/account-move.jpg" caption="Profile move form" >}} -Moving your account is the same as redirecting your account, but it will also irreversibly force everyone to unfollow your current account and follow your new account, if their software supports the Move activity. Your toots will not be moved, due to technical limitations. There is also a very heavy cooldown period in which you cannot migrate again, so be very careful before using this option! +Moving your account is the same as redirecting your account, but it will also irreversibly force everyone to unfollow your current account and follow your new account, if their software supports the Move activity. Your posts will not be moved, due to technical limitations. There is also a very heavy cooldown period in which you cannot migrate again, so be very careful before using this option! ### Account aliases {#aliases} diff --git a/content/en/user/network.md b/content/en/user/network.md index 43e0462b..c6730fee 100644 --- a/content/en/user/network.md +++ b/content/en/user/network.md @@ -21,7 +21,7 @@ There is a way to filter the federated timeline to view only public posts create You can perform quick actions on a post directly from the timeline, or you can click on the post to load an expanded view that shows extra information, such as a full timestamp, interaction counts, and threaded replies, if any. The following actions can be performed on a post: -* **Reply** to a post by clicking the arrow icon. Your toot will show up in the thread below the post you are replying to. +* **Reply** to a post by clicking the arrow icon. Your post will show up in the thread below the post you are replying to. * **Boost** a post by clicking the cycled-arrow icon. The post will be reshared on your profile. * **Favourite** a post by clicking the star icon. The post will be added to your favourites list, and a favourite notification will be delivered to its author. * **Bookmark** a post by clicking the ribbon icon. The post will be privately added to your bookmarks list without generating a notification. @@ -48,7 +48,7 @@ When unread notifications are present, a checkmark will appear in the column hea As long as you encounter a person within your app’s user interface, e.g. the web interface on your home server, or your mobile app, you can just click “follow” and you won’t notice a difference if that person is on your server or not. -However if you come across someone’s public profile hosted on a different server, there’s an obstacle: That server sees you as just another anonymous visitor. Not to worry! You can simply copy the URL of that profile, or of one of their posts, and then paste that URL into the search function. +However if you come across someone’s public profile hosted on a different server, there’s an obstacle: That server sees you as just another anonymous visitor. Not to worry! You can copy the URL of that profile, or of one of their posts, and then paste that URL into the search function. If you are visiting a public page on another Mastodon site, see [Using Mastodon outside of your site](../external/#interact). @@ -62,15 +62,15 @@ If you are following someone, you also have the option to receive a notification {{< figure src="/assets/search.jpg" caption="The search function can be accessed from the sidebar." >}} -Mastodon's basic search allows logged-in users to find toots containing a specific hashtag, or to load a user or status directly if they know the URL or address. Searching for a term will show profiles whose username or display name contains that term, as well as hashtags that match or contain that term. +Mastodon's basic search allows logged-in users to find posts containing a specific hashtag, or to load a user or status directly if they know the URL or address. Searching for a term will show profiles whose username or display name contains that term, as well as hashtags that match or contain that term. -{{< figure src="/assets/direct-url.jpg" caption="An example of a toot being loaded directly by its URL." >}} +{{< figure src="/assets/direct-url.jpg" caption="An example of a post being loaded directly by its URL." >}} {{< figure src="/assets/search-accounts.jpg" caption="An example of accounts returned when searching for "cats"." >}} {{< figure src="/assets/search-hashtags.jpg" caption="An example of hashtags returned when searching for "cats"." >}} -Admins may optionally install full-text search. Mastodon’s full-text search allows logged-in users to find results from their own toots, their favourites, their bookmarks and their mentions. It deliberately does not allow searching for arbitrary strings in the entire database, in order to reduce the risk of abuse by people searching for controversial terms to find people to dogpile. +Admins may optionally install full-text search. Mastodon’s full-text search allows logged-in users to find results from their own posts, their favourites, their bookmarks and their mentions. It deliberately does not allow searching for arbitrary strings in the entire database, in order to reduce the risk of abuse by people searching for controversial terms to find people to dogpile. The following operators are supported: @@ -82,7 +82,7 @@ The following operators are supported: {{< figure src="/assets/dm-column.jpg" caption="A list of conversations containing direct messages." >}} -In Mastodon, direct messages are simply toots that have the "direct" visibility selected. Visibility can be selected per-post, which allows changing the privacy level later in a thread. The direct messages column currently shows a list of all conversations containing a direct post. Clicking on a conversation will load the associated thread. +In Mastodon, direct messages are just posts that have the "direct" visibility selected. Visibility can be selected per-post, which allows changing the privacy level later in a thread. The direct messages column currently shows a list of all conversations containing a direct post. Clicking on a conversation will load the associated thread. {{< figure src="/assets/dm-thread.jpg" caption="A direct message in a thread." >}} diff --git a/content/en/user/posting.md b/content/en/user/posting.md index 62a27213..b005f6f5 100644 --- a/content/en/user/posting.md +++ b/content/en/user/posting.md @@ -1,5 +1,5 @@ --- -title: Posting toots +title: Posting to your profile description: Sharing your thoughts has never been more convenient. menu: docs: @@ -15,7 +15,7 @@ The main body of each status update can be composed using the text field. The de ### Links {#links} -{{< figure src="/assets/compose-links.jpg" caption="Links must start with http\(s\):// and are counted as 23 characters regardless of length." >}} +{{< figure src="/assets/compose-links.jpg" caption="Links must start with http(s):// and are counted as 23 characters regardless of length." >}} If you include links in your post, they must begin with `http://` or `https://`. All links are counted as 23 characters, no matter how long they actually are, so there is no need to use a link shortener to save characters. In fact, using a link shortener is actively discouraged. @@ -47,10 +47,10 @@ You can attach either files or a poll to your status. Click the paper clip to attach a file to your post. You can attach the following: -* **Images** \(PNG, JPG, GIF\) **up to 8MB**. Images will be downscaled to 1.6 megapixels \(enough for a 1280x1280 image\). Up to 4 images can be attached. - * **Animated GIFs** are converted to soundless MP4s like on Imgur/Gfycat \(**GIFV**\). You can also upload soundless MP4 and WebM, which will be handled the same way. -* **Videos** \(MP4, M4V, MOV, WebM\) **up to 40MB**. Video will be transcoded to H.264 MP4 with a maximum bitrate of 1300kbps and framerate of 60fps. -* **Audio** \(MP3, OGG, WAV, FLAC, OPUS, AAC, M4A, 3GP\) **up to 40MB**. Audio will be transcoded to MP3 using V2 VBR \(roughly 192kbps\). +* **Images** (PNG, JPG, GIF) **up to 8MB**. Images will be downscaled to 1.6 megapixels (enough for a 1280x1280 image). Up to 4 images can be attached. + * **Animated GIFs** are converted to soundless MP4s like on Imgur/Gfycat (**GIFV**). You can also upload soundless MP4 and WebM, which will be handled the same way. +* **Videos** (MP4, M4V, MOV, WebM) **up to 40MB**. Video will be transcoded to H.264 MP4 with a maximum bitrate of 1300kbps and framerate of 60fps. +* **Audio** (MP3, OGG, WAV, FLAC, OPUS, AAC, M4A, 3GP) **up to 40MB**. Audio will be transcoded to MP3 using V2 VBR (roughly 192kbps). #### Editing media {#edit} @@ -104,7 +104,7 @@ A more limited delivery option. * Your post cannot be boosted, except by yourself. {{< hint style="warning" >}} -To effectively publish private \(followers-only\) posts, you must **lock your account**–otherwise, anyone could follow you to view older posts. +To effectively publish private (followers-only) posts, you must **lock your account**–otherwise, anyone could follow you to view older posts. {{< /hint >}} {{< hint style="danger" >}} diff --git a/content/en/user/preferences.md b/content/en/user/preferences.md index 919c1399..5f974119 100644 --- a/content/en/user/preferences.md +++ b/content/en/user/preferences.md @@ -25,7 +25,7 @@ In either interface, updates will load automatically as new posts are available. For accessibility reasons, the auto-play of animated GIFs is disabled by default. You can enable animated GIFs if you want to see animations. You can also reduce motion of animations throughout the UI. -Trending hashtags can be shown or hidden below the getting started column in the advanced UI, or below the column switcher in the simple UI \(only when there is enough space to display them\). +Trending hashtags can be shown or hidden below the getting started column in the advanced UI, or below the column switcher in the simple UI (only when there is enough space to display them). ### Confirmation dialogs {#confirm} diff --git a/content/en/user/profile.md b/content/en/user/profile.md index 4dfbd751..1a45c542 100644 --- a/content/en/user/profile.md +++ b/content/en/user/profile.md @@ -67,13 +67,20 @@ It’s completely up to you what you put there. The content can contain mentions Document-based verification and blue ticks are not possible without a central authority. However, Mastodon can cross-reference the links you put on your profile to prove that you are the real owner of those links. In case one of those links is your personal homepage that is known and trusted, it can serve as the next-best-thing to identity verification. -If you put a link in your profile metadata, Mastodon checks if the linked page links back to your Mastodon profile. If so, you get a verification checkmark next to that link, since you are confirmed as the owner. - -Behind the scenes, Mastodon checks for the `rel="me"` attribute on the link back. Likewise, Mastodon puts `rel="me"` on the links within profile metadata. - -The profile page you're linking to must be served securely (over HTTPS) in order to pass verification. - {{< hint style="info" >}} Because Mastodon can be self-hosted, there is no better way to verify your identity than to host Mastodon on your own domain, which people already trust. {{< /hint >}} +If you put an HTTPS link in your profile metadata, Mastodon checks if that link resolves to a web page that links back to your Mastodon profile with a special `rel=me` attribute. If so, you get a verification checkmark next to that link, since you are confirmed as the owner. Likewise, Mastodon puts `rel="me"` on the links within profile metadata. The link might look something like this: + +```html +Follow me on Mastodon! +``` + +More precisely, Mastodon will validate the link under the following conditions: +- Since 4.0: the hostname does not change after IDN normalization +- it starts with HTTPS +- the resolved page contains at least one `a` or `link` tag with a `rel="me"` +- the `href` attribute on one of those elements is equal to the URL for your Mastodon profile + +Alternatively, validation will occur if the resolved page's *first* link has an `href` value that redirects to your Mastodon profile's URL (such as through a link shortener). \ No newline at end of file diff --git a/content/en/user/run-your-own.md b/content/en/user/run-your-own.md index 323b5cdb..1cf431cb 100644 --- a/content/en/user/run-your-own.md +++ b/content/en/user/run-your-own.md @@ -27,7 +27,7 @@ Here is what you need: - A **VPS**. Something that will run the Mastodon code that will always be connected to the internet. **How to get**: DigitalOcean, Hetzner, Exoscale, Scaleway, any of the infinite number of hosting providers. Comes with a monthly or yearly cost that varies depending on hardware specifications. -- An **e-mail provider**. Mastodon needs to send confirmation links and various notifications through e-mail, and hosting your own SMTP server, while possible, is much more difficult to do reliably than to simply use a third-party provider. +- An **e-mail provider**. Mastodon needs to send confirmation links and various notifications through e-mail, and hosting your own SMTP server, while possible, is much more difficult to do reliably than to use a third-party provider. **How to get**: Mailgun, SparkPost, Postmark, Sendgrid, any of the infinite number of e-mail hosting providers that expose a SMTP API. Comes with a monthly cost based on volume of e-mails sent. - Optional: **Object storage provider**. Mastodon can save files that you and your users upload on the hard disk drive of the VPS it runs on, however, the hard disk drive is usually not infinite and difficult to upgrade later. An object storage provider gives you practically infinite metered file storage. @@ -58,4 +58,4 @@ That however does assume a single-machine setup. Mastodon scales quite well hori If you're interested in installing everything on your own, proceed here: -{{< page-ref page="admin/prerequisites.md" >}} +{{< page-ref page="admin/prerequisites" >}} diff --git a/content/en/user/signup.md b/content/en/user/signup.md index c475763a..5e63a111 100644 --- a/content/en/user/signup.md +++ b/content/en/user/signup.md @@ -25,7 +25,7 @@ Mastodon allows website administrators to set one of three different signup mode #### Open signup {#open} -Some websites may allow you to register immediately -- simply fill out the registration with your username, email address, and password, and you can start using your account. +Some websites may allow you to register immediately -- just fill out the registration with your username, email address, and password, and you can start using your account. #### Server invites {#invite} diff --git a/content/ja/_index.md b/content/ja/_index.md index 02fc7134..7d8915b5 100644 --- a/content/ja/_index.md +++ b/content/ja/_index.md @@ -93,19 +93,19 @@ Mastodonとの相互運用に必要な技術仕様ついて、詳しくは[Activ Mastodonの使い方を知る： -{{< page-ref page="user/signup.md" >}} +{{< page-ref page="user/signup" >}} Mastodonのインストール方法を学ぶ： -{{< page-ref page="admin/prerequisites.md" >}} +{{< page-ref page="admin/prerequisites" >}} Mastodonのアプリを作り方を学ぶ： -{{< page-ref page="client/intro.md" >}} +{{< page-ref page="client/intro" >}} Mastodonのバックエンドと貢献方法について知る： -{{< page-ref page="dev/overview.md" >}} +{{< page-ref page="dev/overview" >}} {{< hint style="info" >}} **［翻訳状態］** 日本語版は、英語版の「What is Mastodon?」（Mastodonとは？）と「Using Mastodon」（Masotodonを使う）が訳されている状態です（2020年9月27日）。他の項目や最新の情報については、[英語版](../)を参照してください。 diff --git a/content/ja/user/posting.md b/content/ja/user/posting.md index 6240a619..828c743f 100644 --- a/content/ja/user/posting.md +++ b/content/ja/user/posting.md @@ -15,7 +15,7 @@ menu: ### リンク {#links} -{{< figure src="/assets/image%20%287%29.png" caption="リンクはhttp\(s\)://で始まる必要があり、長さに関係なく23文字として数えられる" >}} +{{< figure src="/assets/image%20%287%29.png" caption="リンクはhttp(s)://で始まる必要があり、長さに関係なく23文字として数えられる" >}} 投稿にリンクを含めるなら、それは`http://`または`https://`で始まる必要があります。すべてのリンクは実際の長さに関係なく23文字として数えられるので、文字を失わないようにするためのリンク短縮サービスを使う必要はありません。実際、リンク短縮サービスを使うことは積極的に思い留まらせるでしょう。 diff --git a/content/ja/user/run-your-own.md b/content/ja/user/run-your-own.md index 2f4a9f1e..a59dcf25 100644 --- a/content/ja/user/run-your-own.md +++ b/content/ja/user/run-your-own.md @@ -52,4 +52,4 @@ menu: もしMastodonをインストールすることに興味がある場合は、次の手順に進んでください。 -{{< page-ref page="admin/prerequisites.md" >}} +{{< page-ref page="admin/prerequisites" >}} diff --git a/content/pl/_index.md b/content/pl/_index.md index 482566a3..42d2feb7 100644 --- a/content/pl/_index.md +++ b/content/pl/_index.md @@ -30,7 +30,7 @@ Serwer Mastodona może funkcjonować samodzielnie. Tak jak na tradycyjnej stroni Mastodon używa standaryzowanego, otwartego protokołu, aby implementować federację. Nazywa się on **ActivityPub**. Dowolne oprogramowanie, które również implementuje ActivityPub, może komunikować się z Mastodonem, tak jak serwery Mastodona komunikują się między sobą. -**Fediwersum** \(„sfederowane uniwersum”, z ang. „fediverse”\) to nazwa dla wszystkich stron mogących komunikować się wzajemnie w Internecie z użyciem ActivityPub. Zaliczają się do tego wszystkie serwery Mastodona, ale też inne implementacje: +**Fediwersum** („sfederowane uniwersum”, z ang. „fediverse”) to nazwa dla wszystkich stron mogących komunikować się wzajemnie w Internecie z użyciem ActivityPub. Zaliczają się do tego wszystkie serwery Mastodona, ale też inne implementacje: * Pleroma, modularny silnik mikroblogowy, * Pixelfed, sfederowana platforma do udostępniania zdjęć, pozwalająca na tworzenie i dzielenie się i przeglądanie wpisów multimedialnych, @@ -51,7 +51,7 @@ Ponieważ Mastodon jest po prostu oprogramowaniem, o które może opierać się > > -- Eugen Rochko, 6 lipca 2018, [„Cage the Mastodon”](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/) -> Scentralizowana platforma społecznościowa ma hierarchiczną strukturę, gdzie jej zasady i ich wymuszanie, jak i rozwój oraz kierunek rozwoju platformy są decyzją jej CEO \[...\] Zdecentralizowana sieć jest pozbawiona możliwości kontroli przez właściciela platormy, dzięki temu, że tego właściciela nie ma. +> Scentralizowana platforma społecznościowa ma hierarchiczną strukturę, gdzie jej zasady i ich wymuszanie, jak i rozwój oraz kierunek rozwoju platformy są decyzją jej CEO [...] Zdecentralizowana sieć jest pozbawiona możliwości kontroli przez właściciela platormy, dzięki temu, że tego właściciela nie ma. > > -- Eugen Rochko, 30 grudnia 2018, [„Dlaczego decentralizacja ma znaczenie?”](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/) @@ -91,19 +91,19 @@ W przeciwieństwie do własnościowych usług, **każdy może dowolnie uruchamia Naucz się korzystać z Mastodona: -{{< page-ref page="user/signup.md" >}} +{{< page-ref page="user/signup" >}} Naucz się instalować Mastodona: -{{< page-ref page="admin/prerequisites.md" >}} +{{< page-ref page="admin/prerequisites" >}} Naucz się tworzyć aplikacje dla Mastodona: -{{< page-ref page="client/intro.md" >}} +{{< page-ref page="client/intro" >}} Naucz się o back-endzie Mastodona i dowiedz się jak wnieść swój wkład: -{{< page-ref page="dev/overview.md" >}} +{{< page-ref page="dev/overview" >}} diff --git a/content/pl/user/discoverability.md b/content/pl/user/discoverability.md index dff9dda6..d83c1448 100644 --- a/content/pl/user/discoverability.md +++ b/content/pl/user/discoverability.md @@ -33,7 +33,7 @@ Możesz wybrać maksymalnie 5 spośród swoich publicznych wpisów do wyróżnie Katalog profilów pokazuje wszystkie konta, które zgodziły się być pokazywane w katalogu i może służyć szybkiemu wyszukiwaniu profilów, którymi możesz być zainteresowany(-a). -Katalog profilów może być posortowany według ostatniej aktywności \(ostatnio opublikowane wpisy\) lub od najnowszych użytkowników \(ostatnio założone konto\). Katalog może wyświetlać tylko lokalne konta lub wszystkie znane przez serwer. +Katalog profilów może być posortowany według ostatniej aktywności (ostatnio opublikowane wpisy) lub od najnowszych użytkowników (ostatnio założone konto). Katalog może wyświetlać tylko lokalne konta lub wszystkie znane przez serwer. Profile są przedstawiane jako karty zawierające nazwę wyświetlaną użytkownika, adres, biogram i kilka podstawowych statystyk jak liczba opublikowanych wpisów, liczba obserwujących i kiedy opublikowali ostatni wpis. diff --git a/content/pl/user/moderating.md b/content/pl/user/moderating.md index 26c7f81e..dd6c84d6 100644 --- a/content/pl/user/moderating.md +++ b/content/pl/user/moderating.md @@ -25,7 +25,7 @@ To ciąg znaków, który jest sprawdzany. Słowo kluczowe będzie wyszukiwane w ### Wygasanie po czasie {#filter-expire} -Opcjonalnie możesz zastosować filtr tylko na określony okres. Wygasłe filtry nie są automatycznie usuwane, ale mogą być włączone ponownie, ustawiając nową datę wygaśnięcia \(lub wyłączając wygasanie\). +Opcjonalnie możesz zastosować filtr tylko na określony okres. Wygasłe filtry nie są automatycznie usuwane, ale mogą być włączone ponownie, ustawiając nową datę wygaśnięcia (lub wyłączając wygasanie). ### Kontekst filtrów {#filter-context} @@ -104,5 +104,5 @@ Jeżeli zablokujesz cały serwer: {{< figure src="/assets/report-modal.jpg" caption="Okno zgłaszania pozwalające na wybór przykładowych wpisów, dodanie notatki czy przekierowanie zgłoszeń." >}} -Jeżeli zobaczysz wpis lub użytkownika naruszającego zasady Twojego serwera, możesz zgłosić użytkownika moderatorom swojego serwera. Wybranie opcji „Zgłoś” otworzy okno zgłaszania. Tam możesz \(jest to wskazane\) dodać notatkę, w której napiszesz, dlaczego zgłaszasz to konto. Możesz załączyć nieodpowiednie wpisy dla dodatkowego kontekstu zgłoszenia, a jeżeli naruszają one zasady zdalnego serwera, możesz przekierować zgłoszenie również do jego moderatorów. +Jeżeli zobaczysz wpis lub użytkownika naruszającego zasady Twojego serwera, możesz zgłosić użytkownika moderatorom swojego serwera. Wybranie opcji „Zgłoś” otworzy okno zgłaszania. Tam możesz (jest to wskazane) dodać notatkę, w której napiszesz, dlaczego zgłaszasz to konto. Możesz załączyć nieodpowiednie wpisy dla dodatkowego kontekstu zgłoszenia, a jeżeli naruszają one zasady zdalnego serwera, możesz przekierować zgłoszenie również do jego moderatorów. diff --git a/content/pl/user/posting.md b/content/pl/user/posting.md index 65cc1256..7098acf3 100644 --- a/content/pl/user/posting.md +++ b/content/pl/user/posting.md @@ -15,7 +15,7 @@ Główna treść każdego wpisu może zostać utworzona z użyciem pola tekstowe ### Odnośniki {#links} -{{< figure src="/assets/compose-links.jpg" caption="Odnośniki muszą zaczynać się od http\(s\):// i są liczone jako 23 znaki niezależnie od ich długości." >}} +{{< figure src="/assets/compose-links.jpg" caption="Odnośniki muszą zaczynać się od http(s):// i są liczone jako 23 znaki niezależnie od ich długości." >}} Jeżeli uwzględnisz w swoim wpisie odnośniki, muszą one zaczynać się od `http://` lub `https://`. Wszystkie odnośniki są traktowane, jakby miały 23 znaki, niezależnie od ich rzeczywistej długości, więc nie musisz korzystać z usług skracania odnośników. Właściwie to odradzamy korzystanie z nich. @@ -47,10 +47,10 @@ Możesz załączyć do wpisu pliki lub ankietę. Naciśnij ikonę spinacza, aby dodać plik do wpisu. Możesz załączyć: -* **Zdjęcia** \(PNG, JPG, GIF\) **do 8MB**. Zdjęcia zostaną zmniejszone do 1.6 megapikseli \(wystarczająco na obraz 1280x1280\). Możesz załączyć maksymalnie 4 zdjęcia. - * **Animowane GIF-y** są konwertowane do plików MP4 bez dźwięku jak na Imgur/Gfycat \(**GIFV**\). Możesz też wysłać plik MP4 lub WebM bez dźwięku, zostaną one obsłużone w ten sam sposób. -* **Filmy** \(MP4, M4V, MOV, WebM\) **do 40MB**. Filmy zostaną transkodowane do H.264 MP4 o maksymalnej przepustowości 1300kbps i liczby 60 klatek na sekundę. -* **Dźwięk** \(MP3, OGG, WAV, FLAC, OPUS, AAC, M4A, 3GP\) **do 40MB**. Dźwięk zostanie transkodowany do MP3 z użyciem V2 VBR \(około 192kbps\). +* **Zdjęcia** (PNG, JPG, GIF) **do 8MB**. Zdjęcia zostaną zmniejszone do 1.6 megapikseli (wystarczająco na obraz 1280x1280). Możesz załączyć maksymalnie 4 zdjęcia. + * **Animowane GIF-y** są konwertowane do plików MP4 bez dźwięku jak na Imgur/Gfycat (**GIFV**). Możesz też wysłać plik MP4 lub WebM bez dźwięku, zostaną one obsłużone w ten sam sposób. +* **Filmy** (MP4, M4V, MOV, WebM) **do 40MB**. Filmy zostaną transkodowane do H.264 MP4 o maksymalnej przepustowości 1300kbps i liczby 60 klatek na sekundę. +* **Dźwięk** (MP3, OGG, WAV, FLAC, OPUS, AAC, M4A, 3GP) **do 40MB**. Dźwięk zostanie transkodowany do MP3 z użyciem V2 VBR (około 192kbps). #### Edytowanie mediów {#edit} @@ -104,7 +104,7 @@ Bardziej ograniczona opcja doręczania. * Tylko Ty możesz udostępnić ten wpis. {{< hint style="warning" >}} -Aby publikowanie prywatnych wpisów \(tylko dla obserwujących\) miało sens, musisz **zablokować swoje konto** – w przeciwnym razie każdy może zaobserwować Cię, aby przeglądać Twoje starsze wpisy. +Aby publikowanie prywatnych wpisów (tylko dla obserwujących) miało sens, musisz **zablokować swoje konto** – w przeciwnym razie każdy może zaobserwować Cię, aby przeglądać Twoje starsze wpisy. {{< /hint >}} {{< hint style="danger" >}} diff --git a/content/pl/user/preferences.md b/content/pl/user/preferences.md index aa4183d3..b3a3b1b4 100644 --- a/content/pl/user/preferences.md +++ b/content/pl/user/preferences.md @@ -25,7 +25,7 @@ W obu interfejsach aktualizacje ładują się, gdy tylko dostępne są nowe wpis Z uwagi na dostępność, autoodtwarzanie animowanych GIF-ów jest domyślnie wyłączone. Możesz włączyć animowane GIF-y, jeżeli chcesz widzieć animacje. Możesz też ograniczyć ilość animacji w UI. -Trendujące hashtagi mogą być wyświetlane lub ukryte pod kolumną „Rozpocznij” w zaawansowanym UI lub pod wyborem kolumn w uproszczonym UI \(tylko jeśli jest wystarczająco miejsca, aby je wyświetlić\). +Trendujące hashtagi mogą być wyświetlane lub ukryte pod kolumną „Rozpocznij” w zaawansowanym UI lub pod wyborem kolumn w uproszczonym UI (tylko jeśli jest wystarczająco miejsca, aby je wyświetlić). ### Dialogi potwierdzenia {#confirm} diff --git a/content/pl/user/run-your-own.md b/content/pl/user/run-your-own.md index 17750d78..1f2b3f2f 100644 --- a/content/pl/user/run-your-own.md +++ b/content/pl/user/run-your-own.md @@ -52,4 +52,4 @@ Zakłada to jednak konfigurację na jednym urządzeniu. Mastodon dość dobrze s Jeżeli chcesz zainstalować wszystko samodzielnie, przejdź tutaj: -{{< page-ref page="admin/prerequisites.md" >}} +{{< page-ref page="admin/prerequisites" >}} diff --git a/content/zh-cn/_index.md b/content/zh-cn/_index.md index d049f9c9..807ccafc 100644 --- a/content/zh-cn/_index.md +++ b/content/zh-cn/_index.md @@ -49,7 +49,7 @@ Mastodon使用一种标准化的、开放的协议来实现站点之间的互动 > > -- Eugen Rochko, Jul 6 2018, [《将Mastodon关到笼子里去》](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/) -> 一个中心化的社交媒体平台有一个等级结构，在这个结构中平台的规则及其实施，以及平台的发展方向都是由CEO决定的\[……\] 一个去中心化的网络有意放弃了对平台所有权的控制，从本质上来讲是没有平台所有者的。 +> 一个中心化的社交媒体平台有一个等级结构，在这个结构中平台的规则及其实施，以及平台的发展方向都是由CEO决定的[……] 一个去中心化的网络有意放弃了对平台所有权的控制，从本质上来讲是没有平台所有者的。 > > -- Eugen Rochko, Dec 30 2018, [《为什么去中心化很重要？》](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/) @@ -89,18 +89,18 @@ Mastodon的开发同样是通过[Patreon](https://patreon.com/mastodon)和[OpenC 学习如何使用Mastodon： -{{< page-ref page="user/signup.md" >}} +{{< page-ref page="user/signup" >}} 学习如何安装Mastodon： -{{< page-ref page="admin/prerequisites.md" >}} +{{< page-ref page="admin/prerequisites" >}} 学习如何为Mastodon编写应用程序： -{{< page-ref page="client/intro.md" >}} +{{< page-ref page="client/intro" >}} 了解Mastodon后端以及如何向Mastodon项目做贡献： -{{< page-ref page="dev/overview.md" >}} +{{< page-ref page="dev/overview" >}} {{< translation-status-zh-cn raw_title="What is Mastodon?" raw_link="/" last_tranlation_time="2020-05-02" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} diff --git a/content/zh-cn/admin/install.md b/content/zh-cn/admin/install.md index 5ae612af..669408e5 100644 --- a/content/zh-cn/admin/install.md +++ b/content/zh-cn/admin/install.md @@ -129,7 +129,7 @@ su - mastodon 使用git下载最新稳定版Mastodon： ```bash -git clone https://github.com/tootsuite/mastodon.git live && cd live +git clone https://github.com/mastodon/mastodon.git live && cd live git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1) ``` @@ -162,7 +162,7 @@ RAILS_ENV=production bundle exec rake mastodon:setup * 预编译静态文件 * 创建数据库schema -配置文件被保存在`.env.production`。如果你愿意的话，你可以查看并编辑这个文件。请参阅[配置文件的文档]({{< relref "config.md" >}})。 +配置文件被保存在`.env.production`。如果你愿意的话，你可以查看并编辑这个文件。请参阅[配置文件的文档]({{< relref "config" >}})。 你已经完成需使用mastodon用户进行的操作，请切换回root用户： diff --git a/content/zh-cn/admin/migrating.md b/content/zh-cn/admin/migrating.md index 563fbc63..46b7feb6 100644 --- a/content/zh-cn/admin/migrating.md +++ b/content/zh-cn/admin/migrating.md @@ -15,7 +15,7 @@ menu: ## 基本步骤 {#basic-steps} -1. 依照[产品指南]({{< relref "install.md" >}})安装新的Mastodon服务器（切记，不要运行 `mastodon:setup`）。 +1. 依照[产品指南]({{< relref "install" >}})安装新的Mastodon服务器（切记，不要运行 `mastodon:setup`）。 2. 停止旧服务器上的Mastodon（`systemctl stop 'mastodon-*.service'`）。 3. 依照如下指示，导出并导入Postgres数据库。 4. 依照如下指示，复制 `system/` 目录下文件。（注意：如果你使用S3存储，你可以跳过此步）。 diff --git a/content/zh-cn/admin/scaling.md b/content/zh-cn/admin/scaling.md index 5bb508f3..baf9b19b 100644 --- a/content/zh-cn/admin/scaling.md +++ b/content/zh-cn/admin/scaling.md @@ -11,11 +11,11 @@ menu: Mastodon有三种进程： -* Web \(Puma\) +* Web (Puma) * Streaming API -* 后台进程 \(Sidekiq\) +* 后台进程 (Sidekiq) -### Web \(Puma\) {#web} +### Web (Puma) {#web} web进程处理绝大多数应用的短HTTP请求。以下环境变量可以控制它： @@ -37,7 +37,7 @@ streaming API处理长HTTP连接与WebSockets连接，通过这些连接用户 一个进程可以处理相当数量的连接。 如果您愿意，streaming API可以托管在其他子域上，例如：避免nginx代理连接开销。 -### 后台进程 \(Sidekiq\) {#sidekiq} +### 后台进程 (Sidekiq) {#sidekiq} Mastodon许多任务都分配给后台进程，以确保HTTP请求快速响应，并防止HTTP请求中止影响到这些任务的执行。Sidekiq是单个进程，具有可配置的线程数。 diff --git a/content/zh-cn/admin/tootctl.md b/content/zh-cn/admin/tootctl.md index 322354dc..ef1a71fb 100644 --- a/content/zh-cn/admin/tootctl.md +++ b/content/zh-cn/admin/tootctl.md @@ -23,7 +23,7 @@ RAILS_ENV=production bin/tootctl help ## 基础命令 -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/cli.rb" caption="lib/cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/cli.rb" caption="lib/cli.rb" >}} ### `tootctl self-destruct` {#self-destruct} @@ -51,7 +51,7 @@ RAILS_ENV=production bin/tootctl help ## 帐户相关命令 {#accounts} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts\_cli.rb" >}} ### `tootctl accounts rotate` {#accounts-rotate} @@ -208,7 +208,7 @@ RAILS_ENV=production bin/tootctl help ## 缓存相关命令 {#cache} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/cache_cli.rb" caption="lib/mastodon/cache\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/cache_cli.rb" caption="lib/mastodon/cache\_cli.rb" >}} ### `tootctl cache clear` {#cache-clear} @@ -232,7 +232,7 @@ RAILS_ENV=production bin/tootctl help ## 域名相关命令 {#domains} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/domains_cli.rb" caption="lib/mastodon/domains\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/domains_cli.rb" caption="lib/mastodon/domains\_cli.rb" >}} ### `tootctl domains purge` {#domains-purge} @@ -269,7 +269,7 @@ RAILS_ENV=production bin/tootctl help ## Emoji相关命令 {#emoji} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/emoji_cli.rb" caption="lib/mastodon/emoji\_cli.rb" >}} ### `tootctl emoji import` {#emoji-import} @@ -301,7 +301,7 @@ RAILS_ENV=production bin/tootctl help ## 时间流（Feeds）相关命令 {#feeds} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/feeds_cli.rb" caption="lib/mastodon/feeds\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/feeds_cli.rb" caption="lib/mastodon/feeds\_cli.rb" >}} ### `tootctl feeds build` {#feeds-build} @@ -327,7 +327,7 @@ RAILS_ENV=production bin/tootctl help ## 媒体相关命令 {#media} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/media_cli.rb" caption="lib/mastodon/media\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/media_cli.rb" caption="lib/mastodon/media\_cli.rb" >}} ### `tootctl media remove` {#media-remove} @@ -390,7 +390,7 @@ RAILS_ENV=production bin/tootctl help ## 预览卡片（Preview Cards）相关命令 {#preview_cards} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/preview_cards_cli.rb" caption="lib/mastodon/preview\_cards\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/preview_cards_cli.rb" caption="lib/mastodon/preview\_cards\_cli.rb" >}} ### `tootctl preview_cards remove` {#preview_cards-remove} @@ -409,7 +409,7 @@ RAILS_ENV=production bin/tootctl help ## 搜索相关命令 {#search} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/search_cli.rb" caption="lib/mastodon/search\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/search_cli.rb" caption="lib/mastodon/search\_cli.rb" >}} ### `tootctl search deploy` {#search-deploy} @@ -425,7 +425,7 @@ RAILS_ENV=production bin/tootctl help ## 站点设定相关命令 {#settings} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/settings_cli.rb" caption="lib/mastodon/settings\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/settings_cli.rb" caption="lib/mastodon/settings\_cli.rb" >}} ### `tootctl settings registrations open` {#settings-registrations-open} @@ -443,7 +443,7 @@ RAILS_ENV=production bin/tootctl help ## 嘟文相关命令 {#statuses} -{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/statuses\_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/statuses_cli.rb" caption="lib/mastodon/statuses\_cli.rb" >}} ### `tootctl statuses remove` {#statuses-remove} diff --git a/content/zh-cn/admin/upgrading.md b/content/zh-cn/admin/upgrading.md index 90702321..be88e530 100644 --- a/content/zh-cn/admin/upgrading.md +++ b/content/zh-cn/admin/upgrading.md @@ -7,10 +7,10 @@ menu: --- {{< hint style="info" >}} -当一个新的Mastodon版本释出后，它将出现在[GitHub releases页面](https://github.com/tootsuite/mastodon/releases)。请注意：运行来自`master`分支的未释出代码，虽然可以进行，但不推荐这样做。 +当一个新的Mastodon版本释出后，它将出现在[GitHub releases页面](https://github.com/mastodon/mastodon/releases)。请注意：运行来自`master`分支的未释出代码，虽然可以进行，但不推荐这样做。 {{< /hint >}} -Mastodon版本与git tags一致。在尝试升级之前，请至[GitHub releases页面](https://github.com/tootsuite/mastodon/releases)查找所需版本。该页面包含了一个**更新日专**，其中描述你需要了解的所有差异，以及**特定的升级指令**。 +Mastodon版本与git tags一致。在尝试升级之前，请至[GitHub releases页面](https://github.com/mastodon/mastodon/releases)查找所需版本。该页面包含了一个**更新日专**，其中描述你需要了解的所有差异，以及**特定的升级指令**。 开始之前，切换至`mastodon`用户： diff --git a/content/zh-cn/user/network.md b/content/zh-cn/user/network.md index 78c7029c..26c0a0f4 100644 --- a/content/zh-cn/user/network.md +++ b/content/zh-cn/user/network.md @@ -13,7 +13,7 @@ menu: 为了让你发现潜在的有趣内容，Mastodon提供了一种浏览所有公共嘟文的方法。当然，所有Mastodon服务器之间并不会全局共享嘟文，因此无法同时浏览*所有*公共嘟文。当你浏览**跨站公共时间轴**时，你将看到你所在的服务器所知道的所有公共嘟文。你的服务器可以通过多种方式发现嘟文，但其中大部分是来自你服务器上的其他用户关注的人。 -这里有一种方法筛选跨站时间轴，以仅查看由你所在服务器发出的公共嘟文：**本站时间轴**。请注意这里的本地\(local\)仅是指服务器，而不是地理位置。 +这里有一种方法筛选跨站时间轴，以仅查看由你所在服务器发出的公共嘟文：**本站时间轴**。请注意这里的本地(local)仅是指服务器，而不是地理位置。 ## 与其他人的嘟文互动 {#actions} diff --git a/content/zh-cn/user/posting.md b/content/zh-cn/user/posting.md index cb46a8d6..82779bc2 100644 --- a/content/zh-cn/user/posting.md +++ b/content/zh-cn/user/posting.md @@ -15,7 +15,7 @@ menu: ### 链接 {#links} -{{< figure src="/assets/image%20%287%29.png" caption="链接必须以 http\(s\):// 开头，无论长度如何，都将被视为23个字符" >}} +{{< figure src="/assets/image%20%287%29.png" caption="链接必须以 http(s):// 开头，无论长度如何，都将被视为23个字符" >}} 如果你的嘟文中有链接，它们必须以 `http://` 或 `https://` 开头。所有的链接无论实际上有多长，都将被记作23个字符。因此没有使用短链接来节省字符的必要。事实上，使用短链接是极其不被推荐的。 @@ -47,10 +47,10 @@ menu: 点击回形针将文件附加到你的嘟文上。你可以附上以下文件： -* **图像** \(PNG, JPG, GIF\)：**最大8MB**。图像将被压缩至160万像素（足够一张1280x1280px的图像）。最多可以附加4张图片。 - * **GIF动画**：GIF动画会转换成无声的mp4，就像 Imgur/Gfycat \(**GIFV**\) 一样。你也可以上传无声的MP4和WebM，它们将被以同样方式处理。 -* **视频** \(MP4, M4V, MOV, WebM\)：**最大40MB**。视频将被转换为最大比特率1300kbps，最大帧率60fps的H.264 MP4。 -* **音频** \(MP3, OGG, WAV, FLAC, OPUS, AAC, M4A, 3GP\)：**最大40MB**。音频将使用V2 VBR（大约192kbps）转码成MP3。 +* **图像** (PNG, JPG, GIF)：**最大8MB**。图像将被压缩至160万像素（足够一张1280x1280px的图像）。最多可以附加4张图片。 + * **GIF动画**：GIF动画会转换成无声的mp4，就像 Imgur/Gfycat (**GIFV**) 一样。你也可以上传无声的MP4和WebM，它们将被以同样方式处理。 +* **视频** (MP4, M4V, MOV, WebM)：**最大40MB**。视频将被转换为最大比特率1300kbps，最大帧率60fps的H.264 MP4。 +* **音频** (MP3, OGG, WAV, FLAC, OPUS, AAC, M4A, 3GP)：**最大40MB**。音频将使用V2 VBR（大约192kbps）转码成MP3。 #### 编辑媒体 {#edit} @@ -84,8 +84,8 @@ menu: 这是默认的选项。 * 任何人都可以通过访问永久链接看到你的嘟文，而不需要登录。 -* 你的嘟文将出现在应用程序内的公共\(Public\)时间轴上。 -* 你的关注者将在他们的主页\(Home\)上接收到这条嘟文，任何被提及的人都将在通知中接收到这条嘟文。 +* 你的嘟文将出现在应用程序内的公共(Public)时间轴上。 +* 你的关注者将在他们的主页(Home)上接收到这条嘟文，任何被提及的人都将在通知中接收到这条嘟文。 * 你的嘟文可以被转发到其他人的主页中。 ### 不公开 {#unlisted} diff --git a/content/zh-cn/user/run-your-own.md b/content/zh-cn/user/run-your-own.md index 6424b6de..98aa8393 100644 --- a/content/zh-cn/user/run-your-own.md +++ b/content/zh-cn/user/run-your-own.md @@ -55,6 +55,6 @@ menu: 如果你有兴趣自己安装一切，请点击这里： -{{< page-ref page="admin/prerequisites.md" >}} +{{< page-ref page="admin/prerequisites" >}} {{< translation-status-zh-cn raw_title="Running your own server" raw_link="/user/run-your-own/" last_tranlation_time="2020-05-03" raw_commit="ad1ef20f171c9f61439f32168987b0b4f9abd74b">}} diff --git a/i18n/en.toml b/i18n/en.toml index 1aa094aa..46549603 100644 --- a/i18n/en.toml +++ b/i18n/en.toml @@ -46,6 +46,9 @@ other = "required" [optional] other = "optional" +[nullable] +other = "nullable" + [pathParameters] other = "Path Parameters" diff --git a/i18n/ja.toml b/i18n/ja.toml index 3d21bbbb..0e38e40c 100644 --- a/i18n/ja.toml +++ b/i18n/ja.toml @@ -46,6 +46,9 @@ other = "必須" [optional] other = "選択" +[nullable] +other = "nullable" + [pathParameters] other = "パスパラメーター" diff --git a/i18n/pl.toml b/i18n/pl.toml index 385f37f3..865c0025 100644 --- a/i18n/pl.toml +++ b/i18n/pl.toml @@ -46,6 +46,9 @@ other = "wymagane" [optional] other = "nieobowiązkowe" +[nullable] +other = "nullable" + [pathParameters] other = "Parametry ścieżki" diff --git a/i18n/zh-cn.toml b/i18n/zh-cn.toml index acc88d63..5e9093f5 100644 --- a/i18n/zh-cn.toml +++ b/i18n/zh-cn.toml @@ -46,6 +46,9 @@ other = "必需的" [optional] other = "可选的" +[nullable] +other = "nullable" + [pathParameters] other = "路径参数" diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html new file mode 100644 index 00000000..c71271d9 --- /dev/null +++ b/layouts/_default/_markup/render-heading.html @@ -0,0 +1,19 @@ + + {{.Text | safeHTML}} + + + + + + \ No newline at end of file diff --git a/layouts/_default/single.html b/layouts/_default/single.html index f66d4680..49eac71e 100644 --- a/layouts/_default/single.html +++ b/layouts/_default/single.html @@ -11,7 +11,7 @@ {{ .Content }}

- {{ i18n "lastUpdated" }} {{ .Lastmod.Format "January 2, 2006" }}{{ with .File }} · {{ i18n "improvePage" }}{{ end }} + {{ i18n "lastUpdated" }} {{ .Lastmod.Format "January 2, 2006" }}{{ with .File }} · {{ i18n "improvePage" }}{{ end }} {{ if .IsTranslated }}
diff --git a/layouts/index.html b/layouts/index.html index 32a98493..166bcedf 100644 --- a/layouts/index.html +++ b/layouts/index.html @@ -11,7 +11,7 @@ {{ .Content }}

- {{ i18n "lastUpdated" }} {{ i18n "lastUpdatedDateFormat" .Lastmod }}{{ with .File }} · {{ i18n "improvePage" }}{{ end }} + {{ i18n "lastUpdated" }} {{ i18n "lastUpdatedDateFormat" .Lastmod }}{{ with .File }} · {{ i18n "improvePage" }}{{ end }} {{ if .IsTranslated }}
diff --git a/layouts/partials/footer.html b/layouts/partials/footer.html index 0bff4a03..5b9ac151 100644 --- a/layouts/partials/footer.html +++ b/layouts/partials/footer.html @@ -31,5 +31,5 @@ {{ i18n "joinMastodon" }} · {{ i18n "blog" }} · ·

-

{{ with .File }}{{ i18n "viewSource" }} · {{ end }}CC BY-SA 4.0 · {{ i18n "imprint" }}

+

{{ with .File }}{{ i18n "viewSource" }} · {{ end }}CC BY-SA 4.0 · {{ i18n "imprint" }}

diff --git a/layouts/shortcodes/nullable.html b/layouts/shortcodes/nullable.html new file mode 100644 index 00000000..82ee5228 --- /dev/null +++ b/layouts/shortcodes/nullable.html @@ -0,0 +1 @@ +{{ i18n "nullable" }} \ No newline at end of file diff --git a/layouts/shortcodes/optional.html b/layouts/shortcodes/optional.html new file mode 100644 index 00000000..e141b706 --- /dev/null +++ b/layouts/shortcodes/optional.html @@ -0,0 +1 @@ +{{ i18n "optional" }} \ No newline at end of file diff --git a/layouts/shortcodes/page-relref.html b/layouts/shortcodes/page-relref.html new file mode 100644 index 00000000..56c8f396 --- /dev/null +++ b/layouts/shortcodes/page-relref.html @@ -0,0 +1,4 @@ + +
+ {{ .Get "caption" | markdownify }} + \ No newline at end of file diff --git a/layouts/shortcodes/required.html b/layouts/shortcodes/required.html new file mode 100644 index 00000000..b0515813 --- /dev/null +++ b/layouts/shortcodes/required.html @@ -0,0 +1 @@ +{{ i18n "required" }} \ No newline at end of file diff --git a/layouts/shortcodes/translation-status-zh-cn.html b/layouts/shortcodes/translation-status-zh-cn.html index 44082590..2455bbbf 100644 --- a/layouts/shortcodes/translation-status-zh-cn.html +++ b/layouts/shortcodes/translation-status-zh-cn.html @@ -1,6 +1,6 @@

翻译状态： - 本文是英文页面 {{ .Get "raw_title" }} 的翻译，最后翻译时间：{{ .Get "last_tranlation_time" }}，点击这里可以查看翻译后页面的改动。 + 本文是英文页面 {{ .Get "raw_title" }} 的翻译，最后翻译时间：{{ .Get "last_tranlation_time" }}，点击这里可以查看翻译后页面的改动。