openapi: 3.0.0
info:
  title: GitHub Repository API
  description: |
    The GitHub Repository API scrapes a single public github.com/{owner}/{name} repository page into structured JSON: the repository details (description, website, topics, primary language, owner, license, default branch, stars, watchers, forks, open issue and pull request counts, published security advisories, commit, branch, tag, release, contributor and "Used by" counts, creation date, the repository a fork came from, and the fork, archived, template, mirror and empty flags together with the enabled tabs and community files), the latest commit on the default branch, the latest release, languages with their share of the code, the top contributors, the project's funding links, the files and folders at the repository root, and the README as plain text and as HTML.

    Pass the repository in the `repository` parameter as `owner/name`. A github.com URL, including deep links such as `https://github.com/rails/rails/tree/main/activerecord`, or a clone URL is normalized to `owner/name`. A renamed or transferred repository resolves to its current name, which the response reports in `repository.full_name`. A repository GitHub cannot find, including one that is private, deleted, or blocked over a legal request, returns an `error`.

    An empty repository returns the details GitHub shows in its header (counts, owner and tabs) with `is_empty: true`. It has no commits, files, languages or README.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: GitHub Repository
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["github_repository"]
            default: "github_repository"
        - name: repository
          in: query
          required: true
          description: >-
            The repository to fetch, as owner/name (e.g. "rails/rails"). A github.com URL, including deep links
            to a branch, file, issue or pull request, and a clone URL such as git@github.com:rails/rails.git are
            normalized to owner/name. The owner must be 1 to 39 letters, digits, or hyphens and must not be one of
            GitHub's reserved routes such as "orgs" or "topics". The name must be 1 to 100 letters, digits,
            hyphens, underscores, or dots. Anything else returns a 400.
          schema:
            type: string
      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 when GitHub has no public repository under this name or has made it unavailable for legal reasons
        repository:
          $ref: '#/components/schemas/Repository'
        latest_commit:
          $ref: '#/components/schemas/Commit'
        latest_release:
          $ref: '#/components/schemas/Release'
        languages:
          type: array
          description: Languages GitHub detects in the repository, with their share of the code
          items:
            $ref: '#/components/schemas/Language'
        contributors:
          type: array
          description: Top contributors GitHub shows for the repository, up to 14
          items:
            $ref: '#/components/schemas/Account'
        funding:
          $ref: '#/components/schemas/Funding'
        files:
          type: array
          description: Files and folders at the repository root on the default branch, at most the first 1,000
          items:
            $ref: '#/components/schemas/FileEntry'
        readme:
          $ref: '#/components/schemas/Readme'
    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 repository
        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
        repository:
          type: string
          description: The repository requested, normalized to owner/name, which keeps the requested name of a renamed repository
    Repository:
      type: object
      required: [id, name, full_name, link, owner]
      properties:
        id:
          type: integer
          description: GitHub repository ID
        name:
          type: string
          description: Repository name
        full_name:
          type: string
          description: Current owner and repository name (e.g. rails/rails), after any rename or transfer
        link:
          type: string
          description: Repository URL
        description:
          type: string
          description: Repository description, with emoji shortcodes shown as the emoji GitHub renders
        website:
          type: string
          description: Website URL set in the repository's About section
        topics:
          type: array
          items:
            type: string
          description: Topics tagged on the repository
        language:
          type: string
          description: Primary language, the one with the largest share in languages
        language_color:
          type: string
          description: Hex color GitHub associates with the primary language
        owner:
          $ref: '#/components/schemas/Owner'
        forked_from:
          type: string
          description: Owner and name of the repository this one was forked from (e.g. pythops/impala)
        license:
          $ref: '#/components/schemas/License'
        default_branch:
          type: string
          description: Default branch name
        stars:
          type: integer
          description: Number of stargazers
        watchers:
          type: integer
          description: Number of accounts watching the repository
        forks:
          type: integer
          description: Number of forks
        open_issues_count:
          type: integer
          description: Number of open issues GitHub counts on the Issues tab, which reads 5001 once there are more than 5,000
        is_open_issues_count_capped:
          type: boolean
          description: Whether GitHub stopped counting open issues past 5,000, making open_issues_count a lower bound
        open_pull_requests_count:
          type: integer
          description: Number of open pull requests GitHub counts on the Pull requests tab, which reads 5001 once there are more than 5,000
        is_open_pull_requests_count_capped:
          type: boolean
          description: Whether GitHub stopped counting open pull requests past 5,000, making open_pull_requests_count a lower bound
        security_advisories_count:
          type: integer
          description: Number of published security advisories
        commits_count:
          type: integer
          description: Number of commits on the default branch
        files_count:
          type: integer
          description: Number of files and folders at the repository root on the default branch
        branches_count:
          type: integer
          description: Number of branches
        tags_count:
          type: integer
          description: Number of tags
        releases_count:
          type: integer
          description: Number of releases
        contributors_count:
          type: integer
          description: Number of contributors
        used_by_count:
          type: integer
          description: Number of repositories GitHub lists as depending on this one ("Used by")
        created_at:
          type: string
          format: date-time
          description: When the repository was created
        is_fork:
          type: boolean
          description: Whether the repository is a fork
        is_archived:
          type: boolean
          description: Whether the repository is archived and read-only
        is_template:
          type: boolean
          description: Whether the repository is a template repository
        is_mirror:
          type: boolean
          description: Whether the repository is a mirror of another repository
        is_empty:
          type: boolean
          description: Whether the repository has no commits
        has_issues:
          type: boolean
          description: Whether the Issues tab is enabled
        has_pull_requests:
          type: boolean
          description: Whether the Pull requests tab is enabled
        has_discussions:
          type: boolean
          description: Whether the Discussions tab is enabled
        has_wiki:
          type: boolean
          description: Whether the repository page shows a Wiki tab, which GitHub shows once the wiki has pages
        has_projects:
          type: boolean
          description: Whether the Projects tab is enabled
        has_code_of_conduct:
          type: boolean
          description: Whether the repository has a code of conduct
        has_contributing_guide:
          type: boolean
          description: Whether the repository has a contributing guide
        has_security_policy:
          type: boolean
          description: Whether the repository has a security policy
        has_citation:
          type: boolean
          description: Whether the repository has a citation file
    Owner:
      type: object
      required: [login, id, type, link, avatar_url]
      properties:
        login:
          type: string
          description: Owner username or organization login
        id:
          type: integer
          description: Owner account ID
        type:
          type: string
          enum: ["User", "Organization"]
          description: Whether the owner is a user or an organization
        link:
          type: string
          description: Owner profile URL
        avatar_url:
          type: string
          description: Owner avatar image URL
    License:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: License name (e.g. MIT License), or Other when GitHub cannot classify the license
        spdx_id:
          type: string
          description: SPDX identifier (e.g. MIT), or NOASSERTION when GitHub cannot classify the license
        link:
          type: string
          description: URL of the license file on the default branch
    Commit:
      type: object
      description: The latest commit on the default branch
      required: [sha, message, link, date, authors]
      properties:
        sha:
          type: string
          description: Full commit SHA
        message:
          type: string
          description: Commit message as GitHub renders it on the page, with the headline separated from the body by a blank line
        link:
          type: string
          description: Commit URL
        date:
          type: string
          format: date-time
          description: Commit date in UTC
        authors:
          type: array
          description: Commit authors, including co-authors
          items:
            $ref: '#/components/schemas/CommitPerson'
        committer:
          $ref: '#/components/schemas/CommitPerson'
        checks:
          $ref: '#/components/schemas/CommitChecks'
    CommitChecks:
      type: object
      description: CI checks for the commit
      required: [state]
      properties:
        state:
          type: string
          description: Combined state of the commit's checks as GitHub reports it (e.g. success, failure, pending)
    CommitPerson:
      type: object
      description: A commit author or committer, who may have no GitHub account
      properties:
        login:
          type: string
          description: GitHub login
        name:
          type: string
          description: Display name
        id:
          type: integer
          description: GitHub account ID
        link:
          type: string
          description: Profile URL, or the app page of a GitHub App such as dependabot[bot]
        avatar_url:
          type: string
          description: Avatar image URL
    Release:
      type: object
      description: The latest release
      required: [name, tag, link, published_at]
      properties:
        name:
          type: string
          description: Release title
        tag:
          type: string
          description: Git tag of the release
        link:
          type: string
          description: Release URL
        published_at:
          type: string
          format: date-time
          description: When the release was published
    Language:
      type: object
      required: [name, percentage]
      properties:
        name:
          type: string
          description: Language name
        percentage:
          type: number
          description: Share of the repository's code in this language, in percent
        color:
          type: string
          description: Hex color GitHub associates with the language
    Account:
      type: object
      required: [login, link, avatar_url]
      properties:
        login:
          type: string
          description: GitHub login
        name:
          type: string
          description: Display name
        id:
          type: integer
          description: GitHub account ID
        link:
          type: string
          description: Profile URL, or the app page of a GitHub App such as dependabot[bot]
        avatar_url:
          type: string
          description: Avatar image URL
    Funding:
      type: object
      description: The project's funding options from its "Sponsor this project" section
      properties:
        github_sponsors:
          type: array
          description: Accounts that accept GitHub Sponsors for this project
          items:
            $ref: '#/components/schemas/Account'
        links:
          type: array
          description: Other funding links from the repository's FUNDING file
          items:
            $ref: '#/components/schemas/FundingLink'
    FundingLink:
      type: object
      required: [platform, label, link]
      properties:
        platform:
          type: string
          description: Funding platform as GitHub names it (e.g. open_collective, patreon, custom)
        label:
          type: string
          description: Label GitHub shows for the link
        link:
          type: string
          description: Funding URL
    FileEntry:
      type: object
      required: [name, path, type]
      properties:
        name:
          type: string
          description: Entry name, where GitHub joins a folder that holds only another folder into one path (e.g. .github/workflows)
        path:
          type: string
          description: Path from the repository root
        type:
          type: string
          description: Entry type as GitHub reports it (e.g. directory, file, symlink_file, submodule)
        link:
          type: string
          description: URL of the entry on the default branch
    Readme:
      type: object
      description: The repository README
      properties:
        text:
          type: string
          description: README text with whitespace collapsed
        html:
          type: string
          description: README rendered as HTML by GitHub, with relative links and image sources made absolute
        link:
          type: string
          description: URL of the README file on the default branch
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message