filters

Create and manage filters.

View all filters

GET https://mastodon.example/api/v1/filters

Returns: Filter OAuth: User token + read:filters Version history: 2.4.3 - added

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Excerpts of various filters in different contexts.

[
  {
    "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 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

View a single filter

GET https://mastodon.example/api/v1/filters/:id

Returns: Filter OAuth: User token + read:filters Version history: 2.4.3 - added

Path Parameters

Name	Type	Description
:id	string

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Filter returned successfully

{
  "id": "8449",
  "phrase": "test",
  "context": [
    "home",
    "notifications",
    "public",
    "thread"
  ],
  "whole_word": false,
  "expires_at": "2019-11-26T09:08:06.254Z",
  "irreversible": true
}

401 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

404 Filter ID does not exist, or is not owned by you

{
  "error": "Record not found"
}

Create a filter

POST https://mastodon.example/api/v1/filters

Returns: Filter OAuth: User token + write:filters Version history: 2.4.3 - added

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

Name	Type	Description
phrase	string	Text to be filtered
context	array	Array of enumerable strings home, notifications, public, thread. At least one context must be specified.
irreversible	boolean	Should the server irreversibly drop matching entities from home and notifications?
whole_word	boolean	Consider word boundaries?
expires_in	string	ISO 8601 Datetime for when the filter expires. Otherwise, null for a filter that doesn't expire.

200 The newly-created filter will be returned.

{
  "id": "8449",
  "phrase": "test",
  "context": [
    "home",
    "notifications",
    "public",
    "thread"
  ],
  "whole_word": false,
  "expires_at": "2019-11-26T09:08:06.254Z",
  "irreversible": true
}

401 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

422 If phrase or context are not provided properly

phrase

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

context

{
  "error": "Validation failed: Context can't be blank, Context None or invalid context supplied"
}

Update a filter

PUT https://mastodon.example/api/v1/filters/:id

Returns: Filter OAuth: User token + write:filters Version history: 2.4.3 - added

Path Parameters

Name	Type	Description
id	string	ID of the filter in the database

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

Name	Type	Description
phrase	string	Text to be filtered
context	array	Array of enumerable strings home, notifications, public, thread. At least one context must be specified.
irreversible	boolean	Should the server irreversibly drop matching entities from home and notifications?
whole_word	boolean	Consider word boundaries?
expires_in	string	ISO 8601 Datetime for when the filter expires. Otherwise, null for a filter that doesn't expire.

200 Filter updated successfully

{
  "id": "8449",
  "phrase": "test",
  "context": [
    "home",
    "notifications",
    "public",
    "thread"
  ],
  "whole_word": false,
  "expires_at": null,
  "irreversible": true
}

401 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

404 The filter does not exist or is not owned by you

{
  "error": "Record not found"
}

422 If phrase or context are not provided properly

phrase

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

context

{
  "error": "Validation failed: Context can't be blank, Context None or invalid context supplied"
}

Remove a filter

DELETE https://mastodon.example/api/v1/filters/:id

Returns: Filter OAuth: User token + write:filters Version history: 2.4.3 - added

Path Parameters

Name	Type	Description
id	string	ID of the filter in the database

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 The filter has been deleted successfully, so an empty object will be returned.

{}

401 Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

404 The filter does not exist or is not owned by you

{
  "error": "Record not found"
}