# Gitfile documentation

How to embed a Gitfile banner, tune its URL, and understand what's cached and what's public.

## Embedding

Paste the Markdown snippet from your dashboard into your GitHub profile README.md. It renders as an SVG image that GitHub fetches fresh on every profile view.

```md
[![Gitfile](https://gitfile.dev/api/v1/banner/octocat.svg)](https://gitfile.dev)
```

## Public profile page

Every GitHub username has a page at https://gitfile.dev/{username} — a readable summary of their public GitHub activity: a derived "developer type" from their language mix, top languages, pinned repos, and a contribution heatmap.

To address one provider explicitly (e.g. when the same name exists on GitHub and GitLab), use https://gitfile.dev/github/{username} or https://gitfile.dev/gitlab/{username}; their banners are at https://gitfile.dev/api/v1/banner/github/{username}.svg and https://gitfile.dev/api/v1/banner/gitlab/{username}.svg.

If that username belongs to a Gitfile account with a public profile, the page also embeds their real, live banner and links back to their dashboard. If it doesn't (or the account hasn't signed in yet), the page still renders from GitHub's public data alone, with a preview of what their banner could look like and a prompt to claim it.

The same Dashboard → Privacy → Public profile toggle that controls the banner URL controls this page too — turning it off replaces both with a private placeholder.

## Terminal / curl

The same banner URL also works from a terminal — no image, no browser. Called from curl, Wget, or HTTPie with no explicit format, it detects the caller isn't a browser and returns a plain-text, ANSI-colored card instead of an SVG.

```bash
curl "https://gitfile.dev/octocat?cols=$(tput cols)&lines=$(tput lines)"
```

Pass your real terminal size with cols/lines — curl can't detect this itself, so `$(tput cols)` and `$(tput lines)` from the shell give it the real numbers. Without them (or with a terminal too narrow for even the most compact layout), it prints a short plain-text prompt asking for the size instead of guessing and risking a broken box.

It restyles exactly like the image does — `?theme=`, `?style=`, `?accentColor=`, and every per-stat toggle apply to the text render too:

```bash
curl "https://gitfile.dev/octocat?style=terminal&theme=dark&accentColor=%2330D158"
```

Drop it in a dotfiles repo, a shell profile, or a CI job's welcome banner. The full cols/lines/color reference is in the API reference (see below), under GET /api/v1/banner/{username}.

## URL parameters

Beyond .svg/.png/.txt (or the equivalent `?format=`), the banner endpoint takes per-request overrides — no auth required — for theme, layout, style, accent color, which stats show, and the terminal-only cols/lines/color params above. None of these touch the saved config — they only restyle that one response. The full list is in the API reference, under GET /api/v1/banner/{username}.

## Caching & rate limits

Banners are rendered once and served from an edge cache until something invalidates them — never per view. Saving a change in the dashboard (or calling `POST /api/v1/config/regenerate`) invalidates the cache instantly; otherwise it refreshes on a rolling ~24h schedule so stats stay current even if the config is never touched.

Authenticated API requests are limited to 60 requests/minute per API key; the public banner endpoint is limited per client IP.

## Security & privacy FAQ

**What data does Gitfile store?** The GitHub profile fields the user has chosen to show, and their banner configuration. Gitfile never asks for or stores a raw personal access token.

**How do I revoke access?** From Dashboard → Privacy → Disconnect GitHub. This immediately invalidates the stored token and clears cached data.

**What if I turn off "Public profile"?** The banner URL keeps working but returns a generic placeholder image — it never 404s in a way that reveals whether the account exists.

## API reference

Full endpoint reference (auth, rate limits, errors, request/response shapes for every Configuration and Banner endpoint) is at https://gitfile.dev/docs/api/llms.txt.