Skip to main content

Documentation Index

Fetch the complete documentation index at: https://gogs.io/llms.txt

Use this file to discover all available pages before exploring further.

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
All timestamps are returned in RFC 3339 format: 
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 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.

​
Pagination

API responses that return multiple items are paginated. You can specify further pages with the ?page query parameter. 
curl https://gogs.example.com/api/v1/repos/alice/hello/issues?page=1
Page numbering is 1-based. Omitting the ?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"
The possible rel values are:
NameDescription
nextThe link relation for the immediate next page of results.
lastThe link relation for the last page of results.
firstThe link relation for the first page of results.
prevThe 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:
LanguageRepository
Gogogs/go-gogs-client