Dan Fredell edited this page Apr 20, 2018 · 26 revisions


This is a set of documents which describes Gogs API 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 format similar to GitHub v3 APIs.

Implementation Status

The following list syncs with develop branch of Gogs ([-] means planned but feature itself has not been implemented yet in Gogs).

  • Activity
    • Feeds
    • [-] Notifications
    • Starring
    • Watching
  • [-] Gists
  • Git Data
    • Blobs
    • Commits
    • References
    • Tags
    • Trees
  • Issues
    • Assignees
    • Comments
    • Labels
    • Milestones
  • Miscellaneous
    • Gitignore
    • Markdown
  • Organizations
    • Members
    • Teams
    • Webhooks
  • Pull Requests
    • [-] Review Comments
  • Repositories
    • Collaborators
    • [-] Comments
    • Commits
    • Contents
    • Deploy Keys
    • Forks
    • Releases
    • Webhooks
  • Users
    • Emails
    • Followers
    • Public Keys
  • Administration
    • [-] Stats
    • Users
    • Organizations
    • Repositories
    • Authentications
    • [-] Configuration
    • Notices

If you have any questions or concern, please file an issue. :blush:


The API is preinstalled with the base Gogs deployment. See current version and api source for more details.

Current Version

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


Parameters of all requests use POST method can be passed through a normal HTML form or JSON data, but sending JSON is recommended.


There are three ways to authenticate through Gogs API v1. 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 repositories to unauthorized users.

Basic Authentication

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

Basic authentication can be used for all Gogs APIs.

Access Token

Personal access tokens are easier to manage and use, but except for few APIs(e.g. API to generate or get a access token), and they can be sent in header or URL 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

Other Implementations


You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.