# Gitfile API reference

Base URL: https://gitfile.dev

Every field configurable in the dashboard is configurable here — same schema, same source of truth. Every request and response body is JSON, except the banner endpoint, which returns the rendered image directly.

## Authentication

Most endpoints accept either credential, whichever is present on the request:
- API key — `Authorization: Bearer gtf_live_...`, generated from Dashboard → API, the only place a key can ever be created. Each key carries one or more scopes (`config:read`, `config:write`) and can only act on its own account's configuration.
- The dashboard's session cookie — what the dashboard itself uses.

There is no endpoint to create, list, or revoke API keys — that's deliberate. Keys are managed exclusively from an authenticated dashboard session, never over the API, so a leaked key can never mint or delete other credentials. The public banner endpoint needs no auth at all.

## Rate limits

Authenticated requests: 60 requests/minute per API key. Public banner endpoint: 300 requests/minute per client IP. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers — back off once `Remaining` hits zero rather than waiting for a 429.

## Errors

Every non-2xx response, from any endpoint below, shares the same JSON envelope: `{ error, message }`, plus `issues` on a 400.

### 400 `invalid_request`
The request body or query string failed validation — see `issues` for exactly which field and why.
```json
{
  "error": "invalid_request",
  "message": "Invalid payload",
  "issues": [
    { "path": ["appearance", "accentColor"], "message": "accentColor must be a 6-digit hex color" }
  ]
}
```

### 401 `unauthenticated / api_auth_error`
No session cookie and no Authorization header were provided, or the API key wasn't recognized (unknown, malformed, or revoked).
```json
{
  "error": "api_auth_error",
  "message": "Missing or invalid Authorization: Bearer gtf_live_... header"
}
```

### 403 `api_auth_error`
The API key is valid but doesn't have the scope this endpoint requires (e.g. a `config:read`-only key calling a `config:write` route).
```json
{
  "error": "api_auth_error",
  "message": "This API key does not have the \"config:write\" scope"
}
```

### 429 `api_auth_error`
More than 60 requests/minute for this API key (or 300/minute per client IP on the public banner endpoint). Every response carries `X-RateLimit-*` headers so you can back off before hitting this.
```json
{
  "error": "api_auth_error",
  "message": "Rate limit exceeded (60 requests/minute)"
}
```

### 500 `internal_error`
Something went wrong on our end. Safe to retry with backoff.
```json
{
  "error": "internal_error",
  "message": "Something went wrong"
}
```

## Endpoints

### Configuration

#### GET /api/v1/config — Retrieve the current configuration

Returns the authenticated user's current banner configuration as JSON.

Auth: Session cookie, or an API key with the config:read scope

Returns: 200 — The full banner configuration. Can also return: 401, 403, 429, 500 (see Errors above).

Example request:
```bash
curl "https://gitfile.dev/api/v1/config" \
  -H "Authorization: Bearer gtf_live_xxxxxxxxxxxx"
```

#### PUT /api/v1/config — Replace the configuration

Replaces the full configuration in one call — every field below is required, same as saving the entire dashboard form at once.

Auth: Session cookie, or an API key with the config:write scope

Request body (All fields required — this is a full replace, not a merge. Use PATCH below to change just a few fields.):
- `displayName` (string): 1–80 characters. The banner's headline name.
- `bio` (string): Up to 240 characters, shown under the display name.
- `showAvatar` (boolean): Whether the GitHub avatar is rendered.
- `customAvatarUrl` (string | null): Overrides the GitHub avatar with a custom image URL, or null to use it.
- `appearance` (object): Visual style of the banner.
  - `theme` (string): "light", "dark", "auto", or "custom".
  - `accentColor` (string): A 6-digit hex color, e.g. "#0A84FF".
  - `layout` (string): "compact", "wide-horizontal", or "vertical-card".
  - `typography` (string): "system", "mono", or "editorial".
  - `style` (string): "cards", "minimal", "split", or "terminal".
  - `radius` (number): Corner radius in px, 0–32.
- `showFields` (object): Which stats and fields are visible on the banner.
  - `repositories` (boolean): Show the repository count.
  - `followers` (boolean): Show the follower count.
  - `stars` (boolean): Show total stars earned.
  - `contributionStreak` (boolean): Show the current day streak.
  - `commits` (boolean): Show commits in the last 30 days.
  - `pullRequests` (boolean): Show pull requests in the last 30 days.
  - `issues` (boolean): Show issues in the last 30 days.
  - `topLanguages` (boolean): Show the top-languages breakdown.
  - `pinnedRepos` (array of string): Up to 3 repo names to feature.
  - `organization` (boolean): Show the GitHub organization/company field.
  - `location` (boolean): Show the location field.
  - `proBadge` (boolean): Show the "Pro" badge.
  - `contributionGraph` (boolean): Show the contribution heatmap.
- `profilePage` (object): Which sections are visible on the public /{username} profile page.
  - `showLiveBanner` (boolean): Show the embedded banner at the top of the page.
  - `showReadme` (boolean): Show the README rendered from your username/username repo.
  - `showLanguageBreakdown` (boolean): Show the top-languages bar.
  - `showPinnedRepos` (boolean): Show the pinned repositories section.
  - `showRecentActivity` (boolean): Show recent pushes, PRs, issues, and releases.
  - `showStatsGrid` (boolean): Show the stats grid and streak card.
  - `showContributionHeatmap` (boolean): Show the full contribution heatmap.
- `public` (boolean): Whether the banner URL and the /{username} page render real data or a private placeholder.
- `includePrivateRepos` (boolean): Opt-in to include private/org repos in aggregate stats. Requires a connected token with repo scope — this flag alone does nothing without one.

Returns: 200 — The configuration as saved. Can also return: 400, 401, 403, 429, 500 (see Errors above).

Example request:
```bash
curl -X PUT "https://gitfile.dev/api/v1/config" \
  -H "Authorization: Bearer gtf_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"theme":"dark","accentColor":"#0A84FF"}'
```

#### PATCH /api/v1/config — Update part of the configuration

Partially updates specific fields without resending the whole object — nested objects (appearance, showFields) are shallow-merged too.

Auth: Session cookie, or an API key with the config:write scope

Request body (Every field is optional — send only what you want to change.):
- `displayName` (string): 1–80 characters. The banner's headline name.
- `bio` (string): Up to 240 characters, shown under the display name.
- `showAvatar` (boolean): Whether the GitHub avatar is rendered.
- `customAvatarUrl` (string | null): Overrides the GitHub avatar with a custom image URL, or null to use it.
- `appearance` (object): Visual style of the banner.
  - `theme` (string): "light", "dark", "auto", or "custom".
  - `accentColor` (string): A 6-digit hex color, e.g. "#0A84FF".
  - `layout` (string): "compact", "wide-horizontal", or "vertical-card".
  - `typography` (string): "system", "mono", or "editorial".
  - `style` (string): "cards", "minimal", "split", or "terminal".
  - `radius` (number): Corner radius in px, 0–32.
- `showFields` (object): Which stats and fields are visible on the banner.
  - `repositories` (boolean): Show the repository count.
  - `followers` (boolean): Show the follower count.
  - `stars` (boolean): Show total stars earned.
  - `contributionStreak` (boolean): Show the current day streak.
  - `commits` (boolean): Show commits in the last 30 days.
  - `pullRequests` (boolean): Show pull requests in the last 30 days.
  - `issues` (boolean): Show issues in the last 30 days.
  - `topLanguages` (boolean): Show the top-languages breakdown.
  - `pinnedRepos` (array of string): Up to 3 repo names to feature.
  - `organization` (boolean): Show the GitHub organization/company field.
  - `location` (boolean): Show the location field.
  - `proBadge` (boolean): Show the "Pro" badge.
  - `contributionGraph` (boolean): Show the contribution heatmap.
- `profilePage` (object): Which sections are visible on the public /{username} profile page.
  - `showLiveBanner` (boolean): Show the embedded banner at the top of the page.
  - `showReadme` (boolean): Show the README rendered from your username/username repo.
  - `showLanguageBreakdown` (boolean): Show the top-languages bar.
  - `showPinnedRepos` (boolean): Show the pinned repositories section.
  - `showRecentActivity` (boolean): Show recent pushes, PRs, issues, and releases.
  - `showStatsGrid` (boolean): Show the stats grid and streak card.
  - `showContributionHeatmap` (boolean): Show the full contribution heatmap.
- `public` (boolean): Whether the banner URL and the /{username} page render real data or a private placeholder.
- `includePrivateRepos` (boolean): Opt-in to include private/org repos in aggregate stats. Requires a connected token with repo scope — this flag alone does nothing without one.

Returns: 200 — The full configuration after the patch is applied. Can also return: 400, 401, 403, 429, 500 (see Errors above).

Example request:
```bash
curl -X PATCH "https://gitfile.dev/api/v1/config" \
  -H "Authorization: Bearer gtf_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"showFields":{"contributionStreak":false}}'
```

#### POST /api/v1/config/regenerate — Force a cache refresh

Forces an immediate cache invalidation of the public banner image (bypassing the normal ~24h refresh schedule). No request body.

Auth: Session cookie, or an API key with the config:write scope

Returns: 200 — Confirms the banner cache was invalidated. Can also return: 401, 403, 429, 500 (see Errors above).

Example request:
```bash
curl -X POST "https://gitfile.dev/api/v1/config/regenerate" \
  -H "Authorization: Bearer gtf_live_xxxxxxxxxxxx"
```

#### DELETE /api/v1/account — Delete your account

Permanently deletes the signed-in account: saved configuration, linked identities, username claims, API keys and cached stats, and revokes the OAuth grants on GitHub/GitLab (best effort). The body must carry one of your linked usernames as a typed confirmation. Session-only: an API key cannot call this endpoint. Not reversible.

Auth: Session cookie only (API keys are rejected)

Returns: 200 — Confirms the account was deleted and the session cookie cleared. Can also return: 400, 401, 500 (see Errors above).

Example request:
```bash
curl -X DELETE "https://gitfile.dev/api/v1/account" \
  -H "Content-Type: application/json" \
  -b "gitfile_session=..." \
  -d '{"confirm":"octocat"}'
```

### Banner

#### GET /api/v1/banner/{username} — Get the rendered banner image

Public endpoint, no auth required — returns the rendered banner directly (not JSON), as SVG, PNG, or plain ANSI text for a terminal. Style and which stats are shown can be overridden per-request with query params, without touching the saved config. Called from curl, Wget, or HTTPie with no explicit format, it returns ansi text automatically. The short gitfile.dev/{username} path (no /api/v1/banner/ prefix) works the same way for a CLI caller — it's the same path a browser uses for the public profile page, content-negotiated by User-Agent. When the same name exists on both GitHub and GitLab (or was claimed first on the other provider), add the provider: /api/v1/banner/github/{username} or /api/v1/banner/gitlab/{username} (and gitfile.dev/github/{username} / gitfile.dev/gitlab/{username} for the profile page and curl).

Auth: None — public

Path parameters:
- `username` (string, required): GitHub username (case-insensitive). Accepts a .svg, .png, or .txt suffix as an alternative to ?format=.

Query parameters:
- `format` (string): "svg" (default for browsers), "png", or "ansi" (default automatically when the request comes from curl, Wget, or HTTPie — see the .txt suffix / Terminal usage below).
- `theme` (string): "light", "dark", "auto", or "custom".
- `accentColor` (string): A 6-digit hex color, e.g. "#0A84FF".
- `layout` (string): "compact", "wide-horizontal", or "vertical-card".
- `typography` (string): "system", "mono", or "editorial".
- `style` (string): "cards", "minimal", "split", or "terminal".
- `radius` (number): Corner radius in px, 0–32.
- `repositories` (boolean): Show the repository count. (true/false or 1/0)
- `followers` (boolean): Show the follower count. (true/false or 1/0)
- `stars` (boolean): Show total stars earned. (true/false or 1/0)
- `contributionStreak` (boolean): Show the current day streak. (true/false or 1/0)
- `commits` (boolean): Show commits in the last 30 days. (true/false or 1/0)
- `pullRequests` (boolean): Show pull requests in the last 30 days. (true/false or 1/0)
- `issues` (boolean): Show issues in the last 30 days. (true/false or 1/0)
- `topLanguages` (boolean): Show the top-languages breakdown. (true/false or 1/0)
- `organization` (boolean): Show the GitHub organization/company field. (true/false or 1/0)
- `location` (boolean): Show the location field. (true/false or 1/0)
- `proBadge` (boolean): Show the "Pro" badge. (true/false or 1/0)
- `contributionGraph` (boolean): Show the contribution heatmap. (true/false or 1/0)
- `pinnedRepos` (string): Comma-separated repo names, up to 3 (e.g. pinnedRepos=gitfile,dotfiles).
- `cols` (number): ansi format only. Terminal width in columns (20-400, default 100). curl can't detect this itself — pass cols=$(tput cols) from your shell.
- `lines` (number): ansi format only. Terminal height in rows (5-200, default 30). Same idea as cols — pass lines=$(tput lines).
- `color` (string): "truecolor" (default), "256", or "none" for plain, uncolored text.

Returns: 200 — The rendered banner. Content-Type is image/svg+xml (default for browsers), image/png with ?format=png, or text/plain (ANSI escape codes included) for ?format=ansi / a CLI caller. Can also return: 400, 429 (see Errors above).

Example request:
```bash
# The short form works too (gitfile.dev/{username}) — curl auto-detects
# a perfect fit:
curl "https://gitfile.dev/octocat?cols=$(tput cols)&lines=$(tput lines)"

# Restyle it the same way you would the SVG/PNG:
curl "https://gitfile.dev/octocat?style=terminal&theme=dark&accentColor=%2330D158"

# Force a specific format:
curl "https://gitfile.dev/api/v1/banner/octocat.svg?theme=light&accentColor=%230A84FF&style=minimal&stars=false"
```