pages.sr.ht: add API reference

This documents the API implemented in [1].

[1]: https://git.sr.ht/~sircmpwn/pages.sr.ht/tree/master/item/server.go

1 files changed, 32 insertions, 0 deletions

diff --git a/pages.sr.ht/api.md b/pages.sr.ht/api.md
new file mode 100644
index 0000000..b7e6d0e
--- /dev/null
+++ b/pages.sr.ht/api.md
@@ -0,0 +1,32 @@
+---
+title: pages.sr.ht API reference
+---
+
+The pages.sr.ht API is a convenience wrapper around the [GraphQL API][0] and
+allows one to easily publish a site with tools like `curl`.
+
+# API endpoints
+
+The following endpoints are available to users with an OAuth2 token valid for
+the specified scope.
+
+## POST /publish/:domain
+
+**Scopes**: `PAGES:RW`
+
+Publish a site.
+
+The request body must use the `multipart/form-data` content type. The following
+fields are supported:
+
+- `content` (required): a .tar.gz file containing the new site content.
+- `protocol`: select which protocol variant of the site to update. If unset,
+  defaults to HTTPS.
+
+A sub-directory can be appended to the URL (e.g. `/publish/example.org/subdir`)
+in which case only the specified sub-directory is updated. The rest of the
+files are left unchanged.
+
+The response contains the new site version as plain-text.
+
+[0]: https://srht.site/graphql