openapi: 3.0.0 info: title: GitHub Search API description: | The GitHub Search API scrapes search results from github.com/search. A single engine covers every GitHub search vertical, selected with the `type` parameter: `repositories` (default), `users`, `issues`, `pull_requests`, `commits`, `topics`, `discussions`, `packages`, `wikis`, and `marketplace`. Each type returns its own `organic_results` shape. The query (`q`) accepts GitHub's full search qualifier syntax (e.g. `language:ruby stars:>1000 topic:cli` for repositories, or `is:pr is:merged` for issues). GitHub only exposes the first 1,000 results for any query (10 per page, up to page 100); `search_information.total_results` reports the true total match count. The available `sort` values depend on `type`: - `repositories`: `stars`, `forks`, `help_wanted_issues`, `updated` - `users`: `followers`, `repositories`, `joined` - `issues` / `pull_requests`: `created`, `updated`, `comments`, `reactions`, `interactions` - `commits`: `author_date`, `committer_date` - `discussions`: `updated`, `comments`, `reactions`, `interactions` - `packages`: `updated`, `created`, `downloads` - `wikis`: `updated` - `marketplace`: `updated`, `created`, `popularity` - `topics`: not sortable version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: GitHub Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Search engine to use schema: type: string enum: ["github_search"] default: "github_search" - name: q in: query required: true description: 'Search query. Accepts GitHub search qualifiers, e.g. "language:ruby stars:>1000 topic:cli".' schema: type: string - name: type in: query required: false description: The GitHub search vertical to query. Determines the shape of each organic result. schema: type: string enum: ["repositories", "users", "issues", "pull_requests", "commits", "topics", "discussions", "packages", "wikis", "marketplace"] default: "repositories" - name: sort in: query required: false description: | Sorts the results by the given field (omit for "Best match" relevance). Valid values depend on type: repositories [stars, forks, help_wanted_issues, updated]; users [followers, repositories, joined]; issues and pull_requests [created, updated, comments, reactions, interactions]; commits [author_date, committer_date]; discussions [updated, comments, reactions, interactions]; packages [updated, created, downloads]; wikis [updated]; marketplace [updated, created, popularity]; topics is not sortable. schema: type: string enum: ["stars", "forks", "help_wanted_issues", "updated", "followers", "repositories", "joined", "created", "comments", "reactions", "interactions", "author_date", "committer_date", "downloads", "popularity"] - name: order in: query required: false description: Sort direction. Requires sort — sending order on its own is rejected with a 400 validation error, not ignored. Defaults to descending when sort is set. schema: type: string enum: ["asc", "desc"] - name: page in: query required: false description: Page number to retrieve. GitHub serves 10 results per page, up to page 100 (only the first 1,000 results are retrievable). schema: type: integer minimum: 1 maximum: 100 default: 1 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' error: type: string description: Error message if the search failed search_information: $ref: '#/components/schemas/SearchInformation' topic: $ref: '#/components/schemas/CuratedTopic' organic_results: type: array description: Results for the selected type. The item shape is one of the per-type schemas below. items: oneOf: - $ref: '#/components/schemas/RepositoryResult' - $ref: '#/components/schemas/UserResult' - $ref: '#/components/schemas/IssueResult' - $ref: '#/components/schemas/CommitResult' - $ref: '#/components/schemas/TopicResult' - $ref: '#/components/schemas/DiscussionResult' - $ref: '#/components/schemas/PackageResult' - $ref: '#/components/schemas/WikiResult' - $ref: '#/components/schemas/MarketplaceResult' pagination: $ref: '#/components/schemas/Pagination' language_filters: type: array description: Languages facet, present on the repositories, users and pull_requests verticals. items: $ref: '#/components/schemas/LanguageFilter' package_type_filters: type: array description: Package type facet, present on the packages vertical. items: $ref: '#/components/schemas/PackageTypeFilter' SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: GitHub URL for this search html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Search engine used type: type: string description: The GitHub search vertical queried q: type: string description: Search query sort: type: string description: Field the results are sorted by order: type: string description: Sort direction page: type: string description: Page number SearchInformation: type: object required: [query, total_results] properties: query: type: string description: The search query that produced these results total_results: type: integer description: Total number of results GitHub matched (only the first 1,000 are retrievable) page: type: integer description: Current page number time_taken: type: number description: Time GitHub took to run the search, in seconds incomplete_results: type: boolean description: Present and true only when GitHub flags the result set as incomplete (search timed out or was truncated); omitted otherwise RepositoryResult: type: object description: Organic result when type=repositories. required: [position, id, name, full_name, link, stars] additionalProperties: false properties: position: type: integer description: Result position on the page id: type: integer description: GitHub repository ID name: type: string description: Repository name full_name: type: string description: Owner and repository name (e.g. rails/rails) link: type: string description: Repository URL description: type: string description: >- Repository description as GitHub renders it in search results, which is the truncated form rather than the repository's full description. Long descriptions are cut at roughly 140 characters and end with a Unicode ellipsis (…). owner: $ref: '#/components/schemas/Owner' stars: type: integer description: Number of stargazers language: type: string description: Primary programming language language_color: type: string description: Hex color GitHub associates with the language topics: type: array items: type: string description: Topics tagged on the repository good_first_issue_issues_count: type: integer description: Number of issues labelled "good first issue" help_wanted_issues_count: type: integer description: Number of issues labelled "help wanted" visibility: type: string description: Repository visibility (e.g. public) updated_at: type: string format: date-time description: When the repository was last updated is_archived: type: boolean description: Whether the repository is archived is_mirror: type: boolean description: Whether the repository is a mirror is_sponsorable: type: boolean description: Whether the repository owner can be sponsored has_funding_file: type: boolean description: Whether the repository has a funding file has_issues: type: boolean description: Whether issues are enabled on the repository UserResult: type: object description: Organic result when type=users. required: [position, login, link] additionalProperties: false properties: position: type: integer description: Result position on the page login: type: string description: User or organization login name: type: string description: Display name id: type: integer description: GitHub account ID link: type: string description: Profile URL avatar_url: type: string description: Full-size avatar image URL bio: type: string description: Profile bio location: type: string description: Profile location followers: type: integer description: Follower count repos: type: integer description: Public repository count is_sponsorable: type: boolean description: Whether the account can be sponsored IssueResult: type: object description: Organic result when type=issues or type=pull_requests. The issues vertical folds in pull requests (is_pull_request tells them apart); the pull_requests vertical returns only PRs. required: [position, number, title, link, state] additionalProperties: false properties: position: type: integer description: Result position on the page id: type: integer description: Issue or pull request ID number: type: integer description: Issue or pull request number within the repository title: type: string description: Title snippet: type: string description: Matched text snippet link: type: string description: URL to the issue (/issues/) or pull request (/pull/) state: type: string description: State (e.g. open, closed, merged) state_reason: type: string description: Reason for the current state (e.g. completed, not_planned) is_pull_request: type: boolean description: Whether this result is a pull request is_merged: type: boolean description: Whether the pull request was merged reviewable_state: type: string description: Review state of the pull request comments: type: integer description: Number of comments labels: type: array items: type: string description: Label names applied author: $ref: '#/components/schemas/Actor' created_at: type: string format: date-time description: When the issue or pull request was created repository: $ref: '#/components/schemas/ResultRepository' CommitResult: type: object description: Organic result when type=commits. required: [position, sha, link] additionalProperties: false properties: position: type: integer description: Result position on the page sha: type: string description: Commit SHA subject: type: string description: First line of the commit message message: type: string description: Full commit message snippet: type: string description: Matched excerpt from the commit body, with GitHub's highlight markup stripped link: type: string description: Commit URL author_date: type: string format: date-time description: Author date of the commit authors: type: array items: $ref: '#/components/schemas/Actor' description: Commit authors (commits can be co-authored) committer: $ref: '#/components/schemas/Actor' repository: $ref: '#/components/schemas/ResultRepository' verification: $ref: '#/components/schemas/CommitVerification' checks: $ref: '#/components/schemas/CommitChecks' issue_references: type: array items: $ref: '#/components/schemas/IssueReference' description: Issues and pull requests the commit links to TopicResult: type: object description: Organic result when type=topics. required: [position, name, link] additionalProperties: false properties: position: type: integer description: Result position on the page id: type: integer description: Topic ID name: type: string description: Topic slug display_name: type: string description: Human-readable topic name (curated topics only) link: type: string description: URL of the topic page on GitHub description: type: string description: Short topic description (curated topics only) created_by: type: string description: Creator or originator of the topic released: type: string description: >- When the subject of the topic was first released, as free-form text copied from GitHub. Not machine-parseable: precision varies between month-year and full-date forms within the same response (e.g. "September 2016", "March 2006", "January 05, 2010"). stargazer_count: type: integer description: Number of users who starred the topic repository_count: type: integer description: GitHub's displayed repository count for the topic is_repository_count_approximate: type: boolean description: Whether repository_count is rounded down (over GitHub's fetch limit) applied_count: type: integer description: Exact number of topic applications (>= repository_count) aliases: type: array items: type: string description: Alternate names for the topic related: type: array items: type: string description: Related topic slugs logo: type: string description: Topic logo image URL github_url: type: string description: Canonical repository associated with the topic wikipedia_url: type: string description: Related Wikipedia article URL is_curated: type: boolean description: Whether the topic is curated by GitHub is_featured: type: boolean description: Whether the topic is featured DiscussionResult: type: object description: Organic result when type=discussions. required: [position, number, title, link] additionalProperties: false properties: position: type: integer description: Result position on the page id: type: integer description: Discussion ID number: type: integer description: Discussion number within the repository title: type: string description: Discussion title snippet: type: string description: Matched body snippet body: type: string description: Full text of the opening discussion post link: type: string description: URL to the discussion comments: type: integer description: Number of comments author: $ref: '#/components/schemas/Actor' created_at: type: string format: date-time description: When the discussion was created updated_at: type: string format: date-time description: When the discussion was last updated repository: $ref: '#/components/schemas/ResultRepository' PackageResult: type: object description: Organic result when type=packages. required: [position, id, name, link] additionalProperties: false properties: position: type: integer description: Result position on the page id: type: string description: > Package ID. Usually a bare numeric string (e.g. 3207650); container packages carry a registry prefix (e.g. rms-1243839). Always compare as a string, never parse as an integer. name: type: string description: Package name link: type: string description: URL to the package page package_type: type: string description: Registry type (e.g. maven, npm, container, nuget) downloads: type: integer description: Download count summary: type: string description: Package description latest_version: type: string description: Most recently published version latest_version_published_at: type: string format: date-time description: When the latest version was published latest_version_digest: type: string description: Content digest of the latest version, e.g. sha256:604f18... (container packages only) topics: type: array items: type: string description: Topics tagged on the package visibility: type: string description: Package visibility (public or private) created_at: type: string format: date-time description: When the package was created updated_at: type: string format: date-time description: When the package was last updated repository: $ref: '#/components/schemas/ResultRepository' WikiResult: type: object description: Organic result when type=wikis. required: [position, id, title, link] additionalProperties: false properties: position: type: integer description: Result position on the page id: type: string description: Content SHA of the wiki page (a hex string, not a numeric id) title: type: string description: Wiki page title snippet: type: string description: Matched body snippet body: type: string description: Full text of the wiki page. Not a snippet - pages average ~8 KB and can exceed 48 KB, so a 10-result wikis response is roughly 95 KB. link: type: string description: URL to the wiki page filename: type: string description: Source filename of the wiki page format: type: string description: Markup format (e.g. markdown, asciidoc) updated_at: type: string format: date-time description: When the wiki page was last updated repository: $ref: '#/components/schemas/ResultRepository' MarketplaceResult: type: object description: Organic result when type=marketplace. The vertical mixes app listings, GitHub Actions and GitHub Models entries, told apart by listing_type. required: [position, id, name, link] additionalProperties: false properties: position: type: integer description: Result position on the page id: oneOf: - type: integer - type: string description: >- Listing ID. An integer for app and Action listings. For "model" entries it is the registry asset URI (a string), which embeds a version segment and therefore changes whenever GitHub publishes a new version of the model — use registry plus slug as the stable key. listing_type: type: string description: >- One of "marketplace_listing" (apps/tools), "repository_action" (GitHub Actions) or "model" (GitHub Models catalog entries). Model entries carry the catalog fields below instead of the app listing fields. name: type: string description: Listing name slug: type: string description: Listing slug link: type: string description: >- URL to the listing or action page. For "model" entries this is the GitHub Models catalog page, which requires a signed-in GitHub session and answers 404 to anonymous clients. state: type: string description: Listing review state (e.g. verified) description: type: string description: Short description full_description: type: string description: Full description extended_description: type: string description: >- Long-form setup and usage guide for the listing, in Markdown. Runs to a few hundred to a few thousand characters. App listings only. listable_type: type: string description: >- The kind of app backing the listing, either "Integration" (a GitHub App) or "OauthApplication" (an OAuth app). App listings only. primary_category: type: string description: Primary category secondary_category: type: string description: Secondary category installation_count: type: integer description: Number of installations (app listings only) stars: type: integer description: Star count (Action listings) dependents_count: type: integer description: Number of dependent repositories (Action listings) repository_id: type: integer description: Source repository ID (Action listings only) logo: type: string description: Listing logo image URL owner_login: type: string description: Listing owner login pricing_url: type: string description: External pricing URL (app listings) company_url: type: string description: External company URL (app listings) documentation_url: type: string description: External documentation URL (app listings) support_url: type: string description: External support URL (app listings). Publisher free-text — some listings supply an email address rather than a URL. status_url: type: string description: External status-page URL (app listings) installation_url: type: string description: External installation/sign-in URL (app listings) learn_more_url: type: string description: External "learn more" URL (app listings) privacy_policy_url: type: string description: External privacy policy URL (app listings) tos_url: type: string description: External terms-of-service URL (app listings) is_free: type: boolean description: Whether the listing is free is_verified_owner: type: boolean description: Whether the listing owner is verified is_recommended: type: boolean description: Whether GitHub recommends the listing publisher: type: string description: Model publisher, on "model" entries only (e.g. Meta) publisher_display_name: type: string description: >- Hosting brand for the model, on "model" entries only. Distinct from publisher, which names the model's creator (e.g. publisher "OpenAI" hosted as "Azure OpenAI Service"). registry: type: string description: Model registry, on "model" entries only (e.g. azureml-meta) task: type: string description: Task the model serves, on "model" entries only (e.g. chat-completion) tags: type: array description: Model capability tags, on "model" entries only items: type: string max_input_tokens: type: integer description: Maximum input context in tokens, on "model" entries only max_output_tokens: type: integer description: Maximum output length in tokens, on "model" entries only CuratedTopic: type: object description: Curated topic knowledge panel, present on the repositories vertical only when the query matches a GitHub topic name (e.g. q=react). required: [name, display_name] properties: name: type: string description: Topic slug display_name: type: string description: Human-readable topic name description: type: string description: Short topic description created_by: type: string description: Creator or originator of the topic released: type: string description: >- When the subject of the topic was first released, as free-form text copied from GitHub. Not machine-parseable: precision varies between month-year and full-date forms (e.g. "March 2013", "September 2016", "January 05, 2010"). stargazer_count: type: integer description: Number of users who starred the topic applied_count: type: integer description: Number of repositories tagged with the topic repository_count: type: integer description: Repository count for the topic link: type: string description: URL of the topic page on GitHub github_url: type: string description: Canonical repository associated with the topic logo: type: string description: Topic logo image URL wikipedia_url: type: string description: Related Wikipedia article URL aliases: type: array items: type: string description: Alternate names for the topic related: type: array items: type: string description: Related topic slugs is_curated: type: boolean description: Whether the topic is curated by GitHub is_featured: type: boolean description: Whether the topic is featured Owner: type: object required: [login] properties: login: type: string description: Owner username or organization login id: type: integer description: Owner ID type: type: string enum: ["User", "Organization"] description: Whether the owner is a user or an organization. Emitted on the repositories vertical only — the other verticals' embed carries no User/Organization discriminator. avatar_url: type: string description: Owner avatar image URL Actor: type: object description: A GitHub actor (issue/PR author, or commit author/committer). properties: login: type: string description: Actor login id: type: integer description: Actor ID name: type: string description: Actor display name avatar_url: type: string description: Actor avatar image URL ResultRepository: type: object description: The repository a commit, issue, pull request, discussion, package, or wiki belongs to. properties: id: type: integer description: Repository ID name: type: string description: Repository name full_name: type: string description: Owner and repository name (e.g. rails/rails) owner: $ref: '#/components/schemas/Owner' updated_at: type: string format: date-time description: When the repository was last updated has_issues: type: boolean description: Whether issues are enabled on the repository CommitVerification: type: object description: Commit signature verification summary. properties: is_verified: type: boolean description: Whether the signature is verified is_signed: type: boolean description: Whether the commit is signed status: type: string description: Verification status (e.g. verified, unsigned) reason: type: string description: Verification reason signature_type: type: string description: > GitHub's signature class name, e.g. GpgSignature. CamelCase, not a lowercase algorithm name. Null on unsigned commits. key_id: type: string description: Signing key ID is_signed_by_github: type: boolean description: Whether GitHub signed the commit signer_login: type: string description: Login of the signer CommitChecks: type: object description: CI status for the commit. properties: state: type: string description: Rollup check state (e.g. success, failure, pending) summary: type: string description: Human-readable checks summary runs: type: array items: $ref: '#/components/schemas/CheckRun' description: Individual check runs CheckRun: type: object properties: name: type: string description: Check run name state: type: string description: Check run state context: type: string description: Extra detail for the check run. GitHub supplies either additional_context or a description depending on the CI provider — the parser emits whichever is present. link: type: string description: URL to the check run details IssueReference: type: object description: An issue or pull request a commit links to. properties: number: type: integer description: Issue or pull request number title: type: string description: Title state: type: string description: State is_pull_request: type: boolean description: Whether the reference is a pull request is_merged: type: boolean description: Whether the pull request was merged link: type: string description: Permalink to the issue or pull request Pagination: type: object required: [current] properties: current: type: integer description: Current page number total_pages: type: integer description: Number of retrievable pages (capped at 100 by GitHub) next: type: string description: Next page URL previous: type: string description: Previous page URL LanguageFilter: type: object required: [name, query] properties: name: type: string description: Language name color: type: string description: Hex color GitHub associates with the language query: type: string description: Qualifier to append to q to filter by this language (e.g. language:TypeScript) PackageTypeFilter: type: object required: [name, query] properties: name: type: string description: Package registry type (npm, container, maven, nuget, rubygems) query: type: string description: Qualifier to append to q to filter by this package type (e.g. package_type:npm) ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong