# gitwall

> Embeddable GitHub activity widgets. A widget is a URL; embedding it is an iframe. No account needed for the free tier.

Base URL: https://gitwall.io — all paths below are relative to it.

## Make a contribution-graph widget for one GitHub user

Build a URL on `/w` with query parameters (all optional except `user`):

- `user` GitHub login (required)
- `months` 3 | 6 | 12 (default 12)
- `theme` github-dark | github-light | tethered | tethered-light | mono-dark (default github-dark)
- `brand` hex without `#` (e.g. `5627ff`). Derives a full palette from one brand color; use with `bg` to pick dark/light.
- `bg`, `text`, `textDim`, `line`, `bgElev`, `accent` hex overrides without `#`
- `ramp` five comma-separated hexes, least to most active, e.g. `0f1550,3e1cc5,5627ff,76aaff,41f8e1`
- `title` custom heading (default "commits, @user")
- `stats`, `labels`, `legend`, `tooltips` 1|0 (default 1)
- `tv` 1 to fill the screen for a wall display (default 0)

Example: `https://gitwall.io/w?user=octocat&months=6&theme=github-light`

## Get the exact iframe to paste

`GET /api/v1/widget/snippet?<same params>&width=800` returns JSON:
`{ url, width, height, iframe, iframeAutoResize, config }`.
Use `iframe` for a fixed height sized for `width`, or `iframeAutoResize` (iframe + 3-line script) so it grows to fit.
The widget posts `{ type: "gitwall:height", height }` to its parent whenever its size changes.

## Team leaderboard

`/team?users=a,b,c&months=12&theme=…&repos=owner/repo,owner/repo`
Ranks members by contributions with streaks and 12-week sparklines. With `repos`, adds lines added/removed per member from GitHub's contributor stats. Same color parameters as `/w`.

## Raw data

`GET /api/v1/contributions/{user}?months=12` → `{ user, from, to, days: [{date, count}], total, repos: [...], summary: {...}, source }`.
`repos` (commits per repository) is populated only when the server has a GitHub token.

## Notes for agents

- Everything is GET and CORS-enabled; nothing to authenticate for public data.
- Results are cached for an hour.
- Private contributions appear only if the GitHub user has enabled "Private contributions" on their profile, or (planned) connects their account.
- Payments: a metered API key tier for agents is planned; until then the free tier shows a small "gitwall" badge.
- Machine-readable spec: /openapi.json