Add git.sr.ht API docs

2 files changed, 299 insertions, 0 deletions

diff --git a/git.sr.ht/api.md b/git.sr.ht/api.md
new file mode 100644
index 0000000..e44e3cf
--- /dev/null
+++ b/git.sr.ht/api.md
@@ -0,0 +1,298 @@
+---
+title: git.sr.ht API reference
+---
+
+The git.sr.ht API allows you to browse, create, and manage repositories on
+git.sr.ht programmatically. This API follows the [standard sourcehut API
+conventions](../api-conventions.md).
+
+## Authentication
+
+Authentication is done via the [meta.sr.ht OAuth
+flow](https://man.sr.ht/meta.sr.ht/oauth-api.md). The following OAuth scopes are
+available for git.sr.ht:
+
+- **info:read**, **info:write**: read & write repository details
+- **access:read**, **access:write**: read & write access control lists
+- **data:read**: read git data
+
+## Git protocols
+
+The high and low-level data endpoints are basic and provided as a convenience.
+For write operations or more complex read operations, we recommend using the
+git interface. git.sr.ht supports the [smart protocol][protocols] over HTTPS
+(read-only) and SSH (read/write).
+
+[protocols]: https://git-scm.com/book/en/v2/Git-Internals-Transfer-Protocols
+
+## Resources
+
+### Commit resource
+
+```json
+{
+  "id": "sha-1 hash",
+  "short_id": "truncated hash",
+  "author": {
+    "email": "email address",
+    "name": "author name"
+  },
+  "committer": {
+    "email": "email address",
+    "name": "committer name"
+  },
+  "timestamp": "timestamp",
+  "message": "commit message",
+  "tree": "tree ID (sha-1 hash)",
+  "parents": [ list of parent IDs (string, sha-1 hash) ],
+  "signature": {
+    "signature": "base64 encoded PGP signature",
+    "data": "base64 encoded signed payload"
+  } or null
+}
+```
+
+### Tree resource
+
+```json
+{
+  "id": "sha-1 hash",
+  "short_id": "truncated hash",
+  "entries": [
+    {
+      "name": "entry name",
+      "id": "sha-1 hash",
+      "type": "tree" | "blob",
+      "mode": unix file mode
+    }
+  ]
+}
+```
+
+### Reference resource
+
+```json
+{
+  "name": "name of reference (e.g. refs/heads/master)",
+  "target": "reference target (sha-1 hash)"
+}
+```
+
+### Repository resource
+
+```json
+{
+  "id": integer,
+  "created": "timestamp",
+  "subject": "message subject",
+  "name": "repository name",
+  "description": "repository description (markdown)",
+  "visibility": "public" | "unlisted" | "private"
+}
+```
+
+## Endpoints
+
+**Note**: usernames are prefixed with `~`.
+
+### GET /api/user/:username
+
+Retrieves a user resource.
+
+### GET /api/user
+
+Equivalent to [/api/user/:username](#GET-apiuserusername), implies the authenticated
+user.
+
+### GET /api/:username/repos
+
+List of [repository resources](#repository-resource) owned by this user.
+
+**OAuth scope**: `info:read`
+
+### GET /api/repos
+
+Equivalent to [/api/:username/repos](#GET-apiusernamerepos), implies the
+authenticated user.
+
+### POST /api/repos
+
+Creates a new [repository resource](#repository-resource).
+
+**OAuth scope**: `info:write`
+
+**Request body**
+
+```json
+{
+  "name": "repository name",
+  "description": "repository description (markdown)" (optional)
+  "visibility": "public" | "unlisted" | "private" (optional: default public)
+}
+```
+
+**Response**
+
+The new [repository resource](#repository-resource)
+
+### GET /api/:username/repos/:name
+
+Retrieves a [repository resource](#repository-resource).
+
+**OAuth scope**: `info:read`
+
+### GET /api/repos/:name
+
+Equivalent to [/api/:username/repos/:name](#GET-apiusernamereposname), implies
+the authenticated user.
+
+### PUT /api/repos/:name
+
+Updates a [repository resource](#repository-resource).
+
+**OAuth scope**: `info:write`
+
+**Request body**
+
+```json
+{
+  "name": "repository name" (optional),
+  "description": "repository description (markdown)" (optional),
+  "visibility": "public" | "unlisted" | "private" (optional)
+}
+```
+
+**Notes**
+
+- Updating the name will create a redirect.
+
+### DELETE /api/repos/:name
+
+Deletes a [repository resource](#repository-resource).
+
+**OAuth scope**: `info:write`
+
+## Common data endpoints
+
+Endpoints for fetching git data from repos.
+
+### GET /api/:username/repos/:name/refs
+
+List of [reference resources](#reference-resource) in this git repository.
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/refs
+
+Equivalent to [/api/:username/repos/refs](#GET-apiusernamereposnamerefs),
+implies the authenticated user.
+
+### GET /api/:username/repos/:name/log
+
+List of the latest [commit resources](#commit-resource) on the default branch.
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/log
+
+Equivalent to [/api/:username/repos/:name/log](#GET-apiusernamereposnamelog),
+implies the authenticated user.
+
+### GET /api/:username/repos/:name/log/:ref
+
+List of the latest [commit resources](#commit-resource) starting from the given
+reference (sha-1 ID or name).
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/log/:ref
+
+Equivalent to [/api/:username/repos/:name/log/:ref](#GET-apiusernamereposnamelogref),
+implies the authenticated user.
+
+## High-level data endpoints
+
+The endpoints work with paths instead of object IDs.
+
+### GET /api/:username/repos/:name/tree
+
+Returns the [tree resource](#tree-resource) for the latest commit to the default
+branch.
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/tree
+
+Equivalent to [/api/:username/repos/:name/tree](#GET-apiusernamereposnametree),
+implies the authenticated user.
+
+### GET /api/:username/repos/:name/tree/:ref
+
+Returns the [tree resource](#tree-resource) for the given reference.
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/tree/:ref
+
+Equivalent to [/api/:username/repos/:name/tree/:ref](#GET-apiusernamereposnametreeref),
+implies the authenticated user.
+
+### GET /api/:username/repos/:name/tree/:ref/:path
+
+Returns the [tree resource](#tree-resource) for the given reference, following
+the parent trees until the requested tree is found. In other words, this lists
+the contents of a subdirectory by path.
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/tree/:ref/:path
+
+Equivalent to [/api/:username/repos/:name/tree/:ref/:path](#GET-apiusernamereposnametreerefpath),
+implies the authenticated user.
+
+### GET /api/:username/repos/:name/blob/:ref/:path
+
+Returns the blob at the given path of the tree specified by the given reference.
+
+**Response**
+
+The contents of the requested blob, as text/plain or as application/octet-stream
+for binary blobs.
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/blob/:ref/:path
+
+Equivalent to [/api/:username/repos/:name/blob/:ref/:path](#GET-apiusernamereposnameblobrefpath),
+implies the authenticated user.
+
+## Low-level data endpoints
+
+These endpoints work with object IDs instead of paths.
+
+### GET /api/:username/repos/:name/tree/:id
+
+Returns the [tree resource](#tree-resource) with the given ID.
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/tree/:id
+
+Equivalent to [/api/:username/repos/:name/tree/:id](#GET-apiusernamereposnametreeid),
+implies the authenticated user.
+
+### GET /api/:username/repos/:name/blob/:id
+
+Returns the blob with the given ID.
+
+**Response**
+
+The contents of the requested blob, as text/plain or as application/octet-stream
+for binary blobs.
+
+**OAuth scope**: `data:read`
+
+### GET /api/repos/:name/blob/:id
+
+Equivalent to [/api/:username/repos/:name/blob/:id](#GET-apiusernamereposnameblobid),
+implies the authenticated user.
diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md
index a6ec18e..a3407d0 100644
--- a/git.sr.ht/index.md
+++ b/git.sr.ht/index.md
@@ -7,6 +7,7 @@ sr.ht.
 
 **See also**:
 
+- [API reference](api.md)
 - [Installation guide](installation.md)
 
 **Important**: git.sr.ht is a work in progress. As a consequence, URLs of