Add lists.sr.ht API docs

1 files changed, 329 insertions, 0 deletions

diff --git a/lists.sr.ht/api.md b/lists.sr.ht/api.md
new file mode 100644
index 0000000..11b8d47
--- /dev/null
+++ b/lists.sr.ht/api.md
@@ -0,0 +1,329 @@
+# API Reference
+
+The lists.sr.ht API allows you to browse, create, and subscribe to mailing lists
+on lists.sr.ht programmatically. This API follows the [standard sourcehut API
+conventions](../api-conventions.md).
+
+## Authentication
+
+Authentication is done via the [meta.sr.ht OAuth
+flow](https://man.sr.ht/meta.sr.ht/oauth-api.md). The following OAuth scopes are
+available for lists.sr.ht:
+
+- **emails:read**: read emails received from lists.sr.ht users
+- **lists:read**, **list:write**: read & write your mailing lists
+- **subs:read**, **subs:write**: read & write your subscriptions
+
+## Resources
+
+### Email resource
+
+```json
+{
+  "id": integer,
+  "created": "timestamp",
+  "subject": "message subject",
+  "message_id": "value of the Message-ID header",
+  "parent_id": integer or null,
+  "thread_id": integer,
+  "list": { short form list resource },
+  "sender": { short form user resource } or null,
+  "is_patch": boolean,
+  "is_request_pull": boolean,
+  "replies": integer,
+  "participants": integer,
+  "envelope": "original email"
+}
+```
+
+**Notes**
+
+- The short form omits `is_patch`, `is_request_pull`, `replies`, `participants`,
+  and `envelope`.
+- The sender is null of the sender's email address could not be associated with
+  a sr.ht account.
+
+### Mailing list resource
+
+```json
+{
+  "created": "timestamp",
+  "updated": "timestamp",
+  "name": "name of this list",
+  "owner": { short form user resource },
+  "description": "list description (markdown)",
+  "permissions": {
+    "nonsubscriber": "list,of,permissions",
+    "subscriber": "list,of,permissions",
+    "account": "list,of,permissions"
+  }
+}
+```
+
+**Notes**
+
+- The permissions which may appear in each `permissions` field are browse,
+  reply, and post.
+- The short form omits everything except for name and owner.
+
+### Subscription resource
+
+```json
+{
+  "id": integer,
+  "created": "timestamp",
+  "list": { short form list resource }
+}
+```
+
+## Endpoints
+
+**Note**: in all routes, `:username` may be substituted with an email address,
+and `:email-id` may be the email's either of the "id" or "message_id" values.
+
+### GET /api/:username
+
+Retrieves a user resource.
+
+### GET /api/user
+
+Equivalent to [/api/:username](#GET-apiusername), implies the authenticated
+user.
+
+### GET /api/user/:username/emails
+
+List of [email resources](#email-resource) received from this user.
+
+**OAuth scope**: `emails:read`
+
+### GET /api/user/emails
+
+Equivalent to [/api/:username/emails](#GET-apiusernameemails), implies the
+authenticated user.
+
+**OAuth scope**: `emails:read`
+
+### GET /api/emails/:email-id
+
+Retrieves an [email resource](#email-resource).
+
+**OAuth scope**: `emails:read`
+
+### GET /api/user/:username/emails/:email-id
+
+Equivalent to [GET /api/emails/:email-id](#GET-apiemailsemail-id); `username` is
+discarded.
+
+**OAuth scope**: `emails:read`
+
+### GET /api/thread/:email-id
+
+Retrieves an array of each email implicated in the thread identified by its
+first message's `:email-id`.
+
+**OAuth scope**: `emails:read`
+
+**Response**
+
+```json
+[
+  { short form email resource },
+  ...
+]
+```
+
+### GET /api/user/:username/thread/:email-id
+
+Equivalent to [GET /api/thread/:email-id](#GET-apithreademail-id); `username` is
+discarded.
+
+**OAuth scope**: `emails:read`
+
+### GET /api/user/:username/lists
+
+List of [mailing list resources](#mailing-list-resource) owned by this user.
+
+**OAuth scope**: `lists:read`
+
+### GET /api/lists
+
+Equivalent to [/api/:username/lists](#GET-apiusernamelists), implies the
+authenticated user.
+
+**OAuth scope**: `lists:read`
+
+### POST /api/lists
+
+Creates a new [mailing list resource](#mailing-list-resource).
+
+**OAuth scope**: `lists:write`
+
+**Request body**
+
+```json
+{
+  "name": "mailing list name",
+  "description": "mailing list description (markdown)" (optional)
+}
+```
+
+**Response**
+
+The new [mailing list resource](#mailing-list-resource).
+
+### GET /api/user/:username/lists/:list-name
+
+Retrieves a [mailing list resource](#mailing-list-resource).
+
+**OAuth scope**: `lists:read`
+
+### GET /api/lists/:list-name
+
+Equivalent to [/api/:username/lists/:list-name](#GET-apiusernamelistslist-name),
+implies the authenticated user.
+
+**OAuth scope**: `lists:read`
+
+### PUT /api/lists/:list-name
+
+Updates a [mailing list resource](#mailing-list-resource).
+
+**OAuth scope**: `lists:write`
+
+**Request body**
+
+```json
+{
+  "description": "mailing list description (markdown)" (optional)
+}
+```
+
+**Response**
+
+The updated [mailing list resource](#mailing-list-resource).
+
+### GET /api/user/:username/lists/:list-name/posts
+
+List of [email resources](#email-resource) posted to this list.
+
+**OAuth scope**: `lists:read`
+
+### GET /api/lists/:list-name/posts
+
+Equivalent to
+[/api/:username/lists/:list-name/posts](#GET-apiusernamelistslist-nameposts),
+implies the authenticated user.
+
+**OAuth scope**: `lists:read`
+
+### GET /api/subscriptions
+
+List of [subscription resources](#subscription-resources)
+
+**OAuth scope**: `subs:read`
+
+### POST /api/subscriptions
+
+Create a new [subscription resources](#subscription-resources)
+
+**OAuth scope**: `subs:write`
+
+**Request body**
+
+```json
+{
+  "list": "~owner/list-name"
+}
+```
+
+**Response**
+
+The new [subscription resource](#subscription-resource).
+
+### GET /api/subscriptions/:sub-id
+
+Retrieves a [subscription resource](#subscription-resource).
+
+**OAuth scope**: `subs:read`
+
+### DELETE /api/subscriptions/:sub-id
+
+Deletes this [subscription resource](#subscription-resource).
+
+**OAuth scope**: `subs:write`
+
+## Webhooks
+
+### /api/user/...
+
+Webhook for user events. Includes the [standard webhook
+endpoints](../api-conventions.md#webhooks)
+
+#### email:received
+
+Issued when lists.sr.ht receives an email from this user.
+
+**OAuth scope**: `emails:read`
+
+**Request body**
+
+The new [email resource](#email-resource).
+
+#### list:create
+
+Issued when the user creates a new mailing list.
+
+**OAuth scope**: `lists:read`
+
+**Request body**
+
+The new [mailing list resource](#mailing-list-resource).
+
+#### subscription:create
+
+Issued when the user subscribes to a mailing list.
+
+**OAuth scope**: `subs:read`
+
+**Request body**
+
+The new [subscription resource](#subscription-resource).
+
+#### subscription:remove
+
+Issued when the user unsubscribes from a mailing list.
+
+**OAuth scope**: `subs:read`
+
+**Request body**
+
+```json
+{
+  "id": integer ID of the affected subscription resource
+}
+```
+
+### /api/user/:username/lists/:list-name/...
+
+Webhook for mailing list events. Includes the [standard webhook
+endpoints](../api-conventions.md#webhooks)
+
+#### post:received
+
+Issued when a new email is posted to this list.
+
+**OAuth scope**: `lists:read`
+
+**Request body**
+
+The new [email resource](#email-resource).
+
+#### list:update
+
+Issued when the list details are updated.
+
+**OAuth scope**: `lists:read`
+
+**Request body**
+
+The updated [mailing list resource](#mailing-list-resource).