Repositories

Repositories

Search repositories

GET /repos/search

Parameters

Name	Type	Description
q	string	Required Keyword of username
uid	int	User ID to specify search whose repositories. Default is 0 and search all repositories
limit	int	Limit number of search results. Default is 10

Example

$ curl https://try.gogs.io/api/v1/repos/search?q=u&uid=1&limit=5

Response

Status: 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 1717,
      "owner": {
        "id": 0,
        "username": "",
        "full_name": "",
        "email": "",
        "avatar_url": ""
      },
      "full_name": "unknwon/Issue-966",
      "private": false,
      "fork": false,
      "html_url": "",
      "clone_url": "",
      "ssh_url": "",
      "permissions": {
        "admin": false,
        "push": false,
        "pull": false
      }
    },
    {
      "id": 154,
      "owner": {
        "id": 0,
        "username": "",
        "full_name": "",
        "email": "",
        "avatar_url": ""
      },
      "full_name": "unknwon/issue935",
      "private": false,
      "fork": false,
      "html_url": "",
      "clone_url": "",
      "ssh_url": "",
      "permissions": {
        "admin": false,
        "push": false,
        "pull": false
      }
    }
  ],
  "ok": true
}

List your repositories

List repositories that are accessible to the authenticated user.

This includes repositories owned by the authenticated user, repositories where the authenticated user is a collaborator, and repositories that the authenticated user has access to through an organization membership.

GET /user/repos

Response

Status: 200 OK
Content-Type: application/json

[
  {
    "id": 2,
    "owner": {
      "id": 1,
      "username": "unknwon",
      "full_name": "",
      "email": "[email protected]",
      "avatar_url": "/avatars/1"
    },
    "full_name": "unknwon/macaron",
    "private": false,
    "fork": false,
    "html_url": "http://localhost:3000/unknwon/macaron",
    "clone_url": "http://localhost:3000/unknwon/macaron.git",
    "ssh_url": "jiahuachen@localhost:unknwon/macaron.git",
    "permissions": {
      "admin": true,
      "push": true,
      "pull": true
    }
  },
  {
    "id": 8,
    "owner": {
      "id": 2,
      "username": "org1",
      "full_name": "org1",
      "email": "[email protected]",
      "avatar_url": "/avatars/2"
    },
    "full_name": "org1/gogs",
    "private": false,
    "fork": false,
    "html_url": "http://localhost:3000/org1/gogs",
    "clone_url": "http://localhost:3000/org1/gogs.git",
    "ssh_url": "jiahuachen@localhost:org1/gogs.git",
    "permissions": {
      "admin": true,
      "push": true,
      "pull": true
    }
  }
]

Create

Create a new repository for the authenticated user.

POST /user/repos

Create a new repository in this organization. The authenticated user must be a owner of the specified organization.

POST /orgs/:org/repos

Parameters

Name	Type	Description
name	string	Required The name of the repository
description	string	A short description of the repository
private	bool	Either true to create a private repository, or false to create a public one. Default is false
auto_init	bool	Pass true to create an initial commit with README, .gitignore and LICENSE. Default is false
gitignores	string	Desired language .gitignore templates to apply. Use the name of the templates. For example, "Go" or "Go,SublimeText".
license	string	Desired LICENSE template to apply. Use the name of the template. For example, "Apache v2 License" or "MIT License".
readme	string	Desired README template to apply. Use the name of the template. Default is Default

Litte notes on README template

If you have created file on your corresponding custom/readme/My README, then use "My README".

Currently, you can use following placeholder for corresponding values of repository:

• {Name}: Repository name
• {Description}: Repository description
• {CloneURL.SSH}: Repository SSH clone address
• {CloneURL.HTTPS}: Repository HTTP/HTTPS clone address

Example

{
  "name": "Hello-World",
  "description": "This is your first repository",
  "private": false
}

Response

Status: 201 Created
Content-Type: application/json

{
  "id": 27,
  "owner": {
    "id": 1,
    "username": "unknwon",
    "full_name": "",
    "email": "[email protected]",
    "avatar_url": "/avatars/1"
  },
  "full_name": "unknwon/Hello-World",
  "private": false,
  "fork": false,
  "html_url": "http://localhost:3000/unknwon/Hello-World",
  "clone_url": "http://localhost:3000/unknwon/hello-world.git",
  "ssh_url": "jiahuachen@localhost:unknwon/hello-world.git",
  "permissions": {
    "admin": true,
    "push": true,
    "pull": true
  }
}

Migrate

Migrate a repository from other Git hosting sources for the authenticated user.

POST /repos/migrate

To migrate a repository for a organization, the authenticated user must be a owner of the specified organization.

Parameters

Name	Type	Description
clone_addr	string	Required Remote Git address (HTTP/HTTPS URL or local path)
auth_username	string	Authorization username
auth_password	string	Authorization password
uid	int	Required User ID who takes ownership of this repository
repo_name	string	Required Repository name
mirror	bool	Repository will be a mirror. Default is false
private	bool	Repository will be private. Default is false
description	string	Repository description

Example

{
  "clone_addr": "https://github.com/Unknwon/macaron",
  "uid": 1,
  "repo_name": "hello-macaron"
}

Response

Status: 201 Created
Content-Type: application/json

{
  "id": 19,
  "owner": {
    "id": 1,
    "username": "unknwon",
    "full_name": "",
    "email": "[email protected]",
    "avatar_url": "//1.gravatar.com/avatar/d8b2871cdac01b57bbda23716cc03b96"
  },
  "full_name": "unknwon/hello-macaron",
  "private": false,
  "fork": false,
  "html_url": "http://localhost:3000/unknwon/hello-macaron",
  "clone_url": "http://localhost:3000/unknwon/hello-macaron.git",
  "ssh_url": "unknwon@localhost:unknwon/hello-macaron.git",
  "permissions": {
    "admin": true,
    "push": true,
    "pull": true
  }
}