zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity
documentation/content/en/methods/filters.md

25 KiB
Raw Blame History

title description menu aliases
filters API methods Create and manage filters.
docs
weight name parent identifier
60 filters methods-accounts methods-filters
/methods/filters
/api/methods/filters
/methods/accounts/filters

Server-side (v2) methods

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

View all filters

GET /api/v2/filters HTTP/1.1

Obtain 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

Request

Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK
[
  {
    "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": []
  },
  // ...
]
401: Unauthorized

Invalid or missing Authorization header.

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

View a specific filter

GET /api/v2/filters/:id HTTP/1.1

Obtain 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

Request

Path parameters
:id
{{}} String. The ID of the Filter in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK
{
  "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": []
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Filter is not owned by you or does not exist

{
  "error": "Record not found"
}

Create a filter

POST /api/v2/filters HTTP/1.1

Create a filter group with the given parameters.

Returns: [Filter]({{< relref "entities/Filter" >}})
OAuth: User token + write:filters
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
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.

Response

200: OK

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": []
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Filter keyword ID was specified

{
  "error": "Record not found"
}
422: Unprocessable entity
{
  "error": "Validation failed: Title can't be blank, Context can't be blank, Context None or invalid context supplied"
}

Update a filter

PUT /api/v2/filters/:id HTTP/1.1

Update a filter group with the given parameters.

Returns: [Filter]({{< relref "entities/Filter" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added

Request

Path parameters
:id
{{}} String. The ID of the Filter in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
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.

Response

200: OK

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": []
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

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 a filter

DELETE /api/v2/filters/:id HTTP/1.1

Delete a filter group with the given id.

Returns: empty object
OAuth: User token + write:filters
Version history:
4.0.0 - added

Path parameters
:id
{{}} String. The ID of the Filter in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

Filter successfully deleted

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Filter is not owned by you or does not exist

{
  "error": "Record not found"
}

View keywords added to a filter

GET /api/v2/filters/:filter_id/keywords HTTP/1.1

List 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

Request

Path parameters
:filter_id
{{}} String. The ID of the Filter in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK
[
  {
    "id": "34979",
    "keyword": "baz",
    "whole_word": true
  },
  // ...
]
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Filter is not owned by you, or does not exist

{
  "error": "Record not found"
}

Add a keyword to a filter

POST /api/v2/filters/:filter_id/keywords HTTP/1.1

Add the given keyword to the specified filter group

Returns: [FilterKeyword]({{< relref "entities/FilterKeyword" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added

Request

Path parameters
:filter_id
{{}} String. The ID of the Filter in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
keyword
{{}} String. The keyword to be added to the filter group.
whole_word
Boolean. Whether the keyword should consider word boundaries.

Response

200: OK
{
  "id": "35583",
  "keyword": "some",
  "whole_word": false
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Filter is not owned by you, or does not exist

{
  "error": "Record not found"
}
422: Unprocessable entity

No keyword was provided

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

View a single keyword

GET /api/v2/filters/keywords/:id HTTP/1.1

Get one filter keyword by the given id.

Returns: [FilterKeyword]({{< relref "entities/FilterKeyword" >}})
OAuth: User token + read:filters
Version history:
4.0.0 - added

Request

Path parameters
:id
{{}} String. The ID of the FilterKeyword in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK
{
  "id": "34979",
  "keyword": "baz",
  "whole_word": true
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Filter is not owned by you, or the filter or filter keyword does not exist

{
  "error": "Record not found"
}

Edit a keyword within a filter

PUT /api/v2/filters/keywords/:id HTTP/1.1

Update the given filter keyword.

Returns: [FilterKeyword]({{< relref "entities/FilterKeyword" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added

Request

Path parameters
:id
{{}} String. The ID of the FilterKeyword in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
keyword
{{}} String. The keyword to be added to the filter group.
whole_word
Boolean. Whether the keyword should consider word boundaries.

Response

200: OK

The keyword "some" was updated to the keyword "other"

{
  "id": "35583",
  "keyword": "other",
  "whole_word": false
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

FilterKeyword is not owned by you, or does not exist

{
  "error": "Record not found"
}
422: Unprocessable entity

No keyword was provided

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

Remove keywords from a filter

DELETE /api/v2/filters/keywords/:id HTTP/1.1

Deletes the given filter keyword.

Returns: empty object
OAuth: User token + write:filters
Version history:
4.0.0 - added

Request

Path parameters
:id
{{}} String. The ID of the FilterKeyword in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

FilterKeyword was deleted successfully

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

FilterKeyword is not owned by you or does not exist

{
  "error": "Record not found"
}

View all status filters

GET /api/v2/filters/:filter_id/statuses HTTP/1.1

Obtain 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

Request

Path parameters
:filter_id
{{}} String. The ID of the Filter in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK
[
  {
    "id": "897",
    "status_id": "109416512469928632"
  },
  // ...
]
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Filter is not owned by you or does not exist

{
  "error": "Record not found"
}

Add a status to a filter group

POST /api/v2/filters/:filter_id/statuses HTTP/1.1

Add a status filter to the current filter group.

Returns: [FilterStatus]({{< relref "entities/FilterStatus" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added

Request

Path parameters
:filter_id
{{}} String. The ID of the Filter in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

FilterStatus created successfully within the current Filter

{
  "id": "897",
  "status_id": "109416512469928632"
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Filter is not owned by you or does not exist

{
  "error": "Record not found"
}

View a single status filter

GET /api/v2/filters/statuses/:id HTTP/1.1

Obtain a single status filter.

Returns: [FilterStatus]({{< relref "entities/FilterStatus" >}})
OAuth: User token + read:filters
Version history:
4.0.0 - added

Request

Path parameters
:id
{{}} String. The ID of the FilterStatus in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK
{
  "id": "897",
  "status_id": "109416512469928632"
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

FilterStatus is not owned by you or does not exist

{
  "error": "Record not found"
}

Remove a status from a filter group

DELETE /api/v2/filters/statuses/:id HTTP/1.1

Add a status filter to the current filter group.

Returns: [FilterStatus]({{< relref "entities/FilterStatus" >}})
OAuth: User token + write:filters
Version history:
4.0.0 - added

Request

Path parameters
:id
{{}} String. The ID of the FilterStatus in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

FilterStatus deleted successfully

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

FilterStatus is not owned by you or does not exist

{
  "error": "Record not found"
}

Client-side (v1) methods

Prior to Mastodon 3.6, matching filters was done client-size and filters could only contain one phrase to filter against.

View your filters

GET /api/v1/filters HTTP/1.1

Returns: 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)

Request

Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

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

View a single filter

GET /api/v1/filters/:id HTTP/1.1

Returns: [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)

Request

Path parameters
:id
{{}} String. The ID of the FilterKeyword in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK
{
  "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"
}

Create a filter

POST /api/v1/filters HTTP/1.1

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

Request

Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
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.

Response

200: OK

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

Update a filter

PUT /api/v1/filters/:id HTTP/1.1

Replaces 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.

Request

Path parameters
:id
{{}} String. The ID of the FilterKeyword in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
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.

Response

200: OK

Filter updated

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

Filter does not exist or is not owned by you

{
  "error": "Record not found"
}
422: Unprocessable entity

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

Remove a filter

DELETE /api/v1/filters/:id HTTP/1.1

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

Request

Path parameters
:id
{{}} String. The ID of the Filter in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

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

Filter does not exist or is not owned by you

{
  "error": "Record not found"
}

See also

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