540 lines
11 KiB
Markdown
540 lines
11 KiB
Markdown
---
|
|
title: filters API methods
|
|
description: Create and manage filters.
|
|
menu:
|
|
docs:
|
|
weight: 60
|
|
name: filters
|
|
parent: methods-accounts
|
|
identifier: methods-filters
|
|
aliases: [
|
|
"/methods/filters",
|
|
"/api/methods/filters",
|
|
"/methods/accounts/filters",
|
|
]
|
|
---
|
|
|
|
{{<hint style="warning">}}
|
|
This page is under construction.
|
|
{{</hint>}}
|
|
|
|
## Server-side (v2) methods {#v2}
|
|
|
|
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}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
GET https://mastodon.example/api/v2/filters HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### View a specific filter {#get-one}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
GET https://mastodon.example/api/v2/filters/:id HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### Create a filter {#create}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
POST https://mastodon.example/api/v2/filters HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### Update a filter {#update}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
PUT https://mastodon.example/api/v2/filters/:id HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### Delete a filter {#delete}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
DELETE https://mastodon.example/api/v2/filters/:id HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### View keywords added to a filter {#keywords-get}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
GET https://mastodon.example/api/v2/filters/:id/keywords HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### View a single keyword within a filter {#keywords-get-one}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
GET https://mastodon.example/api/v2/filters/:filter_id/keywords/:id HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### Add a keyword to a filter {#keywords-create}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
POST https://mastodon.example/api/v2/filters/:filter_id/keywords HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### Edit a keyword within a filter {#keywords-update}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
PUT https://mastodon.example/api/v2/filters/keywords/:id HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
### Remove keywords from a filter {#keywords-get}
|
|
|
|
<!--
|
|
TODO:
|
|
-->
|
|
|
|
```http
|
|
DELETE https://mastodon.example/api/v2/filters/keywords/:id HTTP/1.1
|
|
```
|
|
|
|
---
|
|
|
|
## Client-side (v1) methods {#v1}
|
|
|
|
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-v1}
|
|
|
|
```http
|
|
GET https://mastodon.example/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
|
|
: {{<required>}} 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.
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### View a single filter {#get-one-v1}
|
|
|
|
```http
|
|
GET https://mastodon.example/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
|
|
: {{<required>}} String. The ID of the FilterKeyword in the database.
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
#### Response
|
|
##### 200: OK
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
##### 404: Not found
|
|
|
|
Filter ID does not exist, or is not owned by you
|
|
|
|
```json
|
|
{
|
|
"error": "Record not found"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Create a filter {#create-v1}
|
|
|
|
```http
|
|
POST https://mastodon.example/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
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
##### Form data parameters
|
|
|
|
phrase
|
|
: {{<required>}} String. The text to be filtered.
|
|
|
|
context[]
|
|
: {{<required>}} 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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
##### 422: Unprocessable entity
|
|
|
|
If phrase is not provided properly:
|
|
|
|
```json
|
|
{
|
|
"error": "Validation failed: Phrase can't be blank"
|
|
}
|
|
```
|
|
|
|
If context is not provided properly:
|
|
|
|
```json
|
|
{
|
|
"error": "Validation failed: Context can't be blank, Context None or invalid context supplied"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Update a filter {#update-v1}
|
|
|
|
```http
|
|
PUT https://mastodon.example/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
|
|
: {{<required>}} String. The ID of the FilterKeyword in the database.
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
##### Form data parameters
|
|
|
|
phrase
|
|
: {{<required>}} String. The text to be filtered.
|
|
|
|
context[]
|
|
: {{<required>}} 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
|
|
|
|
```json
|
|
{
|
|
"id": "8449",
|
|
"phrase": "test",
|
|
"context": [
|
|
"home",
|
|
"notifications",
|
|
"public",
|
|
"thread"
|
|
],
|
|
"whole_word": false,
|
|
"expires_at": null,
|
|
"irreversible": true
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
##### 404: Not found
|
|
|
|
Filter does not exist or is not owned by you
|
|
|
|
```json
|
|
{
|
|
"error": "Record not found"
|
|
}
|
|
```
|
|
|
|
##### 422: Unprocessable entity
|
|
|
|
If phrase is not provided properly:
|
|
|
|
```json
|
|
{
|
|
"error": "Validation failed: Phrase can't be blank"
|
|
}
|
|
```
|
|
|
|
If context is not provided properly:
|
|
|
|
```json
|
|
{
|
|
"error": "Validation failed: Context can't be blank, Context None or invalid context supplied"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Remove a filter {#delete-v1}
|
|
|
|
```http
|
|
DELETE https://mastodon.example/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
|
|
: {{<required>}} String. The ID of the SOMETHING in the database.
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} 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.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
##### 404: Not found
|
|
|
|
Filter does not exist or is not owned by you
|
|
|
|
```json
|
|
{
|
|
"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" >}} |