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 Anime, Nature, Cars, Gaming, Space, Heroes, Dark, Abstract, Others.
- `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`. `videoUrl` is a downscaled, silent web preview, not the source file; full-resolution wallpapers are only available in the app.
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
- /ai-info and /ai-info.md: canonical product facts, limitations, source precedence, and assistant guidance.
- /.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: combined long-form product, documentation, learning, blog, and comparison text.
- /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.