Weekend Wanderer API Reference

Liveness probe. Unversioned (note the missing /v1), unauthenticated and unthrottled, and the only endpoint that answers outside the success/data/message envelope — the payload is the top-level object.

Everything the rendered homepage shows, from the same source, so the two cannot drift apart. Sections are cached for 300 seconds; the cache key folds in the resolved category ids and the next scheduled publication, so a renamed category or an article falling due is reflected immediately.

The two categories come from configured slugs, but those are only a preference — categories are created and deleted freely in the admin panel. When a slug no longer resolves, the section falls back to whichever real category currently holds the newest matching published article, preferring one the other section is not already using. On an empty site either can still be null, in which case its article array is []. Clients must hide the section and its “view all” link when the category is null rather than linking to a slug that would 404.

Returns a paginated list of published articles (15 per page).

Query Parameters

Returns a single published article by slug; an unpublished, future-dated or unknown slug is a 404. Increments the view counter once per IP, so repeat requests from the same client do not inflate view_count. Includes the sanitized HTML body, a toc array built from its headings, and up to 4 related articles (same category, topped up from same tags, then latest).

Note: The article's canonical web page at /articles/{slug} also emits full Open Graph (og:title, og:description, og:image, og:url, og:type, article:published_time, article:section) and Twitter Card (twitter:card summary_large_image, twitter:title, twitter:description, twitter:image) meta tags for rich social sharing previews.

Returns all categories ordered by name — not paginated, so there is no links/meta wrapper here. article_count counts only published articles, so it matches exactly what /categories/{slug} will page through. (The admin listing counts drafts and binned articles too, and so can report a higher number for the same category.)

Returns a category and its paginated published articles (15 per page).

Returns all tags ordered by name — not paginated. Each carries a published-only article_count. Fields: id, name, slug, article_count — tags have no description.

Returns { "tag": { ... }, "articles": { "data", "links", "meta" } } — the tag plus its published articles, 15 per page. Mirrors /categories/{slug}.

Searches published articles by title and body text, 15 per page, newest first. Matching is case- and accent-insensitive, so cafe finds “CAFÉ”; %, _ and \ are treated as literals rather than wildcards. If q is omitted or empty, returns all published articles. The response is the same paginated envelope as /articles — data.data, data.links, data.meta — with no separate query echo.

Query Parameters

Logs a click and returns the partner URL. Despite the path, it does not issue an HTTP redirect — it answers 200 with the usual envelope, and the client navigates to data.redirect_url itself. Unknown slugs return 404. The returned URL is always http or https; other schemes are rejected at write time.

Returns public site settings: site_name, site_description, ga_id, contact_email, site_logo and site_favicon. No other key is exposed.

Unlike the admin endpoint, site_logo and site_favicon here are ready-to-use absolute URLs, not stored paths, and fall back to the bundled assets when nothing has been uploaded — so they are never empty. They are derived from APP_URL rather than the requesting host, so a stale APP_URL in production yields URLs the client cannot reach.

Subscribes an email address. Returns 201 on first subscription, 409 if already subscribed.

Body (JSON)

Stores a contact message. Returns 201 on success.

Body (JSON)

Authenticates using email and password. Returns a 24-hour Bearer token. Rate-limited to 5 attempts per 15 minutes.

Body (JSON)

Revokes the current token. No body required.

Paginated list, 15 per page, newest first. ?status=all|published|draft|trashed (default all; an unrecognised value falls back to all rather than erroring). ?search= matches the title only. status=published includes future-scheduled articles, which the public endpoints hide.

Create an article. Responds 201. If a soft-deleted article already holds the requested slug it is recycled instead: the binned row is restored in place, keeping its id, resetting view_count to 0 and discarding what it previously contained.

Get a single article by numeric ID. Non-numeric ids do not match the route and return 404.

Update an article. Full-representation: title, slug, content and category_id are required on every call, and omitting is_published or is_featured resets them to false. Binned articles cannot be edited — restore first, or this returns 404.

Identical to PUT — same handler, same required fields. This is not a partial update.

Soft-delete an article. It leaves the public endpoints but stays retrievable under ?status=trashed.

Restore a soft-deleted article. Returns the restored article.

Permanently delete an article that is already in the bin — it must be soft-deleted first, or this returns 404. Irreversible: the row, its tag links and its uploaded image are all removed.

Paginated list ordered by name, 20 per page — not the full set in one response.

Create a category. Responds 201.

Update a category. Full-representation: name and slug are required on every call.

Identical to PUT — same handler, same required fields.

Delete a category. Returns 409 if any article still points at it, including soft-deleted ones sitting in the bin.

Paginated list ordered by name, 20 per page — not the full set in one response. article_count includes drafts and binned articles.

Create a tag. Responds 201.

Update a tag. Full-representation: name and slug are required on every call.

Identical to PUT — same handler, same required fields.

Delete a tag. Unlike categories this always succeeds: the tag is detached from every article first rather than refused.

Paginated list ordered by name, 20 per page — not the full set in one response. Each entry carries id, name, slug, url, click_count, created_at and updated_at.

Create an affiliate link. Responds 201 with click_count at 0.

Update an affiliate link. Full-representation: name, slug and url are required on every call.

Identical to PUT — same handler, same required fields.

Delete an affiliate link and its recorded clicks. Returns 409 while any article body still embeds an [affiliate] shortcode for its slug, since deleting would leave those articles pointing at a dead /out/{slug} link — the message names how many.

Paginated list of newsletter subscribers (15 per page), newest first. Each entry carries id, email and created_at.

Exports all newsletter subscribers as a downloadable CSV. This is the one admin endpoint that does not return the JSON envelope: the response is text/csv; charset=utf-8 with Content-Disposition: attachment; filename=subscribers-YYYY-MM-DD.csv.

Permanently removes a subscriber.

Paginated list of contact form messages (15 per page), newest first. Each entry carries id, name, email, message, is_read and created_at.

Flips is_read and returns the updated message. It toggles rather than sets, so there is no way to force a particular state — send it twice and you are back where you started. PATCH only; PUT is not routed.

Permanently deletes a contact message.

Retrieve all website settings (including non-public administration settings).

Update website settings. Supports JSON or multipart/form-data for logo and favicon image uploads.

Same handler as POST. Use POST when uploading files, since multipart bodies are not parsed on PUT.

The authenticated admin account: id, name, email and created_at. No password field is ever returned.

Update name and email, and optionally the password. Full-representation: name and email are required on every call. PATCH is not routed. A wrong current_password is a 422 carrying errors.current_password. Changing the password revokes every other token on the account — the token making the call survives, all others stop working immediately.

Dashboard summary metrics.