Add another builds endpoint

1 files changed, 38 insertions, 0 deletions

diff --git a/builds.sr.ht/api.md b/builds.sr.ht/api.md
index 74e7e03..36fa40e 100644
--- a/builds.sr.ht/api.md
+++ b/builds.sr.ht/api.md
@@ -4,6 +4,9 @@ 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
@@ -37,3 +40,38 @@ Inserts a new job into the job queue.
       "execute": boolean,           True to start the build immediately
                                       (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