Skip to content
forgit api docs

Search repositories

GET
/search/repositories

Find repositories via various criteria. This method returns up to 100 results per page.

When searching for repositories, you can get text match metadata for the name and description fields when you pass the text-match media type. For more details about how to receive highlighted search results, see Text match metadata.

For example, if you want to search for popular Tetris repositories written in assembly code, your query might look like this:

q=tetris+language:assembly&sort=stars&order=desc

This query searches for repositories with the word tetris in the name, the description, or the README. The results are limited to repositories where the primary language is assembly. The results are sorted by stars in descending order, so that the most popular repositories appear first in the search results.

API method documentation

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “ Query Parameters ”
q
required
string

The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. The REST API supports the same qualifiers as the web interface for GitHub. To learn more about the format of the query, see Constructing a search query. See “Searching for repositories” for a detailed list of qualifiers.

sort
string
Allowed values: stars forks help-wanted-issues updated

Sorts the results of your query by number of stars, forks, or help-wanted-issues or how recently the items were updated. Default: best match

order
string
default: desc
Allowed values: desc asc

Determines whether the first search result returned is the highest number of matches (desc) or lowest number of matches (asc). This parameter is ignored unless you provide sort.

per_page
integer
default: 30

The number of results per page (max 100). For more information, see “Using pagination in the REST API.”

page
integer
default: 1

The page number of the results to fetch. For more information, see “Using pagination in the REST API.”

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response

Media type application/json
object
total_count
required
integer
incomplete_results
required
boolean
items
required
Array<object>
Repo Search Result Item

Repo Search Result Item

object
id
required
integer
node_id
required
string
name
required
string
full_name
required
string
owner
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
private
required
boolean
html_url
required
string format: uri
description
required
string
nullable
fork
required
boolean
url
required
string format: uri
created_at
required
string format: date-time
updated_at
required
string format: date-time
pushed_at
required
string format: date-time
homepage
required
string format: uri
nullable
size
required
integer
stargazers_count
required
integer
watchers_count
required
integer
language
required
string
nullable
forks_count
required
integer
open_issues_count
required
integer
master_branch
string
default_branch
required
string
score
required
number
forks_url
required
string format: uri
keys_url
required
string
collaborators_url
required
string
teams_url
required
string format: uri
hooks_url
required
string format: uri
issue_events_url
required
string
events_url
required
string format: uri
assignees_url
required
string
branches_url
required
string
tags_url
required
string format: uri
blobs_url
required
string
git_tags_url
required
string
git_refs_url
required
string
trees_url
required
string
statuses_url
required
string
languages_url
required
string format: uri
stargazers_url
required
string format: uri
contributors_url
required
string format: uri
subscribers_url
required
string format: uri
subscription_url
required
string format: uri
commits_url
required
string
git_commits_url
required
string
comments_url
required
string
issue_comment_url
required
string
contents_url
required
string
compare_url
required
string
merges_url
required
string format: uri
archive_url
required
string
downloads_url
required
string format: uri
issues_url
required
string
pulls_url
required
string
milestones_url
required
string
notifications_url
required
string
labels_url
required
string
releases_url
required
string
deployments_url
required
string format: uri
git_url
required
string
ssh_url
required
string
clone_url
required
string
svn_url
required
string format: uri
forks
required
integer
open_issues
required
integer
watchers
required
integer
topics
Array<string>
mirror_url
required
string format: uri
nullable
has_issues
required
boolean
has_projects
required
boolean
has_pages
required
boolean
has_wiki
required
boolean
has_downloads
required
boolean
has_discussions
boolean
has_pull_requests
boolean
pull_request_creation_policy

The policy controlling who can create pull requests: all or collaborators_only.

string
Allowed values: all collaborators_only
archived
required
boolean
disabled
required

Returns whether or not this repository disabled.

boolean
visibility

The repository visibility: public, private, or internal.

string
license
required
License Simple

License Simple

object
key
required
string
name
required
string
url
required
string format: uri
nullable
spdx_id
required
string
nullable
node_id
required
string
html_url
string format: uri
permissions
object
admin
required
boolean
maintain
boolean
push
required
boolean
triage
boolean
pull
required
boolean
text_matches
Search Result Text Matches
Array<object>
object
object_url
string
object_type
string
nullable
property
string
fragment
string
matches
Array<object>
object
text
string
indices
Array<integer>
temp_clone_token
string
allow_merge_commit
boolean
allow_squash_merge
boolean
allow_rebase_merge
boolean
allow_auto_merge
boolean
delete_branch_on_merge
boolean
allow_forking
boolean
is_template
boolean
web_commit_signoff_required
boolean
Examples
Example default 
{
  "total_count": 40,
  "incomplete_results": false,
  "items": [
    {
      "id": 3081286,
      "node_id": "MDEwOlJlcG9zaXRvcnkzMDgxMjg2",
      "name": "Tetris",
      "full_name": "dtrupenn/Tetris",
      "owner": {
        "login": "dtrupenn",
        "id": 872147,
        "node_id": "MDQ6VXNlcjg3MjE0Nw==",
        "avatar_url": "https://secure.gravatar.com/avatar/e7956084e75f239de85d3a31bc172ace?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png",
        "gravatar_id": "",
        "url": "https://api.github.com/users/dtrupenn",
        "received_events_url": "https://api.github.com/users/dtrupenn/received_events",
        "type": "User",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "site_admin": true
      },
      "private": false,
      "html_url": "https://github.com/dtrupenn/Tetris",
      "description": "A C implementation of Tetris using Pennsim through LC4",
      "fork": false,
      "url": "https://api.github.com/repos/dtrupenn/Tetris",
      "created_at": "2012-01-01T00:31:50Z",
      "updated_at": "2013-01-05T17:58:47Z",
      "pushed_at": "2012-01-01T00:37:02Z",
      "homepage": "https://github.com",
      "size": 524,
      "stargazers_count": 1,
      "watchers_count": 1,
      "language": "Assembly",
      "forks_count": 0,
      "open_issues_count": 0,
      "master_branch": "master",
      "default_branch": "master",
      "score": 1,
      "archive_url": "https://api.github.com/repos/dtrupenn/Tetris/{archive_format}{/ref}",
      "assignees_url": "https://api.github.com/repos/dtrupenn/Tetris/assignees{/user}",
      "blobs_url": "https://api.github.com/repos/dtrupenn/Tetris/git/blobs{/sha}",
      "branches_url": "https://api.github.com/repos/dtrupenn/Tetris/branches{/branch}",
      "collaborators_url": "https://api.github.com/repos/dtrupenn/Tetris/collaborators{/collaborator}",
      "comments_url": "https://api.github.com/repos/dtrupenn/Tetris/comments{/number}",
      "commits_url": "https://api.github.com/repos/dtrupenn/Tetris/commits{/sha}",
      "compare_url": "https://api.github.com/repos/dtrupenn/Tetris/compare/{base}...{head}",
      "contents_url": "https://api.github.com/repos/dtrupenn/Tetris/contents/{+path}",
      "contributors_url": "https://api.github.com/repos/dtrupenn/Tetris/contributors",
      "deployments_url": "https://api.github.com/repos/dtrupenn/Tetris/deployments",
      "downloads_url": "https://api.github.com/repos/dtrupenn/Tetris/downloads",
      "events_url": "https://api.github.com/repos/dtrupenn/Tetris/events",
      "forks_url": "https://api.github.com/repos/dtrupenn/Tetris/forks",
      "git_commits_url": "https://api.github.com/repos/dtrupenn/Tetris/git/commits{/sha}",
      "git_refs_url": "https://api.github.com/repos/dtrupenn/Tetris/git/refs{/sha}",
      "git_tags_url": "https://api.github.com/repos/dtrupenn/Tetris/git/tags{/sha}",
      "git_url": "git:github.com/dtrupenn/Tetris.git",
      "issue_comment_url": "https://api.github.com/repos/dtrupenn/Tetris/issues/comments{/number}",
      "issue_events_url": "https://api.github.com/repos/dtrupenn/Tetris/issues/events{/number}",
      "issues_url": "https://api.github.com/repos/dtrupenn/Tetris/issues{/number}",
      "keys_url": "https://api.github.com/repos/dtrupenn/Tetris/keys{/key_id}",
      "labels_url": "https://api.github.com/repos/dtrupenn/Tetris/labels{/name}",
      "languages_url": "https://api.github.com/repos/dtrupenn/Tetris/languages",
      "merges_url": "https://api.github.com/repos/dtrupenn/Tetris/merges",
      "milestones_url": "https://api.github.com/repos/dtrupenn/Tetris/milestones{/number}",
      "notifications_url": "https://api.github.com/repos/dtrupenn/Tetris/notifications{?since,all,participating}",
      "pulls_url": "https://api.github.com/repos/dtrupenn/Tetris/pulls{/number}",
      "releases_url": "https://api.github.com/repos/dtrupenn/Tetris/releases{/id}",
      "ssh_url": "git@github.com:dtrupenn/Tetris.git",
      "stargazers_url": "https://api.github.com/repos/dtrupenn/Tetris/stargazers",
      "statuses_url": "https://api.github.com/repos/dtrupenn/Tetris/statuses/{sha}",
      "subscribers_url": "https://api.github.com/repos/dtrupenn/Tetris/subscribers",
      "subscription_url": "https://api.github.com/repos/dtrupenn/Tetris/subscription",
      "tags_url": "https://api.github.com/repos/dtrupenn/Tetris/tags",
      "teams_url": "https://api.github.com/repos/dtrupenn/Tetris/teams",
      "trees_url": "https://api.github.com/repos/dtrupenn/Tetris/git/trees{/sha}",
      "clone_url": "https://github.com/dtrupenn/Tetris.git",
      "mirror_url": "git:git.example.com/dtrupenn/Tetris",
      "hooks_url": "https://api.github.com/repos/dtrupenn/Tetris/hooks",
      "svn_url": "https://svn.github.com/dtrupenn/Tetris",
      "forks": 1,
      "open_issues": 1,
      "watchers": 1,
      "has_issues": true,
      "has_projects": true,
      "has_pages": true,
      "has_wiki": true,
      "has_downloads": true,
      "archived": true,
      "disabled": true,
      "visibility": "private",
      "license": {
        "key": "mit",
        "name": "MIT License",
        "url": "https://api.github.com/licenses/mit",
        "spdx_id": "MIT",
        "node_id": "MDc6TGljZW5zZW1pdA==",
        "html_url": "https://api.github.com/licenses/mit"
      }
    }
  ]
}

304

Section titled “ 304 ”

Not modified

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error

Validation Error

object
message
required
string
documentation_url
required
string
errors
Array<object>
object
resource
string
field
string
message
string
code
required
string
index
integer
value
One of:
string
nullable
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}

503

Section titled “ 503 ”

Service unavailable

Media type application/json
object
code
string
message
string
documentation_url
string
Example generated 
{
  "code": "example",
  "message": "example",
  "documentation_url": "example"
}