Start adding builds.sr.ht docs

3 files changed, 47 insertions, 1 deletions

diff --git a/builds.sr.ht/api.md b/builds.sr.ht/api.md
new file mode 100644
index 0000000..74e7e03
--- /dev/null
+++ b/builds.sr.ht/api.md
@@ -0,0 +1,39 @@
+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)
+    }
diff --git a/builds.sr.ht/index.md b/builds.sr.ht/index.md
new file mode 100644
index 0000000..1027492
--- /dev/null
+++ b/builds.sr.ht/index.md
@@ -0,0 +1,5 @@
+[builds.sr.ht](https://builds.sr.ht) is a service on sr.ht that allows you to
+submit "build manifests" for us to work on. We spin up a virtual machine per
+your specifications and run your scripts in it. This is generally used to
+compile and test patches, deploy websites, build and publish packages, and so
+on.
diff --git a/index.md b/index.md
index 0b96119..9cc8375 100644
--- a/index.md
+++ b/index.md
@@ -12,7 +12,9 @@ What would you like to learn more about?
   <div class="col-md-6">
     <dt>builds.sr.ht</dt>
     <dd>
-      <a href="#">User Manual</a>&mdash;<a href="#">API Reference</a>
+      <a href="/builds.sr.ht">User Manual</a>
+      &mdash;
+      <a href="/builds.sr.ht/api.md">API Reference</a>
     </dd>
   </div>
   <div class="col-md-6">