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

---
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.

**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](#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.

**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](#GET-apiusernamereposnameblobid),
implies the authenticated user.