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.

Notice: the git.sr.ht API is due for an overhaul in the foreseeable future; be prepared for it to change. The changes will be announced in advance on the sr.ht-announce and sr.ht-discuss mailing lists.

Authentication

Authentication is done via the meta.sr.ht OAuth flow. The following OAuth scopes are available for git.sr.ht:

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 over HTTPS (read-only) and SSH (read/write).

Resources

Artifact resource

{
  "created": "timestamp",
  "checksum": "checksum (string)",
  "size": integer (bytes),
  "filename": "string",
  "url": "url"
}

Note: the checksum format is algorithm:checksum. Presently the only supported algorithm is sha256.

Example: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Commit resource

{
  "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

{
  "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

{
  "name": "name of reference (e.g. refs/heads/master)",
  "target": "reference target (sha-1 hash)",
  "artifacts": [ list of artifact resources ]
}

Repository resource

{
  "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, implies the authenticated user.

GET /api/:username/repos

List of repository resources owned by this user.

OAuth scope: info:read

GET /api/repos

Equivalent to /api/:username/repos, implies the authenticated user.

POST /api/repos

Creates a new repository resource.

OAuth scope: info:write

Request body

{
  "name": "repository name",
  "description": "repository description (markdown)" (optional)
  "visibility": "public" | "unlisted" | "private" (optional: default public)
}

Response

The new repository resource

GET /api/:username/repos/:name

Retrieves a repository resource.

OAuth scope: info:read

GET /api/repos/:name

Equivalent to /api/:username/repos/:name, implies the authenticated user.

PUT /api/repos/:name

Updates a repository resource.

OAuth scope: info:write

Request body

{
  "name": "repository name" (optional),
  "description": "repository description (markdown)" (optional),
  "visibility": "public" | "unlisted" | "private" (optional)
}

Notes

DELETE /api/repos/:name

Deletes a 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 in this git repository.

OAuth scope: data:read

GET /api/repos/:name/refs

Equivalent to /api/:username/repos/refs, implies the authenticated user.

GET /api/:username/repos/:name/log

List of the latest commit resources on the default branch.

OAuth scope: data:read

POST /api/repos/:name/artifacts/:ref

Equivalent to /api/:username/repos/:name/artifacts/:ref, implies the authenticated user.

POST /api/repos/:username/repos/:name/artifacts/:ref

Attaches a file artifact to the specified ref.

Note: this endpoint does not accept JSON. Submit your request as multipart/form-data, with a single field: file.

OAuth scope: data:write

GET /api/repos/:name/log

Equivalent to /api/:username/repos/:name/log, implies the authenticated user.

GET /api/:username/repos/:name/log/:ref

List of the latest commit resources 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, 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 for the latest commit to the default branch.

OAuth scope: data:read

GET /api/repos/:name/tree

Equivalent to /api/:username/repos/:name/tree, implies the authenticated user.

GET /api/:username/repos/:name/tree/:ref

Returns the tree resource for the given reference.

OAuth scope: data:read

GET /api/repos/:name/tree/:ref

Equivalent to /api/:username/repos/:name/tree/:ref, implies the authenticated user.

GET /api/:username/repos/:name/tree/:ref/:path

Returns the 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, 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.

OAuth scope: data:read

Response

The contents of the requested blob, as text/plain or as application/octet-stream for binary blobs.

GET /api/repos/:name/blob/:ref/:path

Equivalent to /api/:username/repos/:name/blob/:ref/:path, 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 with the given ID.

OAuth scope: data:read

GET /api/repos/:name/tree/:id

Equivalent to /api/:username/repos/:name/tree/:id, implies the authenticated user.

GET /api/:username/repos/:name/blob/:id

Returns the blob with the given ID.

OAuth scope: data:read

Response

The contents of the requested blob, as text/plain or as application/octet-stream for binary blobs.

GET /api/repos/:name/blob/:id

Equivalent to /api/:username/repos/:name/blob/:id, implies the authenticated user.

Webhooks

/api/user/...

Webhook for user events. Includes the standard webhook endpoints

repo:create

Issued when the user creates a new repository.

OAuth scope: info:read

Request body

The new repository resource.

repo:update

Issued when the user updates repository details, such as name or description.

OAuth scope: info:read

Request body

The updated repository resource.

Notes

repo:delete

Issued when the user deletes a repository.

OAuth scope: info:read

Request body

{
  "id": integer ID of the affected repository resource
}

/api/:username/repos/:name/...

Webhook for repository events. Includes the standard webhook endpoints. You may pass an additional parameter to the webhook creation endpoint named sync, which shall be a boolean value.

repo:post-update

Called after refs have been updated. If the sync flag on this webhook is set to true, the webhook is invoked during git-receive-pack's post-update hook and the response text is printed to the console of the user executing git push. Your server has 5 seconds to respond to the HTTP request.

OAuth scope: data:read

Request body

{
  "push": "uuid assigned to this push event",
  "push-options": { map of push options },
  "pusher": { user resource },
  "refs": [
    {
      "name": "updated ref, e.g. refs/heads/master",
      "annotated_tag": {
        "name": "tag name",
        "message": "tag message"
      }, # may not be present
      "old": {
        commit resource this ref used to refer to, or null in the case of new
        refs
      },
      "new": {
        commit resource this ref now refers to, or null in the case of deleted
        refs
      }
    }
  ]
}

Notes

About this wiki

commit 8d981c707aae20f461806288bc929f4fae8a6524
Author: Drew DeVault <sir@cmpwn.com>
Date:   2020-02-26T14:36:57-05:00

Document builds.sr.ht artifacts API
Clone this wiki
https://git.sr.ht/~sircmpwn/sr.ht-docs (read-only)
git@git.sr.ht:~sircmpwn/sr.ht-docs (read/write)