Skip to content

API Reference

Jump to bottom
Ferran Buireu edited this page Jun 13, 2026 · 2 revisions

API Reference

ContribKit's web component exposes a small public API on Cloudflare Workers. All data responses are cached public, max-age=3600, stale-while-revalidate=86400 and rate-limited per IP (100 req/min). Every response carries CSP and security headers set by the middleware.

Base URL: https://contribkit.app

Endpoints

Endpoint Returns Description
GET /user/:username.svg image/svg+xml Rendered calendar; accepts palette, shape, background
GET /api/contributions?user=&year= application/json Raw contribution cells plus yearly total
GET /api/health application/json Deployment health: env var/binding presence (never values)

GET /user/:username.svg

Renders the contribution calendar for :username as an SVG image. Always uses the latest rolling year.

Query parameters

Parameter Default Values
palette github github, catppuccin, nord, dracula, gruvbox, sunset, tokyonight, onedark, rosepine, solarized, monokai
shape rounded rounded, square, circle, dot, hex
background transparent transparent, any hex color (#101010), or a CSS color name

Unknown values silently fall back to the default, so the image never breaks.

Example

GET /user/torvalds.svg?palette=dracula&shape=circle&background=%23101010

GET /api/contributions

Returns the raw contribution data as JSON.

Query parameters

Parameter Required Description
user yes GitHub username
year no Four-digit year (back to 2005). Omitted = latest rolling year

Response

{
  "username": "torvalds",
  "cells": [
    { "date": "2024-01-01", "level": 0, "count": 0 },
    { "date": "2024-01-02", "level": 2, "count": 4 }
  ],
  "total": 1234
}
  • level is 0–4 (GitHub's intensity bucket).
  • count is the exact contribution count for that day, or null when GitHub doesn't expose a tooltip for the cell.
  • total is the sum of all daily counts, or null when no counts are available.

Errors

Errors return { "error": "<message>" } with an appropriate status:

Status Meaning
400 Missing user, or invalid username/year
404 GitHub has no such user
5xx GitHub unreachable, or the page couldn't be parsed

GET /api/health

Reports whether the deployed worker was built/configured with each expected variable and binding. Reports presence only — never values. Sent with Cache-Control: no-store.

{
  "status": "ok",
  "env": {
    "PUBLIC_GOOGLE_ANALYTICS_ID": true,
    "PUBLIC_BETTER_STACK_SOURCE_TOKEN": true,
    "PUBLIC_BETTER_STACK_INGESTING_URL": true,
    "API_RATE_LIMITER": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Returns 200 when everything is present, 503 ("status": "misconfigured") otherwise.

See also

Clone this wiki locally