api

The build.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.

API Endpoints

The following endpoints are available to users with an OAuth key valid for the specified scope.

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)
  "access:read": [              List of users that have read access to this
                                  job (optional). The user submitting the
                                  build will be included regardless of this
                                  value. The special username "*" indicates
                                  public read access to this build.
                                  Defaults to *.
    "string"                    Username
  ],
  "access:write": [             List of users that have write access to this
                                  job (optional). The user submitting the
                                  build will be included regardless of this
                                  value.
    "string"                    Username
  ],
  "triggers": [...],            Post-build triggers (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)
}

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

Table of Contents

This commit

commit 8cc980855552f02959da7a2c3742e7c68e917538
Author: Drew DeVault <sir@cmpwn.com>
Date:   2018-07-14T22:09:09

Fix some typos in send-email.md
Clone this wiki
man@man.sr.ht:root
https://man.sr.ht/root