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.
#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.