# Wavey Gist Wavey Gist publishes small, shareable UTF-8 text gists at https://gist.wavey.info. A gist contains 1–32 flat files, up to 1 MiB total. Markdown, source code, and plain text are supported. ## Bases - Public frontend: https://gist.wavey.info - API base: https://api.wavey.info/api/v1 - Publishing API auth: Authorization: Bearer - Use the gist id exactly as returned in API field `id`. ## Recommended Helper Use `publish-gist` for text gists. Public reads need no key. Writes use optimistic concurrency, never retry blindly, and can verify every file in the exact new revision. Read the latest revision as JSON: ```sh publish-gist --read --gist --json ``` `--json` returns the complete API representation, including file text. Use `--summary-json` for URL, revision, snapshot, and file metadata without file text or rendered HTML. Without either JSON option, read mode prints the primary file. Use `--output-dir ` to materialize every file. A revision URL reads that exact revision. Create one file from stdin or disk: ```sh publish-gist --file README.md --verify --summary-json ``` Create multiple files by repeating `--file`: ```sh publish-gist --file README.md --file example.py --title 'Example' --verify --summary-json ``` Each `--file` path is published under its basename; basename collisions are rejected. The primary file is exact `README.md` when present, otherwise the first Markdown filename alphabetically, otherwise the first filename alphabetically. Update an owned gist. The helper reads the latest snapshot, overlays the supplied basenames, and sends one conflict-safe full snapshot: ```sh publish-gist --gist --file README.md --file example.py --verify --summary-json ``` Use repeated `--delete-file ` to remove files. Use `--clear-title` to clear an explicit title. A revision URL still targets the latest gist for updates. Writes require `WAVEY_GIST_API_KEY`. If a conflict occurs, re-read and reconcile. If post-write verification fails, the helper reports the already-created revision; inspect it and do not publish again automatically. ## Public Reading These routes do not require authentication: - GET https://gist.wavey.info/{gist_id}: rendered latest gist. - GET https://gist.wavey.info/{gist_id}/raw: raw primary file for the latest revision. - GET https://gist.wavey.info/{gist_id}/raw/{filename}: raw named file for the latest revision. - GET https://gist.wavey.info/{gist_id}/revisions/{revision_number}: rendered immutable revision. - GET https://gist.wavey.info/{gist_id}/revisions/{revision_number}/raw: raw primary file for that revision. - GET https://gist.wavey.info/{gist_id}/revisions/{revision_number}/raw/{filename}: raw named file for that revision. - GET https://gist.wavey.info/{gist_id}/diff/{from_revision}..{to_revision}: directional multi-file diff between two distinct revisions. - GET https://api.wavey.info/api/v1/gists/{gist_id}/render: rendered JSON for the latest revision. - GET https://api.wavey.info/api/v1/gists/{gist_id}/revisions/{revision_number}/render: rendered JSON for one revision. ## Find Your Gists Search requires your gist API key and returns only active gists owned by that key. It searches each latest revision's id, title, filenames, and file text; it does not search old revisions. ```sh curl -sSG https://api.wavey.info/api/v1/gists \ -H "Authorization: Bearer $WAVEY_GIST_API_KEY" \ --data-urlencode 'q=vault fees' ``` Space-separated terms are case-insensitive literal AND terms. Results are compact summaries without file text. Use `limit` (1–100), `offset`, and `sort=relevance|updated|created`; responses include filtered `pagination.total` and `pagination.next_offset`. Omit `q` to browse owned gists, then read a result by id or URL. ## Direct Publishing API Use `Authorization: Bearer `. Requests reject unknown fields. File names are NFC-normalized flat names: no `/`, `\`, dot segments, surrounding whitespace, control/format characters, or case-fold collisions. Each name is at most 255 UTF-8 bytes. ### Create ```sh curl -sS https://api.wavey.info/api/v1/gists \ -H "Authorization: Bearer $WAVEY_GIST_API_KEY" \ -H "Content-Type: application/json" \ --data '{"title":"Example","files":{"README.md":{"content":"# Example\n\nHello."},"example.py":{"content":"print(42)\n"}}}' ``` ### Update First read the latest gist. Direct API PATCH requires its `snapshot_sha256`. A supplied `files` object is the complete replacement snapshot, not an overlay, so include every file that should remain. A title-only PATCH may omit `files`. The recommended helper differs: it reads the latest snapshot, overlays supplied basenames, and submits the resolved complete snapshot. ```sh curl -sS -X PATCH https://api.wavey.info/api/v1/gists/{gist_id} \ -H "Authorization: Bearer $WAVEY_GIST_API_KEY" \ -H "Content-Type: application/json" \ --data '{"files":{"README.md":{"content":"# Example\n\nUpdated."}},"expected_snapshot_sha256":""}' ``` Only the owner key can update or delete a gist. A stale snapshot returns `409`; a non-owned or missing gist returns `404`. ### Create Or Update With Images Send multipart form data with exactly one `payload` field containing the same JSON object and repeated `images[]` file fields. Reference an image from any Markdown file as `attachment:`. Unreferenced images are appended to the Markdown lead file. ```sh curl -sS https://api.wavey.info/api/v1/gists \ -H "Authorization: Bearer $WAVEY_GIST_API_KEY" \ -F 'payload={"title":"Chart","files":{"README.md":{"content":"# Chart\n\n![Chart](attachment:chart.png)"}}}' \ -F 'images[]=@chart.png' ``` A standalone image upload uses POST `/api/v1/images` with one multipart `image` field. Markdown may also embed absolute external HTTPS image URLs. They load directly from the remote host in each reader's browser, can change or disappear, and expose the reader's IP address to that host even though Wavey Gist sends no referrer. Use uploaded Wavey images for stable archived content. HTTP, relative, malformed, and unsafe image URLs render as escaped alt text. ### Delete ```sh curl -sS -X DELETE https://api.wavey.info/api/v1/gists/{gist_id} \ -H "Authorization: Bearer $WAVEY_GIST_API_KEY" ``` ## Response Shape Create, update, authenticated read, and public render payloads include: - `id`, shareable `url`, optional `title`, and resolved `display_title`. - `primary_file` and a `files` object keyed by filename. - `snapshot_sha256`, which covers the title, filenames, and every file content digest. - `revision_number`, `latest_revision_number`, `created_at`, and `updated_at`. - Each file includes `filename`, `content`, `content_sha256`, `byte_size`, and `raw_url`. - Public render responses additionally include each file's `kind`, `language`, and sanitized `rendered_html`, plus revision history. ## Browser And Account Routes - GET https://api.wavey.info/api/v1/gists/{gist_id}: authenticated latest snapshot. - POST https://api.wavey.info/api/v1/auth/session with JSON `{"api_key":"..."}`: create a web session. - GET https://api.wavey.info/api/v1/me/gists: searchable, paginated owned-gist summaries and stats for the web session. - GET https://gist.wavey.info/me/raw: searchable plain-text owned-gist list for the logged-in session; accepts `q`, `limit`, `offset`, and `sort`. - GET https://gist.wavey.info/api/me/gists: searchable JSON owned-gist list for the logged-in session. - GET or PUT https://gist.wavey.info/api/me/notification-settings: alert preferences. - PUT or DELETE https://gist.wavey.info/api/me/push-subscriptions: enroll or remove the current browser. ## Notes For Agents - Gist URLs are bearer-capability URLs. Anyone with one can read its files. - Gist ids are base62 strings containing 16–64 ASCII letters or digits. Do not guess or enumerate them. - Preserve user content unless asked to edit it. Never print or publish API keys, secrets, or private identifiers. - Prefer a self-contained lead Markdown file beginning with a non-empty `# Title`; code/plain-text leads should have an explicit gist title. - Mermaid fences are supported in Markdown and are rendered with strict security settings. - Math uses GitHub-style dollar delimiters, dollar-backtick inline syntax, and fenced `math` blocks.