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