diff --git a/doc/api.md b/doc/api.md
new file mode 100644
index 00000000..4cf82f0a
--- /dev/null
+++ b/doc/api.md
@@ -0,0 +1,306 @@
+# aurweb v6 /api
+
+Specification for version 6 of the metadata REST-API
+
+## Endpoints
+
+Endpoints are classified in 3 categories:
+
+* Search -> Search for packages
+* Info -> Lookup information for package (exact keyword)
+* Suggest -> Search for package names (max. 20 results)
+
+### Search
+
+Performs a search query according to the `by` parameter.
+
+* <mark>GET</mark>`/api/v6/search/{arg}`
+  <mark>GET</mark>`/api/v6/search/{by}/{arg}`
+  <mark>GET</mark>`/api/v6/search/{by}/{mode}/{arg}`
+    * `arg` <sub>(path; mandatory)</sub>
+    * `by` <sub>(path; optional)</sub>
+    * `mode` <sub>(path; optional)</sub>
+
+#### Parameters
+
+* `by`
+
+    The field that is utilized in the search query
+    If not specified, searching is performend with ***name-desc***
+    * Type: `string`
+    * Allowed values
+        * `name`
+        * `name-desc`
+    * Default: `name-desc`
+
+* `mode`
+
+    The search-mode that is being used to query packages
+    If not specified, searching is performend with ***contains***
+    * Type: `string`
+    * Allowed values
+        * `contains`
+        * `starts-with`
+    * Default: `contains`
+
+* `arg`
+
+    The argument/search-term(s) for the search query
+    Multiple terms/words can be supplied (space separated)
+    to perform and *AND*-like query
+
+    * Type: `string`
+
+#### Response
+
+Data is returned in JSON format.
+Empty fields are ommitted in the output.
+
+`200 - OK`
+
+* PackageData
+
+    ```json
+    {
+        "resultcount": 1,
+        "results": [
+            {
+                "Name": "my-pkg",
+                "Description": "Package description",
+                "Version": "1.7.5-1",
+                "PackageBase": "my-pkg",
+                "URL": "https://example.com",
+                "URLPath": "/cgit/aur.git/snapshot/my-pkg.tar.gz",
+                "Maintainer": "someone",
+                "Submitter": "someone",
+                "FirstSubmitted": 1648375227,
+                "LastModified": 1666386881,
+                "OutOfDate": 1648375227,
+                "NumVotes": 10,
+                "Popularity": 6.463867,
+                "License": [
+                    "MIT",
+                    "GPL3"
+                ],
+                "Depends": [
+                    "some-pkg",
+                    "another-pkg"
+                ],
+                "MakeDepends": [
+                    "some-pkg",
+                    "another-pkg"
+                ],
+                "OptDepends": [
+                    "some-pkg",
+                    "another-pkg"
+                ],
+                "CheckDepends": [
+                    "some-pkg",
+                    "another-pkg"
+                ],
+                "Provides": [
+                    "some-pkg",
+                    "another-pkg"
+                ],
+                "Conflicts": [
+                    "some-pkg",
+                    "another-pkg"
+                ],
+                "Replaces": [
+                    "some-pkg",
+                    "another-pkg"
+                ],
+                "Groups": [
+                    "some-grp",
+                    "another-grp"
+                ],
+                "Keywords": [
+                    "some-keyword",
+                    "another-keyword"
+                ],
+                "CoMaintainers": [
+                    "someone",
+                    "another-one"
+                ]
+            }
+        ],
+        "type": "search",
+        "version": 6
+    }
+    ```
+
+`400 - Bad Request`
+
+* Error
+
+    ```json
+    {
+        "error": "Incorrect by field specified",
+        "resultcount": 1,
+        "results": [],
+        "type": "error",
+        "version": 6
+    }
+    ```
+
+### Info
+
+Returns a list of detailed package data for one or more packages
+
+#### Single lookup
+* <mark>GET</mark>`/api/v6/info/{arg}`
+  <mark>GET</mark>`/api/v6/info/{by}/{arg}`
+    * `arg` <sub>(path; mandatory)</sub>
+    * `by` <sub>(path; optional)</sub>
+
+#### Multi lookup
+* <mark>GET</mark>`/api/v6/info?arg=xyz&arg=abc`
+  <mark>GET</mark>`/api/v6/info?by=provides&arg=xyz&arg=abc`
+    * `arg` <sub>(query-string; mandatory; one or more)</sub>
+    * `by` <sub>(query-string; optional)</sub>
+
+* <mark>POST</mark>`/api/v6/info`
+     * BODY (`application/x-www-form-urlencoded`):
+        ```xml
+        arg=one&arg=two&by=provides
+        ```
+
+#### Parameters
+
+* `by`
+
+    The field is being utilized in the lookup query
+    If not specified, a lookup is performend with ***name***
+    * Type: `string`
+    * Allowed values
+        * `name`
+        * `depends`
+        * `checkdepends`
+        * `optdepends`
+        * `makedepends`
+        * `maintainer`
+        * `submitter`
+        * `provides`
+        * `conflicts`
+        * `replaces`
+        * `keywords`
+        * `groups`
+        * `comaintainers`
+    * Default: `name`
+
+* `arg`
+
+    One or more keywords
+
+    * Type: `string` or `string-array` (depending on the endpoint)
+
+#### Response
+
+Data is returned in JSON format.
+Empty fields are ommitted in the output.
+
+`200 - OK`
+
+* PackageData
+
+    See `Search` type
+
+`400 - Bad Request`
+
+* Error
+
+    See `Search` type
+
+### Suggest
+
+Returns a list of package names starting with the supplied argument.
+Mostly used for auto-completion fields when typing.
+
+#### Starts-with search
+
+* <mark>GET</mark>`/api/v6/suggest/{arg}`
+    * `arg` <sub>(path; mandatory)</sub>
+
+* <mark>GET</mark>`/api/v6/suggest-pkgbase/{arg}`
+    * `arg` <sub>(path; mandatory)</sub>
+
+
+#### Response
+
+Data is returned in JSON format.
+
+`200 - OK`
+
+* PackageNames
+
+    ```json
+    [
+        "pkg1",
+        "pkg2",
+        "pkg3",
+    ]
+    ```
+
+#### Parameters
+
+* `arg`
+
+    Search term (starts-with)
+
+    * Type: `string`
+
+## Examples
+
+Below you'll find some basic examples for the different types of requests.
+
+### Search
+
+* packages containing `firefox` in the package name or description
+
+    <mark>GET</mark>`/api/v6/search/firefox`
+    <mark>GET</mark>`/api/v6/search/name-desc/firefox`
+    <mark>GET</mark>`/api/v6/search/name-desc/contains/firefox`
+
+* packages whose name start with `firefox`
+
+    <mark>GET</mark>`/api/v6/search/name/starts-with/firefox`
+
+* packages containing both `fire` and `fox` in the name
+
+    <mark>GET</mark>`/api/v6/search/name/fire+fox`
+    (note that `+` is a URL-encoded whitespace character)
+
+### Info
+
+* a package with the name `firefox`
+
+    <mark>GET</mark>`/api/v6/info/firefox`
+
+* packages providing `firefox`
+
+    <mark>GET</mark>`/api/v6/info/provides/firefox`
+    <mark>GET</mark>`/api/v6/info?by=provides&arg=firefox`
+
+* packages co-maintained by `someuser`
+
+    <mark>GET</mark>`/api/v6/info/comaintainers/someuser`
+    <mark>GET</mark>`/api/v6/info?by=comaintainers&arg=someuser`
+
+* packages with name `firefox` or `chromium`
+
+    <mark>GET</mark>`/api/v6/info?by=name&arg=firefox&arg=chromium`
+
+    <mark>POST</mark>`/api/v6/info`
+    ```
+    arg=firefox&arg=chromium&by=name
+    ```
+
+### Suggest
+
+* packages starting with `fire`
+
+    <mark>GET</mark>`/api/v6/suggest/fire`
+
+* packages whose pkgbase starts with `fire`
+
+    <mark>GET</mark>`/api/v6/suggest-pkgbase/fire`