filters

Create and manage filters.

get
View all filters

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

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

Request

Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

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: Unauthorized

Invalid or missing Authorization header 

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

get
View a single filter

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

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

Request

Path Parameters
:id
required
string
Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

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: Unauthorized

Invalid or missing Authorization header 

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

404: Not Found

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

{
  "error": "Record not found"
}

post
Create a filter

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

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

Request

Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
phrase
required
string
Text to be filtered
context
required
array
Array of enumerable strings home, notifications, public, thread. At least one context must be specified.
irreversible
optional
boolean
Should the server irreversibly drop matching entities from home and notifications?
whole_word
optional
boolean
Consider word boundaries?
expires_in
optional
integer
Number of seconds from now the filter should expire. Otherwise, null for a filter that doesn’t expire.

Response

200: Success

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: Unauthorized

Invalid or missing Authorization header 

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

422: Unprocessable Entity

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

put
Update a filter

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

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

Request

Path Parameters
id
required
string
ID of the filter in the database
Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
phrase
required
string
Text to be filtered
context
required
array
Array of enumerable strings home, notifications, public, thread. At least one context must be specified.
irreversible
optional
boolean
Should the server irreversibly drop matching entities from home and notifications?
whole_word
optional
boolean
Consider word boundaries?
expires_in
optional
integer
Number of seconds from now the filter should expire. Otherwise, null for a filter that doesn’t expire.

Response

200: Success

Filter updated successfully 

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

401: Unauthorized

Invalid or missing Authorization header 

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

404: Not Found

The filter does not exist or is not owned by you 

{
  "error": "Record not found"
}

422: Unprocessable Entity

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

delete
Remove a filter

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

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

Request

Path Parameters
id
required
string
ID of the filter in the database
Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

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

{}

401: Unauthorized

Invalid or missing Authorization header 

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

404: Not Found

The filter does not exist or is not owned by you 

{
  "error": "Record not found"
}

Last updated December 27, 2020 · Improve this page