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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
---
title: builds.sr.ht API reference
---
**NOTICE**: This is the documentation for the legacy REST API. It is being
replaced with the [GraphQL API](graphql.md).
The builds.sr.ht API allows you to insert jobs, monitor their progress, and
access some information about the build system. Authentication to this API is
brokered by meta.sr.ht. This API uses standard sr.ht error responses. All
requests should be submitted via `https://builds.sr.ht`.
**Notice**: the builds.sr.ht API is due for an overhaul in the foreseeable
future; be prepared for it to change. The changes will be announced in advance
on the [sr.ht-announce] and [sr.ht-discuss] mailing lists.
[sr.ht-announce]: https://lists.sr.ht/~sircmpwn/sr.ht-announce
[sr.ht-discuss]: https://lists.sr.ht/~sircmpwn/sr.ht-discuss
# API Endpoints
The following endpoints are available to users with an OAuth key valid for the
specified scope.
## GET /api/jobs
**Scopes**: jobs:read
Returns a paginated list of job resources.
## POST /api/jobs
**Scopes**: jobs:write
Inserts a new job into the job queue.
```
{
"manifest": "string", The build manifest
"note": "string", Human-friendly description of this build
(markdown, optional)
"tags": [...], Arbitrary list of strings that identify this
build and can be used to navigate the
dashboard. Each string must use only
lowercase alphanumeric characters, or any
of "-_." (optional)
"execute": boolean, True to start the build immediately
(optional — defaults to true)
"secrets": boolean, True to provide secrets during the build
(optional — defaults to true)
}
```
Note: build manifests are YAML, which is machine editable. You are encouraged to
edit it before submitting!
## GET /api/jobs/:id
Gets information about a job by its ID.
**Scopes**: jobs:read
```
{
"id": integer,
"status": "job status enum",
"setup_log": "url", URL to captured stdout/stderr of setup
"tasks": [
{
"name": "setup",
"status": "task status enum"
"log": "url",
},
...
]
}
```
### Job status enum
- **pending**: waiting for user intervention to start
- **queued**: queued to start when a worker is available
- **running**: job is in-progress
- **success**: build completed without errors
- **failed**: build completed with errors
### Task status enum
- **pending**: waiting for earlier tasks to complete
- **running**: task is in-progress
- **success**: task completed without errors
- **failed**: task completed with errors
## GET /api/jobs/:id/artifacts
Returns a paginated list of artifact resources created by this job.
**Scopes**: jobs:read
Artifact resource:
```
{
"id": integer,
"created": timestamp,
"path": /original/filepath/in/guest,
"name": basename,
"url": URL from which the artifact may be downloaded,
"size": size in bytes
}
```
## GET /api/jobs/:id/manifest
Returns the original job's build manifest as plain text.
## POST /api/jobs/:id/start
Starts a job that was created with `execute=false`. Returns an empty JSON
object when successful.
## POST /api/jobs/:id/cancel
Cancels a running job. Returns an empty JSON object when successful.
|
