diff options
Diffstat (limited to 'paste.sr.ht')
-rw-r--r-- | paste.sr.ht/api.md | 97 | ||||
-rw-r--r-- | paste.sr.ht/index.md | 7 | ||||
-rw-r--r-- | paste.sr.ht/installation.md | 4 |
3 files changed, 108 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. diff --git a/paste.sr.ht/index.md b/paste.sr.ht/index.md new file mode 100644 index 0000000..18a207d --- /dev/null +++ b/paste.sr.ht/index.md @@ -0,0 +1,7 @@ +[paste.sr.ht](https://paste.sr.ht) is an ad-hoc text file hosting service on +sr.ht. + +**See also** + +- [API reference](api.md) +- [Installation](installation.md) diff --git a/paste.sr.ht/installation.md b/paste.sr.ht/installation.md new file mode 100644 index 0000000..fc9c122 --- /dev/null +++ b/paste.sr.ht/installation.md @@ -0,0 +1,4 @@ +# Installation + +paste.sr.ht is a standard sr.ht web service and can be installed through the +[standard procedure](/installation.md). |