lists.sr.ht: document patchset tools API

1 files changed, 31 insertions, 0 deletions

diff --git a/lists.sr.ht/api.md b/lists.sr.ht/api.md
index fe3cd26..e443047 100644
--- a/lists.sr.ht/api.md
+++ b/lists.sr.ht/api.md
@@ -313,6 +313,37 @@ implies the authenticated user.
 
 **OAuth scope**: `patches:read`
 
+### PUT /api/user/:username/lists/:list-name/patchsets/:id/tools
+
+Sets the status of a "tool" which is processing this patch, used for example to
+indicate the status of continous integration for a change.
+
+**Request body**
+
+```json
+{
+  "icon": "icon status enum",
+  "details": "user-friendly details, markdown",
+  "key": "arbitrary string"
+}
+```
+
+"icon" shall be one of the following strings:
+
+- pending: the task is scheduled
+- waiting: the task is running and we are awaiting its status
+- success: the task completed successfully
+- failed: the task failed
+- cancelled: the task was cancelled
+
+"details" supports a subset of Markdown, including only bold and italic styles,
+inline code, and links. It must be no more than one line of text.
+
+"key" is an arbitrary string used to uniquely identify this tool. You may update
+the status of your tool later by providing the same key in a new PUT request.
+
+**OAuth scope**: `patches:write`
+
 ### GET /api/user/:username/lists/:list-name/patchsets/:id/patches
 
 List of [email resources](#email-resource) making up the set of patches included