paste.sr.ht/api.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
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.