diff --git a/README.md b/README.md
index b36465f..852c6c4 100644
--- a/README.md
+++ b/README.md
@@ -53,20 +53,14 @@ Getting closer to a stable release, it should be the "last" migration.
    - Manually tested against [Mastodon](https://github.com/tootsuite/mastodon) and other platforms
 
 
-## ActivityPub
-
-_microblog.pub_ implements an [ActivityPub](http://activitypub.rocks/) server, it implements both the client to server API and the federated server to server API.
-
-Activities are verified using HTTP Signatures or by fetching the content on the remote server directly.
-
 ## User Guide
 
 The easiest and recommended way to run _microblog.pub_ in production is to use the provided docker-compose config.
 
 First install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/).
-It's the only requirements, Python is not needed on the host system.
+Python is not needed on the host system.
 
-Note that all the generated data (config included) will be stored on the host (i.e. not in Docker) in `config/` and `data/`.
+Note that all the generated data (config included) will be stored on the host (i.e. not only in Docker) in `config/` and `data/`.
 
 
 ### Installation
@@ -85,6 +79,10 @@ To spawn the docker-compose project (running this command will also update _micr
 $ make run
 ```
 
+### HTTP API
+
+See [docs/api.md](docs/api.md) for the internal HTTP API documentation.
+
 ### Backup
 
 The easiest way to backup all of your data is to backup the `microblog.pub/` directory directly (that's what I do and I have been able to restore super easily).
@@ -106,221 +104,6 @@ $ env POUSSETACHES_AUTH_KEY="<secret-key>" docker-compose -f docker-compose-dev.
 $ FLASK_DEBUG=1 MICROBLOGPUB_DEBUG=1 FLASK_APP=app.py POUSSETACHES_AUTH_KEY="<secret-key>" flask run -p 5005 --with-threads
 ```
 
-## API
-
-Your admin API key can be found at `config/admin_api_key.key`.
-
-## ActivityPub API
-
-### GET /
-
-Returns the actor profile, with links to all the "standard" collections.
-
-### GET /tags/:tag
-
-Special collection that reference notes with the given tag.
-
-### GET /stream
-
-Special collection that returns the stream/inbox as displayed in the UI.
-
-## User API
-
-The user API is used by the admin UI (and requires a CSRF token when used with a regular user session), but it can also be accessed with an API key.
-
-All the examples are using [HTTPie](https://httpie.org/).
-
-### POST /api/note/delete{?id}
-
-Deletes the given note `id` (the note must from the instance outbox).
-
-Answers a **201** (Created) status code.
-
-You can pass the `id` via JSON, form data or query argument.
-
-#### Example
-
-```shell
-$ http POST https://microblog.pub/api/note/delete Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
-```
-
-#### Response
-
-```json
-{
-    "activity": "https://microblog.pub/outbox/<delete_id>"
-}
-```
-
-### POST /api/note/pin{?id}
-
-Adds the given note `id` (the note must from the instance outbox) to the featured collection (and pins it on the homepage).
-
-Answers a **201** (Created) status code.
-
-You can pass the `id` via JSON, form data or query argument.
-
-#### Example
-
-```shell
-$ http POST https://microblog.pub/api/note/pin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
-```
-
-#### Response
-
-```json
-{
-    "pinned": true
-}
-```
-
-### POST /api/note/unpin{?id}
-
-Removes the given note `id` (the note must from the instance outbox) from the featured collection (and un-pins it).
-
-Answers a **201** (Created) status code.
-
-You can pass the `id` via JSON, form data or query argument.
-
-#### Example
-
-```shell
-$ http POST https://microblog.pub/api/note/unpin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
-```
-
-#### Response
-
-```json
-{
-    "pinned": false
-}
-```
-
-### POST /api/like{?id}
-
-Likes the given activity.
-
-Answers a **201** (Created) status code.
-
-You can pass the `id` via JSON, form data or query argument.
-
-#### Example
-
-```shell
-$ http POST https://microblog.pub/api/like Authorization:'Bearer <token>' id=http://activity-iri.tld
-```
-
-#### Response
-
-```json
-{
-    "activity": "https://microblog.pub/outbox/<like_id>"
-}
-```
-
-### POST /api/boost{?id}
-
-Boosts/Announces the given activity.
-
-Answers a **201** (Created) status code.
-
-You can pass the `id` via JSON, form data or query argument.
-
-#### Example
-
-```shell
-$ http POST https://microblog.pub/api/boost Authorization:'Bearer <token>' id=http://activity-iri.tld
-```
-
-#### Response
-
-```json
-{
-    "activity": "https://microblog.pub/outbox/<announce_id>"
-}
-```
-
-### POST /api/block{?actor}
-
-Blocks the given actor, all activities from this actor will be dropped after that.
-
-Answers a **201** (Created) status code.
-
-You can pass the `id` via JSON, form data or query argument.
-
-#### Example
-
-```shell
-$ http POST https://microblog.pub/api/block Authorization:'Bearer <token>' actor=http://actor-iri.tld/
-```
-
-#### Response
-
-```json
-{
-    "activity": "https://microblog.pub/outbox/<block_id>"
-}
-```
-
-### POST /api/follow{?actor}
-
-Follows the given actor.
-
-Answers a **201** (Created) status code.
-
-You can pass the `id` via JSON, form data or query argument.
-
-#### Example
-
-```shell
-$ http POST https://microblog.pub/api/follow Authorization:'Bearer <token>' actor=http://actor-iri.tld/
-```
-
-#### Response
-
-```json
-{
-    "activity": "https://microblog.pub/outbox/<follow_id>"
-}
-```
-
-### POST /api/new_note{?content,reply}
-
-Creates a new note. `reply` is the IRI of the "replied" note if any.
-
-Answers a **201** (Created) status code.
-
-You can pass the `content` and `reply` via JSON, form data or query argument.
-
-#### Example
-
-```shell
-$ http POST https://microblog.pub/api/new_note Authorization:'Bearer <token>' content=hello
-```
-
-#### Response
-
-```json
-{
-    "activity": "https://microblog.pub/outbox/<create_id>"
-}
-```
-
-
-### GET /api/stream
-
-
-#### Example
-
-```shell
-$ http GET https://microblog.pub/api/stream Authorization:'Bearer <token>'
-```
-
-#### Response
-
-```json
-```
-
 
 ## Contributions
 
diff --git a/docs/activitypub.md b/docs/activitypub.md
new file mode 100644
index 0000000..2ca78d9
--- /dev/null
+++ b/docs/activitypub.md
@@ -0,0 +1,9 @@
+## ActivityPub
+
+_microblog.pub_ implements an [ActivityPub](http://activitypub.rocks/) server, it implements both the client to server API and the federated server to server API.
+
+Activities are verified using HTTP Signatures or by fetching the content on the remote server directly.
+
+WebFinger is also required.
+
+TODO
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..90e2321
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,216 @@
+## API
+
+Your admin API key can be found at `config/admin_api_key.key`.
+
+## ActivityPub API
+
+### GET /
+
+Returns the actor profile, with links to all the "standard" collections.
+
+### GET /tags/:tag
+
+Special collection that reference notes with the given tag.
+
+### GET /stream
+
+Special collection that returns the stream/inbox as displayed in the UI.
+
+## User API
+
+The user API is used by the admin UI (and requires a CSRF token when used with a regular user session), but it can also be accessed with an API key.
+
+All the examples are using [HTTPie](https://httpie.org/).
+
+### POST /api/note/delete{?id}
+
+Deletes the given note `id` (the note must from the instance outbox).
+
+Answers a **201** (Created) status code.
+
+You can pass the `id` via JSON, form data or query argument.
+
+#### Example
+
+```shell
+$ http POST https://microblog.pub/api/note/delete Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
+```
+
+#### Response
+
+```json
+{
+    "activity": "https://microblog.pub/outbox/<delete_id>"
+}
+```
+
+### POST /api/note/pin{?id}
+
+Adds the given note `id` (the note must from the instance outbox) to the featured collection (and pins it on the homepage).
+
+Answers a **201** (Created) status code.
+
+You can pass the `id` via JSON, form data or query argument.
+
+#### Example
+
+```shell
+$ http POST https://microblog.pub/api/note/pin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
+```
+
+#### Response
+
+```json
+{
+    "pinned": true
+}
+```
+
+### POST /api/note/unpin{?id}
+
+Removes the given note `id` (the note must from the instance outbox) from the featured collection (and un-pins it).
+
+Answers a **201** (Created) status code.
+
+You can pass the `id` via JSON, form data or query argument.
+
+#### Example
+
+```shell
+$ http POST https://microblog.pub/api/note/unpin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
+```
+
+#### Response
+
+```json
+{
+    "pinned": false
+}
+```
+
+### POST /api/like{?id}
+
+Likes the given activity.
+
+Answers a **201** (Created) status code.
+
+You can pass the `id` via JSON, form data or query argument.
+
+#### Example
+
+```shell
+$ http POST https://microblog.pub/api/like Authorization:'Bearer <token>' id=http://activity-iri.tld
+```
+
+#### Response
+
+```json
+{
+    "activity": "https://microblog.pub/outbox/<like_id>"
+}
+```
+
+### POST /api/boost{?id}
+
+Boosts/Announces the given activity.
+
+Answers a **201** (Created) status code.
+
+You can pass the `id` via JSON, form data or query argument.
+
+#### Example
+
+```shell
+$ http POST https://microblog.pub/api/boost Authorization:'Bearer <token>' id=http://activity-iri.tld
+```
+
+#### Response
+
+```json
+{
+    "activity": "https://microblog.pub/outbox/<announce_id>"
+}
+```
+
+### POST /api/block{?actor}
+
+Blocks the given actor, all activities from this actor will be dropped after that.
+
+Answers a **201** (Created) status code.
+
+You can pass the `id` via JSON, form data or query argument.
+
+#### Example
+
+```shell
+$ http POST https://microblog.pub/api/block Authorization:'Bearer <token>' actor=http://actor-iri.tld/
+```
+
+#### Response
+
+```json
+{
+    "activity": "https://microblog.pub/outbox/<block_id>"
+}
+```
+
+### POST /api/follow{?actor}
+
+Follows the given actor.
+
+Answers a **201** (Created) status code.
+
+You can pass the `id` via JSON, form data or query argument.
+
+#### Example
+
+```shell
+$ http POST https://microblog.pub/api/follow Authorization:'Bearer <token>' actor=http://actor-iri.tld/
+```
+
+#### Response
+
+```json
+{
+    "activity": "https://microblog.pub/outbox/<follow_id>"
+}
+```
+
+### POST /api/new_note{?content,reply}
+
+Creates a new note. `reply` is the IRI of the "replied" note if any.
+
+Answers a **201** (Created) status code.
+
+You can pass the `content` and `reply` via JSON, form data or query argument.
+
+#### Example
+
+```shell
+$ http POST https://microblog.pub/api/new_note Authorization:'Bearer <token>' content=hello
+```
+
+#### Response
+
+```json
+{
+    "activity": "https://microblog.pub/outbox/<create_id>"
+}
+```
+
+
+### GET /api/stream
+
+
+#### Example
+
+```shell
+$ http GET https://microblog.pub/api/stream Authorization:'Bearer <token>'
+```
+
+#### Response
+
+```json
+```
+
+