api --reference

Docs

Every URL option supported by the live SVG endpoint, plus examples and common fixes.

Endpoint

Use this path inside an image tag or open it directly in the browser.

/api/contributions?username=your-github-username

Query Params

Missing optional params fall back to safe defaults.

usernameGitHub username

Required. Public GitHub login to render.

themegithub, ocean, sunset, grape, mono, rose, white

Controls the default SVG palette.

typeheatmap, activity, streak, punch, stats, summary, profile

Selects the widget layout.

sizecompact, normal, wide

Sets the rendered SVG width.

hide_titletrue or false

Hides the title when true.

hide_totaltrue or false

Hides total contribution text when true.

hide_legendtrue or false

Hides legends and helper captions when true.

show_bordertrue or false

Turns the outer border on or off.

avatartrue or false

Shows the GitHub profile image in the profile layout when true.

radius0 to 24

Controls SVG corner radius.

bg6-digit hex

Overrides background color, without #.

text6-digit hex

Overrides primary text color, without #.

border6-digit hex

Overrides border color, without #.

Examples

Swap the username and paste the URL into your README image tag.

/api/contributions?username=muhammad-muneeb3&theme=github&type=heatmap
/api/contributions?username=muhammad-muneeb3&theme=ocean&type=activity&size=wide
/api/contributions?username=muhammad-muneeb3&theme=grape&type=stats&hide_legend=true
/api/contributions?username=muhammad-muneeb3&theme=mono&type=profile&avatar=false&bg=ffffff&text=111111&border=d0d7de

Troubleshooting

The endpoint returns an SVG error state, so broken embeds still explain what happened.

Missing token

Set `GITHUB_TOKEN` in Vercel or your local environment.

Invalid username

Use only letters, numbers, and hyphens. GitHub usernames cannot start or end with a hyphen.

Empty graph

If GitHub shows activity but the widget is empty, private contributions may be hidden or inaccessible to this app token.

Rate limit

Wait until the reset time shown in the SVG error, or use a fresh read-only GitHub token.

Private activity

Only public contribution calendar data available to the configured token can be rendered.