1 files changed, 97 insertions, 0 deletions
diff --git a/paste.sr.ht/api.md b/paste.sr.ht/api.md
new file mode 100644
index 0000000..760fd45
--- /dev/null
+++ b/paste.sr.ht/api.md
@@ -0,0 +1,97 @@
+# API Reference
+
+The paste.sr.ht API allows you to browse and create pastes on paste.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 paste.sr.ht:
+
+- **paste:read** & **paste:write**: read & write pastes
+
+## Resources
+
+### Paste resource
+
+```json
+{
+  "created": "timestamp",
+  "sha": "id of this paste (SHA-1 hash)",
+  "user": { short-form user resource },
+  "files": [
+    {
+      "filename": "filename" or null,
+      "blob_id": "id of this blob (SHA-1 hash)"
+    }, ...
+  ]
+}
+```
+
+### Blob resource
+
+```json
+{
+  "created": "timestamp",
+  "sha": "id of this blob (SHA-1 hash)",
+  "contents": "contents of this blob"
+}
+```
+
+## Endpoints
+
+### GET /api/pastes
+
+List of paste resources.
+
+**OAuth scope**: `pastes:read`
+
+### POST /api/pastes
+
+Create a new paste;
+
+**OAuth scope**: `pastes:write`
+
+**Request body**
+
+```json
+{
+  "files": [
+    {
+      "filename": "filename" or null, (optional)
+      "contents": "contents of this file"
+    }
+  ]
+}
+```
+
+- **contents** must be a UTF-8 encoded string; binary files are not allowed
+
+**Response**
+
+The new paste resource.
+
+### GET /api/pastes/:sha
+
+Retrieves a paste resource.
+
+### GET /api/blobs/:sha
+
+Retrieves a blob resource.
+
+## Webhooks
+
+### /api/pastes/...
+
+Webhook for paste events. Includes the [standard webhook
+endpoints](../api-conventions.md#Webhooks)
+
+#### paste:create:
+
+Issued when a new paste is created. Requires `paste:read` OAuth scope. 
+
+**Request body**
+
+Affected paste resource.