---
title: "MacWall Public API & Machine-Readable Feeds"
description: "Read-only MacWall endpoints for the wallpaper catalog and release metadata, plus the RSS, JSON Feed, llms.txt, and API catalog documents that describe this site."
canonical: "https://macwall.app/docs/public-api"
published: "2026-08-02"
updated: "2026-08-02"
keywords:
  - "macwall api"
  - "wallpaper api"
  - "macwall rss feed"
  - "macwall llms.txt"
  - "api catalog"
---

# Public API and machine-readable feeds

Read-only MacWall endpoints for the wallpaper catalog and release metadata, plus the RSS, JSON Feed, llms.txt, and API catalog documents that describe this site.

MacWall publishes a small read-only HTTP surface plus a set of discovery documents. Everything below is public, unauthenticated, JSON or text, and CDN-cached. Machine clients should start at [/.well-known/api-catalog](https://macwall.app/.well-known/api-catalog), which links to every endpoint and its OpenAPI description.

## Catalog: GET /api/wallpapers

Paginated public wallpaper catalog. Same data that powers [the web gallery](https://macwall.app/wallpapers).

- `q` — free-text search across name and tags.
- `category` — one of Nature, Space, Anime, Cars, City, Video Games, Sci-fi, Fantasy, Cats.
- `tag` — filter by a single tag.
- `sort` — `newest` (default), `popular`, or `older`.
- `page` — 1-based page number, default `1`.
- `limit` — items per page, default `24`.

Returns `{ wallpapers, total, page, limit, hasMore }`. Each wallpaper includes `id`, `name`, `category`, `tags`, `resolution`, `durationSeconds`, `fileSizeBytes`, `thumbUrl`, `videoUrl`, `isPro`, `isFeatured`, `likeCount`, and `createdAt`. Pro assets are marked with `isPro` and require a license in the app to use.

## Releases: GET /api/installers/releases/version.json

Current release metadata — `version`, optional `build`, a download `url`, and optional `notes`. This is the same feed the in-app updater reads and the source for [the changelog](https://macwall.app/changelog). It is intentionally uncached so a new build is visible immediately.

## Installer: GET /download/latest

Stable path that `302`-redirects to the current signed DMG. Link to this rather than a versioned file so your link never goes stale.

## Discovery documents

- [/.well-known/api-catalog](https://macwall.app/.well-known/api-catalog) — RFC 9727 API catalog in `application/linkset+json`.
- [/openapi.json](https://macwall.app/openapi.json) — OpenAPI 3.1 description of the endpoints above.
- [/llms.txt](https://macwall.app/llms.txt) — curated Markdown index of the whole site for language models.
- [/llms-full.txt](https://macwall.app/llms-full.txt) — every content page concatenated as one Markdown document.
- [/rss.xml](https://macwall.app/rss.xml), [/atom.xml](https://macwall.app/atom.xml), [/feed.json](https://macwall.app/feed.json) — blog feeds in RSS 2.0, Atom 1.0, and JSON Feed 1.1.
- [/sitemap.xml](https://macwall.app/sitemap.xml) and [/robots.txt](https://macwall.app/robots.txt) — crawl surface.
- [/ai.txt](https://macwall.app/ai.txt) and [/crawlers](https://macwall.app/crawlers) — AI and crawler usage policy.

## Markdown twin of every page

Append `.md` to any content URL to get a clean Markdown version with YAML frontmatter — for example `/blog/what-is-macwall-complete-guide.md` or `/docs/public-api.md`. These responses are `text/markdown` and `noindex`, so they exist for agents and pipelines without competing with the HTML page in search.

## Fair use

- Cache responses and keep request rates reasonable — these endpoints are shared infrastructure, not a bulk export.
- Hotlinking video files is discouraged; link to the wallpaper page or the app deep link instead.
- Wallpaper videos are licensed for use inside MacWall and are not redistributable — see [Terms](https://macwall.app/terms).
- Send a descriptive `User-Agent` with a contact URL so we can reach you before rate limiting you.

## Frequently asked questions

### Do I need an API key?

No. These endpoints are public and unauthenticated. There is no write API and no user data exposed.

### Is the API versioned?

Response shapes are additive — new fields may appear, existing ones are not renamed or removed without notice in [the changelog](https://macwall.app/changelog).

### Can I use the catalog data in my own app?

Metadata, yes, with attribution and a link back to macwall.app. The wallpaper videos themselves are licensed for MacWall use only. Ask first at [support@macwall.app](mailto:support@macwall.app).

---

Source: https://macwall.app/docs/public-api