Search Endpoints - Better Hub

Search Repositories

Search for repositories across GitHub.

GET /api/search-repos

Query Parameters

string

required

Search query using GitHub search syntaxExamples:

tetris language:assembly - Assembly Tetris implementations
stars:>1000 - Repositories with over 1000 stars
user:octocat - Repositories owned by octocat
org:github - Repositories in the GitHub organization
topic:react - Repositories tagged with react

language

string

Filter by programming language (e.g., “javascript”, “python”, “typescript”)This parameter is automatically added to the query as language:{value}

page

number

default:"1"

Page number for pagination (minimum: 1)

per_page

number

default:"30"

Number of results per page (minimum: 1, maximum: 100)

Response

total_count

number

Total number of repositories matching the search

incomplete_results

boolean

Whether the search results are incomplete

items

object[]

Array of repository objects

Show Repository Object (selected fields)

number

Repository ID

name

string

Repository name

full_name

string

Full name (owner/repo)

description

string | null

Repository description

owner

object

Owner information (login, avatar_url, etc.)

html_url

string

GitHub URL to the repository

language

string | null

Primary programming language

stargazers_count

number

Number of stars

forks_count

number

Number of forks

open_issues_count

number

Number of open issues

topics

string[]

Repository topics/tags

created_at

string

ISO 8601 timestamp

updated_at

string

ISO 8601 timestamp

Example Request

curl "https://yourdomain.com/api/search-repos?q=tetris&language=javascript&per_page=10"

Example Response

{
  "total_count": 1247,
  "incomplete_results": false,
  "items": [
    {
      "id": 123456789,
      "name": "awesome-ml",
      "full_name": "octocat/awesome-ml",
      "description": "A curated list of machine learning resources",
      "owner": {
        "login": "octocat",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif"
      },
      "html_url": "https://github.com/octocat/awesome-ml",
      "language": "Python",
      "stargazers_count": 5432,
      "forks_count": 891,
      "open_issues_count": 23,
      "topics": ["machine-learning", "python", "awesome-list"],
      "created_at": "2020-05-10T12:00:00Z",
      "updated_at": "2024-01-15T08:30:00Z"
    }
  ]
}

Search Code

Search for code across GitHub repositories.

GET /api/search-code

Query Parameters

string

required

Search query using GitHub code search syntaxExamples:

addClass in:file language:js repo:jquery/jquery
function path:app/public language:javascript
import React extension:tsx

language

string

Filter by programming languageThis parameter is automatically added to the query as language:{value}

page

number

default:"1"

Page number for pagination (minimum: 1)

per_page

number

default:"30"

Number of results per page (minimum: 1, maximum: 100)

Response

total_count

number

Total number of code matches

incomplete_results

boolean

Whether the search results are incomplete

items

object[]

Array of code match objects

Show Code Match Object

name

string

File name

path

string

Full file path

sha

string

Git SHA hash

url

string

API URL for the file

html_url

string

GitHub URL to view the file

repository

object

Repository information (name, full_name, owner, etc.)

text_matches

object[]

Highlighted text matches (when available)

Example Request

curl "https://yourdomain.com/api/search-code?q=fetch+in:file&language=typescript"

Example Response

{
  "total_count": 3421,
  "incomplete_results": false,
  "items": [
    {
      "name": "App.tsx",
      "path": "src/components/App.tsx",
      "sha": "abc123def456",
      "url": "https://api.github.com/repositories/123456789/contents/src/components/App.tsx",
      "html_url": "https://github.com/octocat/my-app/blob/main/src/components/App.tsx",
      "repository": {
        "id": 123456789,
        "name": "my-app",
        "full_name": "octocat/my-app",
        "owner": {
          "login": "octocat"
        }
      },
      "text_matches": [
        {
          "fragment": "const [state, setState] = useState(0);",
          "matches": [
            {
              "text": "useState",
              "indices": [26, 34]
            }
          ]
        }
      ]
    }
  ]
}

Search Users

Search for users across GitHub.

GET /api/search-users

Query Parameters

string

required

Search query for GitHub usernames or user informationExamples:

tom - Users with “tom” in their username
fullname:tom - Users with “tom” in their full name
location:san francisco - Users in San Francisco

org

string

Organization name to prioritize in search resultsWhen provided, the endpoint performs two searches:

Users in the specified organization matching the query
Global users matching the query

Results are merged with org members appearing first.

per_page

number

default:"30"

Number of results per page (minimum: 1, maximum: 100)

Response

total_count

number

Total number of users matching the search

items

object[]

Array of user objects

Show User Object

Username

number

User ID

avatar_url

string

Avatar image URL

html_url

string

GitHub profile URL

type

string

User type (“User” or “Organization”)

Example Request

curl "https://yourdomain.com/api/search-users?q=octocat"

Example Response

{
  "total_count": 42,
  "items": [
    {
      "login": "octocat",
      "id": 583231,
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "html_url": "https://github.com/octocat",
      "type": "User"
    },
    {
      "login": "octocatdev",
      "id": 1234567,
      "avatar_url": "https://avatars.githubusercontent.com/u/1234567",
      "html_url": "https://github.com/octocatdev",
      "type": "User"
    }
  ]
}

Example Response (with org parameter)

When the org parameter is provided, organization members appear first:

{
  "total_count": 15,
  "items": [
    {
      "login": "john-from-github",
      "id": 111111,
      "avatar_url": "https://avatars.githubusercontent.com/u/111111",
      "html_url": "https://github.com/john-from-github",
      "type": "User"
    },
    {
      "login": "john-public",
      "id": 222222,
      "avatar_url": "https://avatars.githubusercontent.com/u/222222",
      "html_url": "https://github.com/john-public",
      "type": "User"
    }
  ]
}

Common Error Responses

Show 400 Bad Request

{
  "error": "Missing query parameter"
}

The q query parameter is required for all search endpoints.

Show 401 Unauthorized

{
  "error": "Not authenticated"
}

User is not authenticated. All search endpoints require authentication.

Rate Limiting

All search endpoints are subject to GitHub API rate limits:

Authenticated requests: 5,000 requests per hour
Search API specific: 30 requests per minute

The GitHub integration in /lib/github.ts includes comprehensive rate limit handling:

GitHubRateLimitError exception with resetAt, limit, and used properties
Automatic detection via HTTP 403/429 status codes
Rate limit headers parsed from x-ratelimit-* headers

Notes

All search endpoints require authentication via session cookies
Maximum 100 results per page across all endpoints
Page numbers start at 1 and are normalized (values < 1 become 1)
The /api/search-code endpoint includes text match highlighting via the Accept: application/vnd.github.text-match+json header
The /api/search-users endpoint supports organization-scoped search with fallback to global results
All timestamps are in ISO 8601 format (UTC)

​Search Repositories

​Query Parameters

​Response

​Example Request

​Example Response

​Search Code

​Query Parameters

​Response

​Example Request

​Example Response

​Search Users

​Query Parameters

​Response

​Example Request

​Example Response

​Example Response (with org parameter)

​Common Error Responses

​Rate Limiting

​Notes

Search Repositories

Query Parameters

Response

Example Request

Example Response

Search Code

Query Parameters

Response

Example Request

Example Response

Search Users

Query Parameters

Response

Example Request

Example Response

Example Response (with org parameter)

Common Error Responses

Rate Limiting

Notes