Documentation

Complete reference of the API

Everything you need to know to integrate GitReposAPI into your projects. From the endpoint to the complete structure of each returned field.

Quick Start

GitReposAPI has a single endpoint that accepts requests. The only required parameter is (GitHub GETname). All other parameters are optional and serve to filter, sort and paginate the results.

1. Make a GET request

GET https://api-pearl-nine-29.vercel.app/api/github?user=USERNAME

2. Receive the formatted JSON

The response comes with three main blocks:

pagination

Pagination info: current page, total items, whether next/previous exists.

stats

Aggregated statistics: total repos, stars, forks, languages and topics.

projects

Array with formatted, filtered and sorted repositories.

3. Add filters (optional)

Combine as many parameters as you want in the query string:

# Filter by TypeScript, sort by stars, 5 per page
GET https://api-pearl-nine-29.vercel.app/api/github?user=USERNAME&language=TypeScript&sort=stars&per_page=5

# Search repos with "api" in name or description
GET https://api-pearl-nine-29.vercel.app/api/github?user=USERNAME&search=api

# Stats only (no repo list)
GET https://api-pearl-nine-29.vercel.app/api/github?user=USERNAME&stats_only=true

Documentation

Complete reference of the API

Everything you need to know to integrate the API into your projects.

Endpoint

GEThttps://api-pearl-nine-29.vercel.app/api/github

Parameter	Type	Default	Description
`user`*	string	`-`	GitHub username
`language`	string	`-`	Filter by language
`topic`	string	`-`	Filter by topic
`search`	string	`-`	Search in name or description
`sort`	string	`updated`	updated \| created \| pushed \| name \| stars \| forks \| size
`order`	string	`desc`	asc \| desc
`page`	number	`1`	Page number
`per_page`	number	`10`	Items per page (1-100)
`include_forks`	boolean	`false`	Include forks
`include_archived`	boolean	`false`	Include archived
`stats_only`	boolean	`false`	Return only statistics

How the API processes your request

Input validation

The user parameter is validated with regex (only letters, numbers and hyphens, up to 39 characters). Sort and order parameters are checked against allowed value lists. If anything is invalid, the API returns 400 with a clear message.

GitHub API fetch

The API makes internal requests to the GitHub API, fetching up to 100 repos per page and up to 10 pages (1,000 repos max). If a GITHUB_TOKEN is configured, the rate limit is 5,000 req/hour; without token, 60 req/hour.

Filtering

Forks and archived repos are removed by default (unless you pass include_forks=true or include_archived=true). Then language, topic and search filters are applied. All are case-insensitive.

Statistics calculation

Statistics are calculated on already filtered repos. If you filtered by TypeScript, stats will show only TypeScript repo data. This includes total stars, forks, languages and topics.

Sorting and pagination

Repos are sorted by the chosen field (sort) in the chosen direction (order). Then paginated according to page and per_page. The pagination object in the response indicates if more pages exist.

Response

The final JSON is returned with CORS headers, allowing any site to consume the API. Cache is 10 minutes, meaning data is refreshed every 10 minutes.

Frequently Asked Questions

Do I need authentication to use the API?

No. The API is completely public. You don't need any token or registration. Just make a GET request with the user parameter.

Does the API have usage limits?

The API works as a proxy for the GitHub API. The limit depends on server configuration: with token, 5,000 req/hour; without token, 60 req/hour. As a consumer, you don't need to worry about this.

Can I use it in commercial projects?

Yes. The API is free and open for use. You can use it in personal, commercial projects, portfolios, web apps, mobile, etc.

Is the data real-time?

Data has a 10-minute cache. If you create a new repository, it will appear in the API within 10 minutes.

Does the API work with any GitHub user?

Yes, as long as the user exists and has public repositories. Works with any valid GitHub username.

Can I use the API from any domain?

Yes. CORS is configured to accept requests from any origin (Access-Control-Allow-Origin: *). This means you can call the API directly from the frontend, without needing an intermediary backend.