# Gists

Gists share a small set of text files without creating a repository. Browse
public Gists at `/gists`, or sign in and choose **New gist**.

## Visibility

- **Public** Gists appear in public discovery and are readable by direct URL.
- **Unlisted** Gists do not appear in public discovery, but anyone with the
  opaque URL can read them. Unlisted is link sharing, not private storage.

Only the owner can edit a Gist. The owner or a platform administrator can
delete it.

Each Gist also appears on its owner's profile. Use the Gist browser to search
public Gists by description or filename, or switch to **Yours** to search your
own public and unlisted Gists.

## Revisions, stars, and forks

Every create or update records a complete immutable revision. The history
panel can open a stable revision URL without changing the current Gist. A Gist
keeps at most 100 revisions, and an account can retain at most 100 MiB of Gist
revision history.

Signed-in users can star a Gist once. Forking always names an exact source
revision, copies that snapshot into a new Gist, and preserves its lineage even
if the source Gist is later removed. The new fork starts with the source
revision's description, visibility, and files; its owner can edit it normally.

## Limits

A Gist contains between one and ten root-level files. Filenames cannot contain
path separators or control characters.

| Limit | Value |
| --- | ---: |
| Filename | 128 characters |
| Description | 256 characters |
| One file | 256 KiB |
| One Gist | 1 MiB |
| One account | 100 Gists and 25 MiB |
| Revision history | 100 revisions per Gist and 100 MiB per account |
| Search query | 64 characters |
| Authenticated mutations | 120 per hour |

The web editor validates names before submission. The API enforces every limit
using UTF-8 byte counts, and the database also enforces the per-account storage
boundary.

## API access

Personal access tokens use `gist:read` for reads and `gist:write` for creates,
updates, and deletes. Gist scopes are account-wide and cannot be constrained to
a repository.

The API supports public and owner listings, metadata search, creation, direct
reads, raw file responses, immutable revision reads, stars, exact-revision
forks, full-file-set updates, and deletion. Raw responses use `text/plain;
charset=utf-8` and disable content sniffing.

Search uses an FTS5 virtual table. Before exporting a D1 database, follow
Cloudflare's virtual-table export procedure: temporarily drop the search
virtual table, export, then recreate and repopulate the index from canonical
Gist metadata. The Gist and revision tables remain the source of truth.

See [`llms.txt`](../../llms.txt) for request and response examples.

## Version boundary

Gists do not provide comments, private collaborator access, or Git transport.
Updating a Gist replaces its current file set while retaining the previous
snapshot as an immutable revision.