path: root/builds.sr.ht/api.md

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

## 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)
    }