Repository files navigation

This is a set of documents which describes Gogs REST API v1 usage, since it's still in early stage:

1. Content of documentation and APIs are subject to change.
2. We do not provide documentation in other languages.
3. Aim to be in the format that is similar toGitHub REST API v3.

If you have any questions or concern, pleasefile an issue. 😊

• Administration
  • Users
  • Repositories
  • Organizations
  • Teams
• Issues
  • Comments
  • Labels
  • Milestones
• Miscellaneous
• Organizations
  • Members
  • Teams
• Repositories
  • Branches
  • Collaborators
  • Commits
  • Contents
  • Deploy Keys
  • Releases
  • Webhooks
• Users
  • Emails
  • Followers
  • Public Keys
• Git Data
  • Trees

The API is preinstalled with the base Gogs deployment. Seecurrent version andAPI source code for more details.

All Gogs APIs are underv1 using request path prefix/api/v1.

All data is sent and received as JSON unless specified otherwise.

HTTP/2 200content-type: application/json; charset=UTF-8date: Sat, 15 Dec 2018 01:55:28 GMTserver: Caddycontent-length: 175

All timestamps return in RFC3339 format:

YYYY-MM-DDTHH:MM:SSZ2006-01-02T15:04:05Z07:00

There are three ways to authenticate through Gogs API v1. Requests that require authentication will return404 Not Found, instead of403 Forbidden, in some places. This is to prevent the accidental leakage of private repositories to unauthorized users.

curl -u "unknwon" https://try.gogs.io/api/v1/users/unknwon/tokens

Basic authentication can only be used to obtain access tokens.

Personal access tokens are easier to manage and use, but except for few APIs (i.e. generate or get a access token), and they can be sent inheader orURL query.

$ curl -H "Authorization: token {ACCESS_TOKEN}" https://try.gogs.io/api/v1/user/repos$ curl https://try.gogs.io/api/v1/user/repos?token={ACCESS_TOKEN}

You can specify further pages with the?page parameter.

curl https://try.gogs.io/api/v1/repos/unknwon/hello/issues?page=1

Note that page numbering is 1-based and that omitting the?page parameter will return the first page.

TheLink header includes pagination information:

Link: <https://try.gogs.io/api/v1/repos/unknwon/hello/issues?page=3>; rel="next",  <https://try.gogs.io/api/v1/repos/unknwon/hello/issues?page=50>; rel="last"

The example includes a line break for readability.

This Link response header contains one or more Hypermedia link relations, some of which may require expansion as URI templates.

The possible rel values are:

• Go
• Android
• Bash

• The style of documentation is heavily influenced byGitHub Developer.