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

ip_blocks API methods

Disallow certain IP address ranges from signing up.

    • List all IP blocks
    • Get a single IP block
    • Block an IP address range from signing up
    • Update a domain block
    • Delete an IP block
    • See also

List all IP blocks

GET /api/v1/admin/ip_blocks HTTP/1.1

Show information about all blocked IP ranges.

Returns: Array of Admin::IpBlock
OAuth: User token + admin:read:ip_blocks
Permissions: Manage Blocks
Version history:
4.0.0 - added

Request

Headers
Authorization
required Provide this header with Bearer <user_token> 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 blocks. Max 200 blocks.

Response

200: OK
[
  {
    "id": "1",
    "ip": "8.8.8.8/32",
    "severity": "no_access",
    "comment": "",
    "created_at": "2022-11-16T07:22:00.501Z",
    "expires_at": null
  },
  // ...
]

Because IpBlock 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.

Link: <http://mastodon.example/api/v1/admin/ip_blocks?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/ip_blocks?limit=2&since_id=1>; rel="prev"
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

Get a single IP block

GET /api/v1/admin/ip_blocks/:id HTTP/1.1

Show information about a single IP block.

Returns: Admin::IpBlock
OAuth: User token + admin:read:ip_blocks
Permissions: Manage Blocks
Version history:
4.0.0 - added

Path parameters
:id
required String. The ID of the IpBlock 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": "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

{
  "error": "This action is not allowed"
}
404: Not found

IpBlock with the given ID does not exist

{
	"error": "Record not found"
}

Block an IP address range from signing up

POST /api/v1/admin/ip_blocks HTTP/1.1

Add an IP address range to the list of IP blocks.

Returns: Admin::IpBlock
OAuth: User token + admin:write:ip_blocks
Permissions: Manage Blocks
Version history:
4.0.0 - added

Request

Headers
Authorization
required Provide this header with Bearer <user_token> 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
required 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.

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

{
  "error": "This action is not allowed"
}
422: Unprocessable entity

IP has already been blocked, and/or no severity was provided

{
  "error": "Validation failed: Severity can't be blank, Ip has already been taken"
}

Update a domain block

PUT /api/v1/admin/ip_blocks/:id HTTP/1.1

Change parameters for an existing IP block.

Returns: Admin::IpBlock
OAuth: User token + admin:write:ip_blocks
Permissions: Manage Blocks
Version history:
4.0.0 - added

Request

Path parameters
:id
required String. The ID of the IpBlock in the database.
Headers
Authorization
required Provide this header with Bearer <user_token> 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

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

{
  "error": "This action is not allowed"
}

Delete an IP block

DELETE /api/v1/admin/ip_blocks/:id HTTP/1.1

Lift a block against an IP range.

Returns: Admin::IpBlock
OAuth: User token + admin:write:domain_blocks
Permissions: Manage Blocks
Version history:
4.0.0 - added

Request

Path parameters
:id
required String. The ID of the DomainAllow 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 IP has been removed from the block list

{}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}
404: Not found

IpBlock with the given ID does not exist

{
	"error": "Record not found"
}

See also

app/controllers/api/v1/admin/ip_blocks_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