Mastodon
  • What is Mastodon?
  • Using Mastodon
    • Signing up for an account
    • Setting up your profile
    • Posting to your profile
    • Using the network features
    • Dealing with unwanted content
    • Promoting yourself and others
    • Set your preferences
    • More settings
    • Using Mastodon externally
    • Moving or leaving accounts
    • Running your own server
  • Running Mastodon
    • Preparing your machine
    • Installing from source
    • Configuring your environment
    • Configuring full-text search
    • Installing optional features
      • Object storage
      • Onion services
      • Captcha
      • Single Sign On
    • Setting up your new instance
    • Using the admin CLI
    • Upgrading to a new release
    • Backing up your server
    • Migrating to a new machine
    • Scaling up your server
    • Moderation actions
    • Troubleshooting errors
      • Database index corruption
    • Roles
  • Developing Mastodon apps
    • Getting started with the API
    • Playing with public data
    • Obtaining client app access
    • Logging in with an account
    • Libraries and implementations
  • Contributing to Mastodon
    • Technical overview
    • Setting up a dev environment
    • Code structure
    • Routes
    • Bug bounties and responsible disclosure
  • Spec compliance
    • ActivityPub
    • WebFinger
    • Security
    • Microformats
    • OAuth
    • Bearcaps
  • REST API
    • Datetime formats
    • Guidelines and best practices
    • OAuth Tokens
    • OAuth Scopes
    • Rate limits
  • API Methods
    • apps
      • oauth
      • emails
    • accounts
      • bookmarks
      • favourites
      • mutes
      • blocks
      • domain_blocks
      • filters
      • reports
      • follow_requests
      • endorsements
      • featured_tags
      • preferences
      • followed_tags
      • suggestions
      • tags
    • profile
    • statuses
      • media
      • polls
      • scheduled_statuses
    • timelines
      • conversations
      • lists
      • markers
      • streaming
    • grouped notifications
    • notifications
      • push
    • search
    • instance
      • trends
      • directory
      • custom_emojis
      • announcements
    • admin
      • accounts
      • canonical_email_blocks
      • dimensions
      • domain_allows
      • domain_blocks
      • email_domain_blocks
      • ip_blocks
      • measures
      • reports
      • retention
      • trends
    • proofs
    • oembed
  • API Entities
    • Account
    • AccountWarning
    • Admin::Account
    • Admin::CanonicalEmailBlock
    • Admin::Cohort
    • Admin::Dimension
    • Admin::DomainAllow
    • Admin::DomainBlock
    • Admin::EmailDomainBlock
    • Admin::Ip
    • Admin::IpBlock
    • Admin::Measure
    • Admin::Report
    • Announcement
    • Appeal
    • Application
    • Context
    • Conversation
    • CustomEmoji
    • DomainBlock
    • Error
    • ExtendedDescription
    • FamiliarFollowers
    • FeaturedTag
    • Filter
    • FilterKeyword
    • FilterResult
    • FilterStatus
    • IdentityProof
    • Instance
    • List
    • Marker
    • MediaAttachment
    • Notification
    • NotificationPolicy
    • NotificationRequest
    • Poll
    • Preferences
    • PreviewCard
    • PreviewCardAuthor
    • PrivacyPolicy
    • Quote
    • Reaction
    • Relationship
    • RelationshipSeveranceEvent
    • Report
    • Role
    • Rule
    • ScheduledStatus
    • Search
    • ShallowQuote
    • Status
    • StatusEdit
    • StatusSource
    • Suggestion
    • Tag
    • TermsOfService
    • Token
    • Translation
    • V1::Filter
    • V1::Instance
    • V1::NotificationPolicy
    • WebPushSubscription

admin/accounts API methods

Perform moderation actions with accounts.

    • View accounts (v1)
    • View accounts (v2)
    • View a specific account
    • Approve a pending account
    • Reject a pending account
    • Delete an account
    • Perform an action against an account
    • Enable a currently disabled account
    • Unsilence an account
    • Unsuspend an account
    • Unmark an account as sensitive
    • See also

View accounts (v1)

GET /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
required 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
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. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts.

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 /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
required Provide this header with Bearer <user_token> 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[]
Array of 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. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
limit
Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts.

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 /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
required String. The ID of the Account in the database.
Headers
Authorization
required 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 /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
required String. The ID of the Account in the database.
Headers
Authorization
required 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 /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
required String. The ID of the Account in the database.
Headers
Authorization
required 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 /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
required String. The ID of the Account in the database.
Headers
Authorization
required 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 /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
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
required String. The ID of the Account in the database.
Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.
Form data parameters
type
required 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

{}
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 /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
required String. The ID of the Account in the database.
Headers
Authorization
required 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 /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
required String. The ID of the Account in the database.
Headers
Authorization
required 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 /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
required String. The ID of the Account in the database.
Headers
Authorization
required 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 /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
required String. The ID of the Account in the database.
Headers
Authorization
required 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

app/controllers/api/v1/admin/accounts_controller.rb
app/controllers/api/v1/admin/account_actions_controller.rb

Last updated October 10, 2024 · Improve this page

Sponsored by

Dotcom-Monitor LoadView Stephen Tures Swayable SponsorMotion

Join Mastodon · Blog ·

View source · CC BY-SA 4.0 · Imprint