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](/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).

MacWall Public API & Machine-Readable Feeds

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, which links to every endpoint and its OpenAPI description.

Catalog: GET /api/wallpapers

Paginated public wallpaper catalog. Same data that powers the web gallery.

`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. 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 — RFC 9727 API catalog in `application/linkset+json`.
/openapi.json — OpenAPI 3.1 description of the endpoints above.
/llms.txt — curated Markdown index of the whole site for language models.
/llms-full.txt — every content page concatenated as one Markdown document.
/rss.xml, /atom.xml, /feed.json — blog feeds in RSS 2.0, Atom 1.0, and JSON Feed 1.1.
/sitemap.xml and /robots.txt — crawl surface.
/ai.txt and /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.
Send a descriptive `User-Agent` with a contact URL so we can reach you before rate limiting you.

Public API and machine-readable feeds