From 8774c7f9f29015bfc07049780b0c8aa9b75a19a4 Mon Sep 17 00:00:00 2001
From: Eugen Rochko <eugen@zeonfederated.com>
Date: Fri, 5 Oct 2018 02:49:12 +0200
Subject: [PATCH] Add filters API

---
 content/en/api/guidelines.md   |  6 +++
 content/en/api/rest/filters.md | 72 +++++++++++++++++++++++++++++++++-
 2 files changed, 76 insertions(+), 2 deletions(-)

diff --git a/content/en/api/guidelines.md b/content/en/api/guidelines.md
index 735d039e..b9ef1ec2 100644
--- a/content/en/api/guidelines.md
+++ b/content/en/api/guidelines.md
@@ -44,3 +44,9 @@ Links in Mastodon are not shortened using URL shorteners. However, URLs in text
 ```
 
 The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long, otherwise it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup, instead, you are expected to insert it yourself if you need it in your app.
+
+## Filters
+
+Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for home and notifications context, but anything else is still up to the client to filter!
+
+Expired filters are not deleted by the server. They should no longer be applied but they are still stored by the server. It is up to clients to delete those filters eventually.
diff --git a/content/en/api/rest/filters.md b/content/en/api/rest/filters.md
index 96d83c40..dfbe9cc3 100644
--- a/content/en/api/rest/filters.md
+++ b/content/en/api/rest/filters.md
@@ -1,7 +1,75 @@
 ---
-title: Filters API
+title: Filters
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
+
+## GET /api/v1/filters
+
+Text filters the user has configured that potentially must be applied client-side.
+
+Returns array of [Filter]({{< relref "entities.md#filter" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="0.0.0" >}}
+
+## POST /api/v1/filters
+
+Create a new filter.
+
+Returns [Filter]({{< relref "entities.md#filter" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}
+
+### Parameters
+
+|Name|Description|Required|Default|
+|----|-----------|:------:|:-----:|
+| `phrase` | Keyword or phrase to filter | Required ||
+| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required ||
+| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional ||
+| `whole_word` | Whether to consider word boundaries when matching | Optional ||
+| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Null or blank string means "don't change" | Optional | Unlimited |
+
+## GET /api/v1/filters/:id
+
+A text filter.
+
+Returns [Filter]({{< relref "entities.md#filter" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="0.0.0" >}}
+
+## PUT /api/v1/filters/:id
+
+Update a text filter.
+
+Returns [Filter]({{< relref "entities.md#filter" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}
+
+### Parameters
+
+|Name|Description|Required|Default|
+|----|-----------|:------:|:-----:|
+| `phrase` | Keyword or phrase to filter | Required ||
+| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required ||
+| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional ||
+| `whole_word` | Whether to consider word boundaries when matching | Optional ||
+| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Null or blank string means "don't change" | Optional | Unlimited |
+
+## DELETE /api/v1/filters/:id
+
+Delete a text filter.
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}