documentation/content/en/methods/admin/domain_blocks.md

---

title: admin/domain_blocks API methods description: Disallow certain domains to federate. menu: docs:

name: domain_blocks
parent: methods-admin
identifier: methods-admin-domain_blocks

aliases: [

"/methods/admin/domain_blocks",
"/api/methods/admin/domain_blocks",

]

List all blocked domains {#get}

GET /api/v1/admin/domain_blocks HTTP/1.1

Show information about all blocked domains.

Returns: Array of 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 <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",
    "domain": "example.com",
    "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
    "created_at": "2022-11-16T08:15:34.238Z",
    "severity": "noop",
    "reject_media": false,
    "reject_reports": false,
    "private_comment": null,
    "public_comment": null,
    "obfuscate": false
  },
  // ...
]

Because DomainBlock 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/domain_blocks?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/domain_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 blocked domain {#get-one}

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

Show information about a single blocked domain.

Returns: 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 <user token> to gain authorized access to this API method.

Response

200: OK

{
  "id": "1",
  "domain": "example.com",
  "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
  "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

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

404: Not found

DomainBlock with the given ID does not exist

{
  "error": "Record not found"
}

---

Block a domain from federating {#create}

POST /api/v1/admin/domain_blocks HTTP/1.1

Add a domain to the list of domains blocked from federating.

Returns: 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 <user token> 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.

{
  "id": "1",
  "domain": "example.com",
  "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
  "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

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

422: Unprocessable entity - Missing Parameter

The domain parameter was not provided

{
  "error": "Validation failed: Domain can't be blank"
}

422: Unprocessable entity - Existing Domain Block

The domain parameter already is covered by an existing domain block.

{
  "error": "You have already imposed stricter limits on example.com."
  "existing_domain_block": {
    "id": "1",
    "domain": "example.com",
    "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
    "created_at": "2022-11-16T08:15:34.238Z",
    "severity": "noop",
    "reject_media": false,
    "reject_reports": false,
    "private_comment": null,
    "public_comment": null,
    "obfuscate": false
  }
}

---

Update a domain block {#update}

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

Change parameters for an existing domain block.

Returns: 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 <user token> 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

{
  "id": "1",
  "domain": "example.com",
  "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
  "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

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

500: Server error

Invalid severity

---

Remove a domain block {#delete}

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

Lift a block against a domain.

Returns: 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 <user token> to gain authorized access to this API method.

Response

200: OK

The domain 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

DomainBlock with the given ID does not exist

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