GitBanners API docs

Quick start

Put a GitHub login, or owner/repo, in the path and add .svg or .png:

https://gitbanners.com/markeljan.svg
https://gitbanners.com/vercel/next.js/contributors.png?theme=dracula

In a README, wrap the image in a link to its page:

markdown
[![GitHub banner for markeljan](https://gitbanners.com/markeljan.svg)](https://gitbanners.com/markeljan)

Software should ask the API instead of building URLs by hand. It checks that the target exists and answers with the image URLs and the embed code:

bash
curl "https://gitbanners.com/api/v1/banner?target=vercel/next.js"

URL patterns

URLs are shaped like GitHub's own. The same path is a page, an image or a Markdown document, depending on its ending.

• {owner} is the login of a GitHub user or organization. It is not case-sensitive; links are printed in lower case.
• A second segment that is the id of a profile preset (overview, activity, stats, repos, languages, streak, wrapped, card) selects that preset. Anything else is read as a repository name. A repository that shares its name with a preset is written with its own preset: /{owner}/{repo}/overview.svg.
• A login that collides with a route of this site is written with @: /@docs.svg is the banner of the GitHub account named docs.
• .svg and .png are honoured on the last segment only, so /vercel/next.js is a repository and not a file.
• Options go in the query string and are the same for every form: ?theme=dracula&size=og. A saved banner keeps its own options and ignores them.

Image responses

A well-formed image URL always answers 200 with an image. A README shows a broken-image icon for any other status, so an unknown login or a GitHub outage is drawn as a small card instead, and the X-Banner-State header says which it was.

• Cache-Control: public, max-age=600 lets browsers and GitHub's image proxy reuse an image for 10 minutes. The CDN refreshes its own copy every 15 minutes, serves the previous one while it does, and keeps serving it for up to 7 days if GitHub cannot be reached.
• Access-Control-Allow-Origin: * and Cross-Origin-Resource-Policy: cross-origin: a banner can be embedded, fetched and drawn on a canvas from any site.
• SVG answers carry a Content-Security-Policy that allows no scripts and no external resources. Avatars are inlined, so the image needs nothing from the network.
• ?scale=1, 2 or 3 sets the pixel density of a PNG. README banners default to 2, the fixed social sizes to 1. ?download=1 asks the browser to save the file.
• A URL that cannot be a banner answers 404 and no image: as a problem (not_found) when a login or repository name is too long or malformed or the path has more than three segments, and as the HTML 404 page when the first segment is a route of this site or contains a character no GitHub login can.

Content negotiation

The bare URL of a banner page answers with what the client asks for.

Negotiated answers carry Vary: Accept. Embed snippets always use the explicit .svg or .png URL, which answers the same for every client.

Embedding

Markdown for a README. The image links to its page, where a reader can copy the banner for themselves:

markdown
[![GitHub banner for markeljan](https://gitbanners.com/markeljan.svg)](https://gitbanners.com/markeljan)

HTML that follows the reader's light or dark theme on GitHub:

html
<a href="https://gitbanners.com/markeljan">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://gitbanners.com/markeljan.svg?theme=github-dark">
    <img src="https://gitbanners.com/markeljan.svg?theme=github-light" alt="GitHub banner for markeljan">
  </picture>
</a>

GitHub data is refreshed every 15 minutes, the CDN copy of an image every 15 minutes, and GitHub's image proxy keeps its copy for 10 minutes. A banner in a README therefore trails GitHub by less than an hour.

Variants and themes

A banner is a preset (what it shows), a size (the canvas), a theme (the colours) and optional overrides. GET /api/v1/options returns everything in this section as JSON.

Presets

There are 16 presets. The kind of the target decides which ones apply; an id that does not exist for the kind falls back to its default.

Sizes

width (320 to 3000) and height (120 to 3000) set a custom canvas in pixels. A custom width without a height keeps the automatic height.

Themes

There are 24 themes. The default is github-dark, and an unknown id falls back to it. Every colour of a theme can be overridden with the parameters below.

Query parameters

Parsing is lenient on purpose: an unknown parameter is ignored and an invalid value falls back to the default, so a typo never breaks an image that is already embedded somewhere. The parameters marked Pro are honoured on saved banners of Pro accounts only.

REST API

The JSON API lives under https://gitbanners.com/api/v1. It is read-only (GET, HEAD and OPTIONS), needs no key, and sends Access-Control-Allow-Origin: *, so a browser can call it from any site. /openapi.json describes it in OpenAPI 3.1.

Answers are JSON and may be cached: Cache-Control: public, max-age=60 for account and repository data, max-age=300 for search and the options catalog. Every answer, errors included, carries the rate limit headers and a Link header to the OpenAPI description, the API catalog and this page.

List presets, themes, sizes and parameters

GET /api/v1/options. Everything a banner URL can say: the presets for users, organizations and repositories, the colour themes with their palettes, the canvas sizes, the fonts and every documented query parameter. Takes no parameters, so it also works as a first call to check that the API is reachable.

bash
curl "https://gitbanners.com/api/v1/options"

Returns: An OptionsCatalog.

Search accounts and repositories by prefix

GET /api/v1/search. Typeahead over GitHub: accounts whose login starts with the query, or the repositories of one owner when the query is written as owner/prefix. The query must be 2 to 140 characters long.

• q (query, required): The start of a login such as verc, or owner/prefix such as vercel/ne for repositories.

bash
curl "https://gitbanners.com/api/v1/search?q=verc"

Returns: A SearchResult: the query and a list of suggestions.

Describe one banner: URLs, embed code, size

GET /api/v1/banner. The image URLs, embed snippets, dimensions and alt text of one banner, after checking with GitHub that the target exists. Takes the same option parameters as the image URLs and answers with the canonical form of the banner: GitHub's own capitalisation, default values left out of the query.

• target (query, required): A GitHub login such as vercel, or a repository as owner/name such as vercel/next.js. A github.com URL works too.
• preset (query, optional): Preset id for the kind of target. An id that does not exist for the kind falls back to its default preset.
• Every banner parameter as a query parameter, such as theme, size or accent.

bash
curl "https://gitbanners.com/api/v1/banner?target=vercel/next.js&preset=contributors&theme=dracula"

Returns: A BannerDescription.

Get a user or an organization

GET /api/v1/owners/{login}. A GitHub user or organization as normalized JSON: profile, statistics, the contribution calendar with streaks, top repositories and languages. The kind field says which of the two it is.

• login (path, required): GitHub user or organization login.
• year (query, optional): Calendar year for a user's contribution calendar and statistics, from 2008 to the current year. Omit it for the last 12 months.
• view (query, optional): preview answers faster for users, from one upstream request: profile and contribution calendar, with complete: false and the remaining statistics null. Default full.

bash
curl "https://gitbanners.com/api/v1/owners/vercel"

Returns: A User or an Organization.

Get a repository

GET /api/v1/repos/{owner}/{repo}. A public repository as normalized JSON: counts, languages, a year of weekly commit activity, star history, the latest release and top contributors. A renamed repository answers under its current name.

• owner (path, required): Login of the user or organization that owns the repository.
• repo (path, required): Repository name as it appears on github.com.

bash
curl "https://gitbanners.com/api/v1/repos/vercel/next.js"

Returns: A Repository.

Get the API index

GET /api/v1. Where everything is: the current version, the OpenAPI description, the docs, the MCP endpoint and one URL template per operation and image form.

bash
curl "https://gitbanners.com/api/v1"

Returns: An ApiIndex.

Get the API root

GET /api. The unversioned entry point. It answers with the same index as the current version, so a client that only knows the host can find the versioned operations from here.

bash
curl "https://gitbanners.com/api"

Returns: An ApiIndex.

Image operations

The image URLs are part of the same OpenAPI description. They answer with image/svg+xml or image/png instead of JSON, and follow the rules under image responses.

Draw the banner of a user or an organization

GET /{owner}.{format}. The live banner image of a GitHub user or organization, drawn with the default preset. A well-formed URL always answers 200 with an image: an unknown login or an upstream failure is drawn as a card and reported in the X-Banner-State header, because an embedded image must never turn into a broken-image icon.

• owner (path, required): GitHub user or organization login. Write @login for a login that collides with a route of this site, such as @docs.
• format (path, required): Image format. SVG is the form to embed in a README; PNG is for surfaces that do not draw SVG.
• scale (query, optional): PNG pixel density. Default 2 for README banners (automatic height) and 1 for the fixed social sizes. Ignored for SVG.
• download (query, optional): Set to 1 to have the browser save the image instead of showing it.
• Every banner parameter as a query parameter, such as theme, size or accent.

bash
curl -o banner.svg "https://gitbanners.com/markeljan.svg"

Returns: An SVG or PNG image.

Draw the banner of a repository, or a profile preset

GET /{owner}/{repo}.{format}. The live banner image of a public repository. When the second segment is the id of a profile preset (such as activity, stats or streak) the answer is that preset of the owner's banner instead. A third segment selects a repository preset: /{owner}/{repo}/{preset}.{format}. A well-formed URL always answers 200 with an image, like the owner form.

• owner (path, required): Login of the user or organization.
• repo (path, required): Repository name, or one of the profile preset ids: overview, activity, stats, repos, languages, streak, wrapped, card.
• format (path, required): Image format. SVG is the form to embed in a README; PNG is for surfaces that do not draw SVG.
• scale (query, optional): PNG pixel density. Default 2 for README banners (automatic height) and 1 for the fixed social sizes. Ignored for SVG.
• download (query, optional): Set to 1 to have the browser save the image instead of showing it.
• Every banner parameter as a query parameter, such as theme, size or accent.

bash
curl -o banner.png "https://gitbanners.com/vercel/next.js.png"

Returns: An SVG or PNG image.

Errors

Every API answer that is not a success is application/problem+json (RFC 9457). Branch on code, show title and detail to a person, and follow resolution.

json
{
  "documentation_url": "https://gitbanners.com/docs#errors",
  "type": "https://gitbanners.com/docs#error-not_found",
  "title": "Not found",
  "status": 404,
  "detail": "No public GitHub user or organization is named no-such-login-here.",
  "code": "not_found",
  "resolution": "Check the spelling on github.com, then retry.",
  "instance": "/api/v1/owners/no-such-login-here"
}

Codes of the public API and the image URLs:

The web app's own account routes (saved banners, the signed-in user) use the same format with these codes. They work with a browser session from this site only and are not part of the public API:

Rate limits

Requests are counted per client IP address, in short windows. An IPv6 client is counted as its /64 network.

Every API answer carries the IETF rate limit fields:

RateLimit-Policy: "api";q=120;w=60
RateLimit: "api";r=119;t=60

• q is the quota and w the length of the window in seconds.
• r is what is left in the current window and t the seconds until it resets.
• Past the quota the answer is 429 with the code rate_limited and a Retry-After header. Wait that many seconds before the next request.
• If the counter itself cannot be reached, requests go through and only RateLimit-Policy is sent.

Banner images and pages are not limited per client. They are cached instead, so embedding a banner on a busy page costs one render per cache lifetime.

Data and freshness

• Banners and API answers are built from public GitHub data only: profiles, public repositories and the public contribution calendar.
• Private repositories are never read or named. If a user turned on "Private contributions" in their GitHub profile settings, GitHub includes those counts in the public calendar, and a banner shows them as counts.
• GitHub data is refreshed every 15 minutes. When GitHub cannot be reached, the last good copy is used for up to 7 days.
• fetchedAt on every entity says when its data was read from GitHub.

Versioning and deprecation

The version is in the path: /api/v1. Within a version, changes only add: new operations, new optional parameters, new members in a response. Clients should ignore members they do not know.

A change that would break a client ships under a new path (/api/v2), and the old version keeps answering while it is being retired. A retiring operation says so in its responses:

• Deprecation: the date from which the operation counts as deprecated (RFC 9745).
• Sunset: the date after which it may stop answering (RFC 8594), at least 90 days after the deprecation date.
• Link with rel="successor-version": the operation to move to.

Every API answer already carries a Link header with rel="deprecation" that points at this section, so a client can find the policy from any response. No operation is deprecated today.

Image URLs follow the same idea from the other side: they ignore what they do not understand, so a banner embedded today keeps drawing when parameters are added later.

Authentication

None. Every operation on this page is public and needs no API key, token or sign-up.

Sign in with GitHub exists for the web app only, to save banners and unlock Pro. It is a browser session that works from this site alone, and it is not part of the API.

MCP server

The same data is available to agents as tools on a Model Context Protocol server at https://gitbanners.com/mcp. It speaks Streamable HTTP, is stateless, and needs no credentials. Only POST is served; GET and DELETE answer 405.

Add it to a client that reads an mcpServers configuration:

json
{
  "mcpServers": {
    "gitbanners": {
      "type": "http",
      "url": "https://gitbanners.com/mcp"
    }
  }
}

Or call it by hand:

bash
curl -X POST "https://gitbanners.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_banner","arguments":{"target":"vercel/next.js"}}}'

• Every tool is read-only and declares it (readOnlyHint). Results come as structured content that matches the tool's output schema, and as the same JSON in a text block.
• A failed lookup is a tool result with isError and the same code values as the REST API. An unknown tool or a malformed message is a JSON-RPC error.
• Calls count against the api quota (120 requests per 60 seconds).
• The server card is at /mcp/server-card and /.well-known/mcp/server-card.json; the registry manifest is /server.json.

Tools in the browser

In a browser that implements WebMCP, the site registers tools on document.modelContext so an agent working in the page can use it directly: search_github, get_banner and list_banner_options read, and save_banner and update_saved_banner store a banner in the account of the signed-in visitor.

Agent skill

An agent skill that teaches the URL grammar and the machine interfaces is published at /.well-known/agent-skills/gitbanners/SKILL.md. The index at /.well-known/agent-skills/index.json lists it with the SHA-256 digest of the file, so a client can verify what it downloaded.

Markdown

Content pages and banner pages have a Markdown version, for agents that would rather not parse HTML.

• Add .md to the URL: /docs.md, /pricing.md, /vercel.md, /vercel/next.js.md. The homepage is /index.md.
• Or send Accept: text/markdown to the page URL. The answer carries Vary: Accept.
• Each document opens with front matter: title, description, canonical and last-updated.
• A path that is nothing answers 404 in Markdown too, with links to the indexes below.
• The Markdown of an account or a repository lists who it is, its headline numbers, and the image URL of every preset.

Machine-readable files

Updated 13 November 2026. Read this page as Markdown.