Add patchsets to lists.sr.ht API docs

1 files changed, 106 insertions, 0 deletions

diff --git a/lists.sr.ht/api.md b/lists.sr.ht/api.md
index 1ec6d4e..f009ac0 100644
--- a/lists.sr.ht/api.md
+++ b/lists.sr.ht/api.md
@@ -15,6 +15,7 @@ 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
+- **patches:read**, **patches:write**: read & write patchsets on lists
 
 ## Resources
 
@@ -78,6 +79,32 @@ available for lists.sr.ht:
 }
 ```
 
+### Patchset resource
+
+```json
+{
+  "id": integer,
+  "created": "timestamp",
+  "updated": "timestamp",
+  "subject": "patchset subject",
+  "prefix": "subject prefix",
+  "version": integer,
+  "status": "patchset status enum",
+  "list": { short form list resource },
+  "cover_letter": { short form email resource } or null,
+  "superseded_by": { short form patchset resource } or null
+}
+```
+
+**Notes**
+
+- The status field may be one of `proposed`, `needs_revision`, `superseded`,
+  `approved`, `rejected`, or `applied`.
+- The patchset subject is extracted from the cover letter if present, otherwise
+  from the subject of the first patch.
+- The subject prefix, in the example of `[PATCH foobar] Add foo to bar`, is
+  "foobar".
+
 ## Endpoints
 
 **Note**: in all routes, `:username` may be substituted with an email address,
@@ -218,6 +245,75 @@ implies the authenticated user.
 
 **OAuth scope**: `lists:read`
 
+### GET /api/user/:username/lists/:list-name/patchsets
+
+List of [patchset resources](#patchset-resource) posted to this list.
+
+**OAuth scope**: `patches:read`
+
+### GET /api/user/:username/lists/:list-name/patchsets
+
+Equivalent to
+[/api/user/:username/lists/:list-name/patchsets](#GET-apiuserusernamelistslist-namepatchsets),
+implies the authenticated user.
+
+**OAuth scope**: `patches:read`
+
+### GET /api/user/:username/lists/:list-name/patchsets/:id
+
+Retrieves a [patchset resource](#patchset-resource).
+
+**OAuth scope**: `patches:read`
+
+### GET /api/user/:username/lists/:list-name/patchsets/:id
+
+Equivalent to
+[/api/user/:username/lists/:list-name/patchsets/:id](#GET-apiuserusernamelistslist-namepatchsetsid),
+implies the authenticated user.
+
+**OAuth scope**: `patches:read`
+
+### GET /api/user/:username/lists/:list-name/patchsets/:id
+
+Updates a [patchset resource](#patchset-resource).
+
+**OAuth scope**: `patches:read`
+
+**Request body**
+
+```json
+{
+  "status": "patchset status enum" (optional)
+}
+```
+
+**Response**
+
+The updated [patchset resource](#patchset-resource).
+
+### GET /api/user/:username/lists/:list-name/patchsets/:id
+
+Equivalent to
+[/api/user/:username/lists/:list-name/patchsets/:id](#GET-apiuserusernamelistslist-namepatchsetsid),
+implies the authenticated user.
+
+**OAuth scope**: `patches:read`
+
+### GET /api/user/:username/lists/:list-name/patchsets/:id/patches
+
+List of [email resources](#email-resource) making up the set of patches included
+in this patchset.
+
+**OAuth scope**: `patches:read`
+
+### GET /api/user/:username/lists/:list-name/patchsets/:id/patches
+
+Equivalent to
+[/api/user/:username/lists/:list-name/patchsets/:id/patches](#GET-apiuserusernamelistslist-namepatchsetsidpatches),
+implies the authenticated user.
+
+**OAuth scope**: `patches:read`
+
 ### GET /api/subscriptions
 
 List of [subscription resources](#subscription-resources)
@@ -310,6 +406,16 @@ Issued when the user unsubscribes from a mailing list.
 Webhook for mailing list events. Includes the [standard webhook
 endpoints](../api-conventions.md#webhooks)
 
+#### patchset:received
+
+Issued when a complete patchset is received.
+
+**OAuth scope**: `patches:read`
+
+**Request body**
+
+The new [patchset resource](#patchset-resource).
+
 #### post:received
 
 Issued when a new email is posted to this list.