The Gogs API provides a RESTful interface for interacting with your Gogs instance programmatically. It aims to follow a format similar to the GitHub REST API v3.
The API is bundled with every Gogs installation. No additional setup is required.
The API is still in its early stages. Content and endpoints are subject to change.
Current version
All Gogs APIs are under v1 using the request path prefix /api/v1.
https://gogs.example.com/api/v1
Schema
All data is sent and received as JSON unless specified otherwise.
HTTP/2 200
Content-Type: application/json; charset=UTF-8
YYYY-MM-DDTHH:MM:SSZ
2006-01-02T15:04:05Z07:00
Authentication
There are two ways to authenticate through the Gogs API. Requests that require authentication will return 404 Not Found instead of 403 Forbidden in some places. This is to prevent the accidental leakage of private resources to unauthorized users.
Basic authentication
Access token
Basic authentication is used to obtain access tokens. Supply your username (you will be prompted for your password):curl -u "alice" https://gogs.example.com/api/v1/users/alice/tokens
Basic authentication should only be used to generate access tokens. Do not use it for regular API requests.
Personal access tokens are the recommended way to authenticate. They can be sent via a request header or a URL query parameter.Using a header:curl -H "Authorization: token {YOUR_ACCESS_TOKEN}" https://gogs.example.com/api/v1/user/repos
curl https://gogs.example.com/api/v1/user/repos?token={YOUR_ACCESS_TOKEN}
Using the Authorization header is preferred over the query parameter, as URLs may be logged by proxies and servers.
?page query parameter.
curl https://gogs.example.com/api/v1/repos/alice/hello/issues?page=1
?page parameter returns the first page.
Pagination info is included in the Link header of each response. Use this to navigate between pages programmatically.
Link: <https://gogs.example.com/api/v1/repos/alice/hello/issues?page=3>; rel="next",
<https://gogs.example.com/api/v1/repos/alice/hello/issues?page=50>; rel="last"
rel values are:
| Name | Description |
|---|
next | The link relation for the immediate next page of results. |
last | The link relation for the last page of results. |
first | The link relation for the first page of results. |
prev | The link relation for the immediate previous page of results. |
Always use the Link header values to navigate between pages rather than constructing URLs manually.
SDKs
The following best-effort-maintained SDKs are available:
| Language | Repository |
|---|
| Go | gogs/go-gogs-client |
