3628b6d434
* 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
21 KiB
| title | description | menu | aliases | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| admin/accounts API methods | Perform moderation actions with accounts. |
|
|
View accounts (v1)
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]({{<relref "api/guidelines#pagination">}}) for more information.
Returns: Array of [Admin::Account]({{<relref "entities/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 <user token>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
- 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
[
{
"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
{
"error": "This action is not allowed"
}
View accounts (v2)
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]({{<relref "api/guidelines#pagination">}}) for more information.
Returns: Array of [Admin::Account]({{<relref "entities/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 <user token>to gain authorized access to this API method.
Query parameters
- origin
- String. Filter for
localorremoteaccounts. - status
- String. Filter for
active,pending,disabled,silenced, orsuspendedaccounts. - permissions
- String. Filter for accounts with
staffpermissions (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.
- 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
[
{
"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
{
"error": "This action is not allowed"
}
View a specific account
GET https://mastodon.example/api/v1/admin/accounts/:id HTTP/1.1
View admin-level information about the given account.
Returns: [Admin::Account]({{<relref "entities/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 <user token>to gain authorized access to this API method.
Response
200: OK
{
"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
{
"error": "This action is not allowed"
}
404: Not found
Account does not exist
{
"error": "Record not found"
}
Approve a pending account
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]({{<relref "entities/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 <user token>to gain authorized access to this API method.
Response
200: OK
The account is now approved
{
"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.
{
"error": "This action is not allowed"
}
404: Not found
Account does not exist
{
"error": "Record not found"
}
Reject a pending account
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]({{<relref "entities/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 <user token>to gain authorized access to this API method.
Response
200: OK
{
"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.
{
"error": "This action is not allowed"
}
404: Not found
Account does not exist
{
"error": "Record not found"
}
Delete an account
DELETE https://mastodon.example/api/v1/admin/accounts/:id HTTP/1.1
Permanently delete data for a suspended account.
Returns: [Admin::Account]({{<relref "entities/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 <user token>to gain authorized access to this API method.
Response
200: OK
The account's data has been deleted.
{
"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.
{
"error": "This action is not allowed"
}
Perform an action against an account
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 <user token>to gain authorized access to this API method.
Form data parameters
- type
- {{}} String. The type of action to be taken:
none,sensitive,disable,silence, orsuspend. - 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
{}
403: Forbidden
Authorized user is missing a permission, or invalid or missing Authorization header
{
"error": "This action is not allowed"
}
404: Not found
Account or Report with given ID does not exist
{
"error": "Record not found"
}
422: Server error
type is not provided or is not understood
{
"error": "Record invalid"
}
Enable a currently disabled account
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]({{<relref "entities/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 <user token>to gain authorized access to this API method.
Response
200: OK
Account was enabled, or was already enabled.
{
"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
{
"error": "This action is not allowed"
}
404: Not found
Account does not exist
{
"error": "Record not found"
}
Unsilence an account
POST https://mastodon.example/api/v1/admin/accounts/:id/unsilence HTTP/1.1
Unsilence an account if it is currently silenced.
Returns: [Admin::Account]({{<relref "entities/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 <user token>to gain authorized access to this API method.
Response
200: OK
Account was unsilenced, or was already not silenced
{
"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
{
"error": "This action is not allowed"
}
404: Not found
Account does not exist
{
"error": "Record not found"
}
Unsuspend an account
POST https://mastodon.example/api/v1/admin/accounts/:id/unsuspend HTTP/1.1
Unsuspend a currently suspended account.
Returns: [Admin::Account]({{<relref "entities/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 <user token>to gain authorized access to this API method.
Response
200: OK
Account successfully unsuspended
{
"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
{
"error": "This action is not allowed"
}
404: Not found
Account does not exist
{
"error": "Record not found"
}
Unmark an account as sensitive
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]({{<relref "entities/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 <user token>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.
{
"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
{
"error": "This action is not allowed"
}
404: Not found
Account does not exist
{
"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" >}}