| title | description | menu | aliases | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
filters API methods |
Create and manage filters. |
|
|
Since Mastodon 3.6, filters can contain multiple keywords and are matched server-side. Clients apply the filter action based on [the status's filtered attribute]({{< relref "entities/Status#filtered" >}}).
GET /api/v2/filters HTTP/1.1Obtain a list of all filter groups for the current user.
Returns: Array of [Filter]({{< relref "entities/Filter" >}})
OAuth: User token + read:filters
Version history:
4.0.0 - added
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
[
{
"id": "20060",
"title": "Remove Twitter crossposts from public timeline",
"context": [
"public"
],
"expires_at": null,
"filter_action": "hide",
"keywords": [
{
"id": "1311",
"keyword": "from birdsite",
"whole_word": true
},
{
"id": "1324",
"keyword": "@twitter.com",
"whole_word": false
},
{
"id": "1325",
"keyword": "https://t.co/",
"whole_word": false
}
],
"statuses": []
},
// ...
]Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}GET /api/v2/filters/:id HTTP/1.1Obtain a single filter group owned by the current user.
Returns: [Filter]({{< relref "entities/Filter" >}})
OAuth: User token + read:filters
Version history:
4.0.0 - added
:id : {{}} String. The ID of the Filter in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
{
"id": "20060",
"title": "Remove Twitter crossposts from public timeline",
"context": [
"public"
],
"expires_at": null,
"filter_action": "hide",
"keywords": [
{
"id": "1311",
"keyword": "from birdsite",
"whole_word": true
},
{
"id": "1324",
"keyword": "@twitter.com",
"whole_word": false
},
{
"id": "1325",
"keyword": "https://t.co/",
"whole_word": false
}
],
"statuses": []
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter is not owned by you or does not exist
{
"error": "Record not found"
}POST /api/v2/filters HTTP/1.1Create a filter group with the given parameters.
Returns: [Filter]({{< relref "entities/Filter" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
title : {{}} String. The name of the filter group.
context[]
: {{}} Array of String. Where the filter should be applied. Specify at least one of home, notifications, public, thread, account.
filter_action
: String. The policy to be applied when the filter is matched. Specify warn or hide.
expires_in : Integer. How many seconds from now should the filter expire?
keywords_attributes[][keyword] : String. A keyword to be added to the newly-created filter group.
keywords_attributes[][whole_word] : String. Whether the keyword should consider word boundaries.
Sample of a Filter created by the call:
POST https://mastodon.example/api/v2/filters
?title=test
&context[]=public
&keywords_attributes[][keyword]=foo
&keywords_attributes[][whole_word]=false
&keywords_attributes[][keyword]=bar
&keywords_attributes[][whole_word]=true
{
"id": "25933",
"title": "test",
"context": [
"public"
],
"expires_at": null,
"filter_action": "warn",
"keywords": [
{
"id": "34978",
"keyword": "foo",
"whole_word": false
},
{
"id": "34979",
"keyword": "bar",
"whole_word": true
}
],
"statuses": []
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter keyword ID was specified
{
"error": "Record not found"
}{
"error": "Validation failed: Title can't be blank, Context can't be blank, Context None or invalid context supplied"
}PUT /api/v2/filters/:id HTTP/1.1Update a filter group with the given parameters.
Returns: [Filter]({{< relref "entities/Filter" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added
:id : {{}} String. The ID of the Filter in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
title : String. The name of the filter group.
context[]
: Array of String. Where the filter should be applied. Specify at least one of home, notifications, public, thread, account.
filter_action
: String. The policy to be applied when the filter is matched. Specify warn or hide.
expires_in : Integer. How many seconds from now should the filter expire?
keywords_attributes[][keyword] : String. A keyword to be added to the newly-created filter group.
keywords_attributes[][whole_word] : String. Whether the keyword should consider word boundaries.
keywords_attributes[][id] : String. Provide the ID of an existing keyword to modify it, instead of creating a new keyword.
keywords_attributes[][_destroy] : Boolean. If true, will remove the keyword with the given ID.
Sample call:
PUT /api/v2/filters/25933
?keywords_attributes[][id]=34978
&keywords_attributes[][_destroy]=true
&keywords_attributes[][id]=34979
&keywords_attributes[][keyword]=baz
This will remove keyword 34978 ("foo") and will replace keyword 34979 ("bar") with a new keyword ("baz")
{
"id": "25933",
"title": "test",
"context": [
"public"
],
"expires_at": null,
"filter_action": "warn",
"keywords": [
{
"id": "34979",
"keyword": "baz",
"whole_word": true
}
],
"statuses": []
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter is not owned by you or does not exist. Alternatively, keywords_attributes[][id] was provided, there is no keyword with given id within this Filter.
{
"error": "Record not found"
}DELETE /api/v2/filters/:id HTTP/1.1Delete a filter group with the given id.
Returns: empty object
OAuth: User token + write:filters
Version history:
4.0.0 - added
:id : {{}} String. The ID of the Filter in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
Filter successfully deleted
{}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter is not owned by you or does not exist
{
"error": "Record not found"
}GET /api/v2/filters/:filter_id/keywords HTTP/1.1List all keywords attached to the current filter group.
Returns: Array of [FilterKeyword]({{< relref "entities/FilterKeyword" >}})
OAuth: User token + read:filters
Version history:
4.0.0 - added
:filter_id : {{}} String. The ID of the Filter in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
[
{
"id": "34979",
"keyword": "baz",
"whole_word": true
},
// ...
]Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter is not owned by you, or does not exist
{
"error": "Record not found"
}POST /api/v2/filters/:filter_id/keywords HTTP/1.1Add the given keyword to the specified filter group
Returns: [FilterKeyword]({{< relref "entities/FilterKeyword" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added
:filter_id : {{}} String. The ID of the Filter in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
keyword : {{}} String. The keyword to be added to the filter group.
whole_word : Boolean. Whether the keyword should consider word boundaries.
{
"id": "35583",
"keyword": "some",
"whole_word": false
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter is not owned by you, or does not exist
{
"error": "Record not found"
}No keyword was provided
{
"error": "Validation failed: Keyword can't be blank"
}GET /api/v2/filters/keywords/:id HTTP/1.1Get one filter keyword by the given id.
Returns: [FilterKeyword]({{< relref "entities/FilterKeyword" >}})
OAuth: User token + read:filters
Version history:
4.0.0 - added
:id : {{}} String. The ID of the FilterKeyword in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
{
"id": "34979",
"keyword": "baz",
"whole_word": true
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter is not owned by you, or the filter or filter keyword does not exist
{
"error": "Record not found"
}PUT /api/v2/filters/keywords/:id HTTP/1.1Update the given filter keyword.
Returns: [FilterKeyword]({{< relref "entities/FilterKeyword" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added
:id : {{}} String. The ID of the FilterKeyword in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
keyword : {{}} String. The keyword to be added to the filter group.
whole_word : Boolean. Whether the keyword should consider word boundaries.
The keyword "some" was updated to the keyword "other"
{
"id": "35583",
"keyword": "other",
"whole_word": false
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}FilterKeyword is not owned by you, or does not exist
{
"error": "Record not found"
}No keyword was provided
{
"error": "Validation failed: Keyword can't be blank"
}DELETE /api/v2/filters/keywords/:id HTTP/1.1Deletes the given filter keyword.
Returns: empty object
OAuth: User token + write:filters
Version history:
4.0.0 - added
:id : {{}} String. The ID of the FilterKeyword in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
FilterKeyword was deleted successfully
{}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}FilterKeyword is not owned by you or does not exist
{
"error": "Record not found"
}GET /api/v2/filters/:filter_id/statuses HTTP/1.1Obtain a list of all status filters within this filter group.
Returns: Array of [FilterStatus]({{< relref "entities/FilterStatus" >}})
OAuth: User token + read:filters
Version history:
4.0.0 - added
:filter_id : {{}} String. The ID of the Filter in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
[
{
"id": "897",
"status_id": "109416512469928632"
},
// ...
]Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter is not owned by you or does not exist
{
"error": "Record not found"
}POST /api/v2/filters/:filter_id/statuses HTTP/1.1Add a status filter to the current filter group.
Returns: [FilterStatus]({{< relref "entities/FilterStatus" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added
:filter_id : {{}} String. The ID of the Filter in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
FilterStatus created successfully within the current Filter
{
"id": "897",
"status_id": "109416512469928632"
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter is not owned by you or does not exist
{
"error": "Record not found"
}GET /api/v2/filters/statuses/:id HTTP/1.1Obtain a single status filter.
Returns: [FilterStatus]({{< relref "entities/FilterStatus" >}})
OAuth: User token + read:filters
Version history:
4.0.0 - added
:id : {{}} String. The ID of the FilterStatus in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
{
"id": "897",
"status_id": "109416512469928632"
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}FilterStatus is not owned by you or does not exist
{
"error": "Record not found"
}DELETE /api/v2/filters/statuses/:id HTTP/1.1Add a status filter to the current filter group.
Returns: [FilterStatus]({{< relref "entities/FilterStatus" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added
:id : {{}} String. The ID of the FilterStatus in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
FilterStatus deleted successfully
{}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}FilterStatus is not owned by you or does not exist
{
"error": "Record not found"
}Prior to Mastodon 3.6, matching filters was done client-size and filters could only contain one phrase to filter against.
GET /api/v1/filters HTTP/1.1Returns: List of [V1::Filter]({{< relref "entities/V1_Filter" >}})
OAuth: User token + read:filters
Version history:
2.4.3 - added
4.0.0 - deprecated. For compatibility purposes, now returns a List of V1::Filter, with each V1::Filter representing one FilterKeyword (with the keyword being presented in the phrase attribute)
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
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
},
// ...
]Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}GET /api/v1/filters/:id HTTP/1.1Returns: [V1::Filter]({{< relref "entities/V1_Filter" >}})
OAuth: User token + read:filters
Version history:
2.4.3 - added
4.0.0 - deprecated. For compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the keyword being presented in the phrase attribute)
:id : {{}} String. The ID of the FilterKeyword in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
{
"id": "8449",
"phrase": "test",
"context": [
"home",
"notifications",
"public",
"thread"
],
"whole_word": false,
"expires_at": "2019-11-26T09:08:06.254Z",
"irreversible": true
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter ID does not exist, or is not owned by you
{
"error": "Record not found"
}POST /api/v1/filters HTTP/1.1Returns: [V1::Filter]({{< relref "entities/V1_Filter" >}})
OAuth: User token + write:filters
Version history:
2.4.3 - added
3.1.0 - added account context to filter in profile views
4.0.0 - deprecated. For compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the keyword being presented in the phrase attribute). This method will create a Filter that contains only one FilterKeyword. The title of the Filter and the keyword of the FilterKeyword will be set equal to the phrase provided.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
phrase : {{}} String. The text to be filtered.
context[]
: {{}} Array of String. Where the filter should be applied. Specify at least one of home, notifications, public, thread, account.
irreversible : Boolean. Should the server irreversibly drop matching entities from home and notifications? Defaults to false.
whole_word : Boolean. Should the filter consider word boundaries for this keyword? Defaults to false.
expires_in
: Integer. Number of seconds from now that the filter should expire. Otherwise, null for a filter that doesn't expire.
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
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}If phrase is not provided properly:
{
"error": "Validation failed: Phrase can't be blank"
}If context is not provided properly:
{
"error": "Validation failed: Context can't be blank, Context None or invalid context supplied"
}PUT /api/v1/filters/:id HTTP/1.1Replaces a filter's parameters in-place.
Returns: [V1::Filter]({{< relref "entities/V1_Filter" >}})
OAuth: User token + write:filters
Version history:
2.4.3 - added
3.1.0 - added account context to filter in profile views
4.0.0 - deprecated. or compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the keyword being presented in the phrase attribute). This method will return an error if you attempt to change expires_in, irreversible, or context for a filter with multiple keywords. Changing phrase and whole_word is always safe.
:id : {{}} String. The ID of the FilterKeyword in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
phrase : {{}} String. The text to be filtered.
context[]
: {{}} Array of String. Specify at least one of home, notifications, public, thread, account.
irreversible : Boolean. Should the server irreversibly drop matching entities from home and notifications? Defaults to false.
whole_word : Boolean. Should the filter consider word boundaries? Defaults to false.
expires_in
: Integer. Number of seconds from now that the filter should expire. Otherwise, null for a filter that doesn't expire.
Filter updated
{
"id": "8449",
"phrase": "test",
"context": [
"home",
"notifications",
"public",
"thread"
],
"whole_word": false,
"expires_at": null,
"irreversible": true
}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter does not exist or is not owned by you
{
"error": "Record not found"
}If phrase is not provided properly:
{
"error": "Validation failed: Phrase can't be blank"
}If context is not provided properly:
{
"error": "Validation failed: Context can't be blank, Context None or invalid context supplied"
}DELETE /api/v1/filters/:id HTTP/1.1Returns: empty object
OAuth: User token + write:filters
Version history:
2.4.3 - added
4.0.0 - deprecated. This method will delete only the FilterKeyword from its parent Filter. To delete the parent Filter, you must use the v2 filters API.
:id : {{}} String. The ID of the Filter in the database.
Authorization
: {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
The filter has been deleted successfully, so an empty object will be returned.
{}Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}Filter does not exist or is not owned by you
{
"error": "Record not found"
}{{< page-relref ref="api/guidelines#filters" caption="Implementation guidelines for filters" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/filters_controller.rb" caption="app/controllers/api/v2/filters_controller.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters/keywords_controller.rb" caption="app/controllers/api/v1/filters/keywords_controller.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters/statuses_controller.rb" caption="app/controllers/api/v1/filters/statuses_controller.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/filters_controller.rb" caption="app/controllers/api/v1/filters_controller.rb" >}}