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.