API

API Reference

Endpoints

GET /

Returns API metadata and available theme names.

Response (200):

{
  "name": "GitHub Profile Card API",
  "version": "0.1.2",
  "author": "Nayan Das (https://github.com/nayandas69)",
  "usage": "GET /card/:username",
  "themes": ["default", "dark", "dracula", "..."],
  "repository": "https://github.com/nayandas69/github-profile-card"
}

---

GET /card/:username

Returns an SVG image of the GitHub profile card.

---

GET /health

Simple health check endpoint for monitoring and uptime pings.

Response (200):

{
  "status": "ok",
  "timestamp": "2026-02-18T12:00:00.000Z"
}

---

Parameters

Path Parameters

Parameter	Type	Required	Description
username	string	Yes	GitHub username (1–39 chars, alphanumeric, hyphens, or underscores)

Query Parameters

Parameter	Type	Required	Default	Description
theme	string	No	default	Theme name for the card (see Theme List)
title_color	string	No	—	Hex color for the title (without #, e.g. ff0000)
text_color	string	No	—	Hex color for body text
icon_color	string	No	—	Hex color for icons
bg_color	string	No	—	Hex color for the card background
border_color	string	No	—	Hex color for the card border
hide_border	string	No	false	Set to true to remove the card border
compact	string	No	false	Set to true to hide bio, pronouns, X/Twitter handle, and language labels
fields	string	No	(all)	Comma-separated list of sections to show: stats, languages, langs, all

Important: Color parameters accept 6-digit hex values without the # prefix. Invalid hex values return a 400 error.

---

Examples

Basic Request

https://github-profile-card-blue.vercel.app/card/nayandas69

With Theme

https://github-profile-card-blue.vercel.app/card/nayandas69?theme=dracula

Custom Colors

https://github-profile-card-blue.vercel.app/card/nayandas69?theme=dark&title_color=ff6e96&icon_color=bd93f9

Compact Mode

https://github-profile-card-blue.vercel.app/card/nayandas69?compact=true

Show Only Languages (Hide Stats)

https://github-profile-card-blue.vercel.app/card/nayandas69?fields=languages

Hide Border

https://github-profile-card-blue.vercel.app/card/nayandas69?theme=tokyonight&hide_border=true

---

Response

Success (200)

Returns an SVG image with content-type image/svg+xml.

<?xml version="1.0" encoding="UTF-8"?>
<svg width="500" height="{dynamic}" viewBox="0 0 500 {dynamic}" xmlns="http://www.w3.org/2000/svg">
  <!-- Profile Card SVG Content -->
</svg>

Note: The card width is fixed at 500px. The height is dynamically calculated based on visible sections.

Error (400) — Invalid Username

{
  "error": "Invalid GitHub username. Username must be 1-39 characters and contain only alphanumeric characters, hyphens, or underscores."
}

Error (400) — Invalid Hex Color

{
  "error": "Invalid hex color for title_color: xyz123"
}

Error (404) — User Not Found

{
  "error": "GitHub user \"username\" not found"
}

Error (429) — Rate Limited

{
  "error": "GitHub API rate limit exceeded. Please try again later."
}

Error (500) — Server Error

{
  "error": "An unexpected error occurred"
}

Error (503) — GitHub API Unavailable

{
  "error": "GitHub API error. Please try again later."
}

---

Theme List

Available Themes (56 Total)

Default:

• default

Dark Themes (8):

• dark, dracula, monokai, nord, github_dark, slate, midnight, highcontrast

Light Themes (3):

• pearl, ice, sand

Pastel Themes (5):

• pastel_peach, pastel_mint, pastel_lavender, pastel_lemon, pastel_rose

Material Design (6):

• mui_blue, mui_indigo, mui_teal, mui_deep_purple, mui_orange, mui_red

VSCode Themes (5):

• vscode_dark_plus, vscode_light, vscode_monokai_pro, vscode_night_owl, vscode_palenight

Brand Themes (6):

• twitter, discord, spotify, github_light, youtube, instagram

Neon/Vibrant (6):

• radical, cyberpunk, synthwave, oceanic, mint, royal

Natural/Warm (10):

• gruvbox, merko, forest, rose, sunset, lavender, ember, tokyonight, onedark, cobalt

AMOLED (3):

• amoled_blue, amoled_green, amoled_purple

Grayscale (3):

• grayscale_light, grayscale_mid, grayscale_dark

---

Caching

The API uses a multi-layer caching strategy for optimal performance:

Layer	Type	TTL	Description
1	In-memory	30 minutes	Per-instance cache with bounded size (max 500 entries)
2	Upstash Redis	30 minutes	Shared across serverless instances (optional)
3	CDN (Vercel Edge)	30 minutes	s-maxage=1800 with stale-while-revalidate=1800

• Concurrent requests for the same username are deduplicated (only one API call is made).
• The in-memory cache enforces a max of 500 entries with oldest-first eviction.
• A background sweep runs every 5 minutes to proactively remove expired entries.

---

Rate Limiting

• No authentication is required to use the API.
• The server limits concurrent in-flight requests to 100 to prevent overload.
• GitHub API rate limits apply (the server uses a GITHUB_TOKEN for authenticated requests).
• If GitHub's rate limit is hit, the API returns a 429 response.

---

CORS

The API supports CORS and allows requests from any origin.

---

Implementation Examples

Markdown

![GitHub Profile Card](https://github-profile-card-blue.vercel.app/card/USERNAME?theme=dracula)

HTML

<img src="https://github-profile-card-blue.vercel.app/card/USERNAME?theme=dracula" alt="GitHub Profile Card">

JavaScript

const username = 'nayandas69';
const theme = 'dracula';
const url = `https://github-profile-card-blue.vercel.app/card/${username}?theme=${theme}`;
const img = new Image();
img.src = url;
document.body.appendChild(img);

React

export default function ProfileCard() {
  const username = 'nayandas69';
  const theme = 'dracula';

  return (
    <img
      src={`https://github-profile-card-blue.vercel.app/card/${username}?theme=${theme}`}
      alt="GitHub Profile Card"
    />
  );
}

---

Limitations

• GitHub API rate limits apply (authenticated via server-side GITHUB_TOKEN)
• Usernames must be 1–39 characters (alphanumeric, hyphens, underscores)
• Bio is truncated to 40 characters (single line with ellipsis)
• Top 5 languages are shown (by total code size across owned, non-fork repos)
• Language labels may be shortened if the card is too narrow to fit all names
• Avatar is embedded as base64 (fetched at 96px) for cross-platform SVG compatibility
• Profile data is cached for 30 minutes across all layers

---

Support

For issues or questions, visit the GitHub repository.