# GitFold — Full API Reference

> Download any GitHub subdirectory as a zip — no git clone, no login.
> Web: https://gitfold.cc  |  API: https://api.gitfold.cc  |  Docs: https://gitfold.cc/docs

---

## URL formats accepted

Any of these work everywhere (web UI, API, CLI):

    https://github.com/owner/repo/tree/branch/path/to/dir   (subdirectory)
    https://github.com/owner/repo/tree/branch               (entire repo root)
    github.com/owner/repo/tree/branch/path                  (no protocol OK)
    https://gitfold.cc/owner/repo/tree/branch/path          (gitfold URL)

GitFold URLs are identical to GitHub tree URLs with the domain swapped.

---

## REST API

Base URL: `https://api.gitfold.cc`

All endpoints:
- Return errors as JSON with `code`, `message`, and `hint` fields
- Support `OPTIONS` preflight with CORS headers

**CORS policy:**
- Credentialed requests (`credentials: 'include'`) are allowed from `gitfold.cc` and `localhost`
- Other origins receive `Access-Control-Allow-Origin: *` (no credentials)

---

### GET /v1/download

Download a GitHub directory as an archive.

**Query parameters**

| Parameter | Type   | Required | Description                          |
|-----------|--------|----------|--------------------------------------|
| url       | string | yes      | URL-encoded GitHub tree URL          |
| format    | string | no       | `zip` (default) or `tar.gz` / `tgz` |

**Headers**

| Header          | Description                                              |
|-----------------|----------------------------------------------------------|
| X-GitHub-Token  | GitHub PAT — raises rate limit to 5,000 req/hr           |
| X-Sub-Token     | Subscription token — unlocks Pro/Power file count limits |
| Cookie          | `gitfold_session=<jwt>` — OAuth session (auto from browser) |

**Response**

- `200 OK` — `application/zip` or `application/gzip` stream
- `Content-Disposition: attachment; filename="dirname.zip"`
- `X-Cache: HIT` or `X-Cache: MISS` — R2 cache status
- For full-repo downloads: `302` redirect to GitHub's archive CDN (zero-latency)

**Examples**

Download a subdirectory:

    curl -L "https://api.gitfold.cc/v1/download?url=https%3A%2F%2Fgithub.com%2Fanthropics%2Fclaude-code%2Ftree%2Fmain%2Fplugins" \
         -o plugins.zip

With a GitHub token:

    curl -L \
         -H "X-GitHub-Token: ghp_xxxxxxxxxxxx" \
         "https://api.gitfold.cc/v1/download?url=https%3A%2F%2Fgithub.com%2Fanthropics%2Fclaude-code%2Ftree%2Fmain%2Fplugins" \
         -o plugins.zip

Download as tar.gz:

    curl -L "https://api.gitfold.cc/v1/download?url=...&format=tar.gz" -o archive.tar.gz

---

### GET /v1/info

Get metadata about a directory without downloading it.

**Query parameters**

| Parameter | Type   | Required | Description                 |
|-----------|--------|----------|-----------------------------|
| url       | string | yes      | URL-encoded GitHub tree URL |

**Headers**

Same as `/v1/download` (X-GitHub-Token, X-Sub-Token, Cookie).

**Response**

    {
      "provider":  "github",
      "owner":     "anthropics",
      "repo":      "claude-code",
      "branch":    "main",
      "path":      "plugins",
      "fileCount": 12,
      "totalSize": 45200,
      "tier":      "free",
      "fileLimit": 50,
      "files": [
        { "path": "plugins/README.md",        "size": 1204  },
        { "path": "plugins/feature-dev/prompt.md", "size": 11636 }
      ]
    }

**Example**

    curl "https://api.gitfold.cc/v1/info?url=https%3A%2F%2Fgithub.com%2Fanthropics%2Fclaude-code%2Ftree%2Fmain%2Fplugins"

---

### GET /v1/auth/github

Start GitHub OAuth login. Redirects the browser to GitHub's authorization page.

**Response:** `302` redirect to `https://github.com/login/oauth/authorize?...`

After the user authorizes, GitHub redirects back to `/v1/auth/github/callback`, which sets a session cookie and redirects to `https://gitfold.cc/?auth=success`.

**Example (browser navigation):**

    window.location.href = 'https://api.gitfold.cc/v1/auth/github'

---

### GET /v1/auth/github/callback

OAuth callback handler — called by GitHub automatically. Not intended for direct use.

---

### GET /v1/auth/me

Return the current user's session info.

**Headers:** Cookie with `gitfold_session` (sent automatically by browser if `credentials: 'include'`)

**Response (authenticated):**

    {
      "authenticated": true,
      "userId":       "550e8400-e29b-41d4-a716-446655440000",
      "email":        "user@example.com",
      "githubLogin":  "octocat",
      "tier":         "free"
    }

**Response (not authenticated):**

    { "authenticated": false }

**Example:**

    fetch('https://api.gitfold.cc/v1/auth/me', { credentials: 'include' })

---

### POST /v1/auth/logout

Clear the session cookie and revoke the JWT.

**Headers:** Cookie with `gitfold_session`

**Response:**

    { "ok": true }

Sets `Set-Cookie: gitfold_session=; Max-Age=0; ...` to clear the session.

**Example:**

    fetch('https://api.gitfold.cc/v1/auth/logout', {
      method: 'POST',
      credentials: 'include'
    })

---

### POST /v1/checkout

Create a Stripe Checkout session for a Pro or Power subscription.

**Request body (JSON):**

| Field | Type   | Required | Description             |
|-------|--------|----------|-------------------------|
| email | string | yes      | Customer email address  |
| tier  | string | no       | `"pro"` (default) or `"power"` |

**Response:**

    { "url": "https://checkout.stripe.com/pay/cs_..." }

Redirect the user to `url` to complete payment. On success, Stripe redirects to
`https://gitfold.cc/pricing?checkout=success&session_id=cs_...`

**Example:**

    const res = await fetch('https://api.gitfold.cc/v1/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'user@example.com', tier: 'pro' })
    })
    const { url } = await res.json()
    window.location.href = url

---

### POST /v1/webhook/stripe

Stripe webhook endpoint. Handles `checkout.session.completed`, `customer.subscription.updated`,
and `customer.subscription.deleted` events to update subscription state.

**Not for direct use** — configured in Stripe Dashboard to point here.

---

### GET /v1/sub/claim

Claim a subscription token after a successful Stripe Checkout.

**Query parameters**

| Parameter  | Type   | Required | Description                               |
|------------|--------|----------|-------------------------------------------|
| session_id | string | yes      | Stripe Checkout session ID from the URL   |

**Response (success):**

    { "ok": true, "token": "sub_xxxxxxxxxxxx", "email": "user@example.com" }

**Response (not found / still processing):**

    { "ok": false, "message": "Session not found or expired. It may take a moment — please refresh." }

Store the returned `token` in localStorage as `gitfold_sub_token` and pass it as `X-Sub-Token` on API requests.

---

### GET /v1/sub/status

Query subscription status by token or email.

**Query parameters** (provide one):

| Parameter | Type   | Description                    |
|-----------|--------|--------------------------------|
| token     | string | Subscription token (preferred) |
| email     | string | Customer email address         |

**Response:**

    { "tier": "pro", "active": true, "email": "user@example.com" }

    { "tier": "free", "active": false }

---

### GET /health

Health check.

    { "ok": true, "service": "worker", "version": "1.0.0", "timestamp": "..." }

---

## Error responses

All errors return JSON:

    {
      "code":    "RATE_LIMITED",
      "message": "GitHub API rate limit exceeded.",
      "hint":    "Provide X-GitHub-Token to get 5,000 requests/hour."
    }

| Status | Code            | Meaning                                          |
|--------|-----------------|--------------------------------------------------|
| 400    | INVALID_URL     | Not a valid GitHub tree URL, or path is empty    |
| 400    | INVALID_REQUEST | Missing or malformed request parameters          |
| 404    | NOT_FOUND       | Repo, branch, or path does not exist on GitHub   |
| 413    | TOO_MANY_FILES  | Directory exceeds tier file-count limit          |
| 413    | TOO_LARGE       | Directory exceeds 100 MB size limit              |
| 429    | RATE_LIMITED    | GitHub API rate limit hit                        |
| 500    | CONFIG_ERROR    | Server misconfiguration (OAuth/Stripe not set up)|
| 502    | GITHUB_ERROR    | GitHub API returned an unexpected error          |
| 500    | INTERNAL_ERROR  | Unexpected server error                          |

---

## CLI

    # No install needed
    npx gitfold <url>

    # Options
    npx gitfold <url>                          # download zip to current directory
    npx gitfold <url> --output ./archive.zip   # custom output path
    npx gitfold <url> --info                   # list files, no download
    npx gitfold <url> --token ghp_xxxx         # use GitHub token
    npx gitfold <url> --format tar.gz          # download as tar.gz

---

## Tier limits

| Tier   | Max files | How to unlock                              |
|--------|-----------|--------------------------------------------|
| Free   | 50        | Default (no token, no login)               |
| Token  | 200       | GitHub PAT header or sign in with GitHub   |
| Pro    | 1,000     | Subscribe at gitfold.cc/pricing            |
| Power  | 5,000     | Subscribe at gitfold.cc/pricing            |

Max directory size: 100 MB per request (all tiers).

GitHub API rate limits:
- No token: 60 req/hour
- With GitHub token / OAuth: 5,000 req/hour

---

## Web UI

https://gitfold.cc — paste any GitHub tree URL, click Download.

Bookmarklet: drag `javascript:window.location.href=window.location.href.replace('github.com','gitfold.cc')` to bookmarks bar for one-click downloads on GitHub.

---

## Source code

https://github.com/chrisye96/gitfold (MIT license)
Runs on Cloudflare Workers + Pages + D1 + R2.