Moodboard data from the Aesthetics Wiki, normalized into clean JSON and presented through an Acid Design interface.

Landing Page · Technical Documentation · Quick Start · Endpoint Reference · License

---

✦ SYSTEM OVERVIEW

Aesthetics API turns a visual index of internet aesthetics into a small, predictable, read-only API. Each record contains a stable slug, display name, source page, portable image filename, original image source, and a resolved image URL.

┌──────────────────────┐
│   Aesthetics Wiki    │
│  moodboards + links  │
└──────────┬───────────┘
           │ scrape + normalize
           ▼
┌──────────────────────┐
│   aesthetics.json    │
│  structured records  │
└──────────┬───────────┘
           │ load once
           ▼
┌──────────────────────┐
│       FastAPI        │
│ search · random · ID │
└──────────┬───────────┘
           │
      ┌────┴────┐
      ▼         ▼
    JSON      images
 local / CDN / source

Core characteristics

Signal	Value
Dataset	219 aesthetics
Authentication	None
API style	Read-only REST
Response format	JSON
Image delivery	Local filesystem, custom CDN, or original source
Browser access	CORS-enabled
Interactive API docs	Swagger UI and ReDoc through FastAPI
Frontend	Static HTML, CSS, and JavaScript
Visual system	Acid Design / Acidgrafix

---

⌁ WHAT A RECORD LOOKS LIKE

{
  "slug": "acid-design",
  "name": "Acid Design",
  "aesthetic_url": "https://aesthetics.fandom.com/wiki/Acid_Design",
  "image": "acid-design.png",
  "source_image_url": "https://static.wikia.nocookie.net/.../revision/latest",
  "image_url": "http://127.0.0.1:8000/images/acid-design.png"
}

The stored image value remains a bare filename. The API resolves image_url at request time, allowing the same dataset to work with local files, a private object store, a public CDN, or the original source host.

---

⚡ QUICK START

1. Create an isolated Python environment

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell:

.venv\Scripts\Activate.ps1

2. Install the runtime

python -m pip install --upgrade pip
pip install "fastapi[standard]" uvicorn requests beautifulsoup4

3. Confirm the required data exists

api.py
aesthetics.json
images/

4. Start the API

uvicorn api:app --reload --host 127.0.0.1 --port 8000

5. Verify the service

curl http://127.0.0.1:8000/healthz

Expected response:

{
  "status": "ok",
  "count": 219,
  "image_mode": "local"
}

Open the generated API documentation:

http://127.0.0.1:8000/docs
http://127.0.0.1:8000/redoc

---

◎ ENDPOINT REFERENCE

Method	Route	Purpose
GET	/aesthetics	Return the complete collection.
GET	/aesthetics/{slug}	Return one aesthetic by slug.
GET	/aesthetics/{slug}/image	Return or redirect to the moodboard image.
GET	/random	Return one random aesthetic.
GET	/search?q={query}	Search names using a case-insensitive substring.
GET	/healthz	Report service health, record count, and image mode.

Retrieve the collection

curl -s http://127.0.0.1:8000/aesthetics | jq

Retrieve one record

curl -s http://127.0.0.1:8000/aesthetics/cottagecore | jq

Search by name

curl -s "http://127.0.0.1:8000/search?q=core" | jq

Download an image

curl -L \
  -o acid-design.png \
  http://127.0.0.1:8000/aesthetics/acid-design/image

Request a random aesthetic

const response = await fetch("http://127.0.0.1:8000/random");

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const aesthetic = await response.json();
console.log(aesthetic.name, aesthetic.image_url);

---

⌘ CONFIGURATION

The runtime can be configured without changing the dataset.

Variable	Purpose	Default
AESTHETICS_DATA	Path to the JSON dataset.	./aesthetics.json
IMAGE_MODE	Image strategy: local, cdn, or source.	local
IMAGE_DIR	Local moodboard directory.	./images
IMAGE_BASE_URL	Public base URL for CDN mode.	unset
PUBLIC_API_BASE	Public API origin used to build absolute local URLs.	inferred

Example local configuration:

export AESTHETICS_DATA="./aesthetics.json"
export IMAGE_MODE="local"
export IMAGE_DIR="./images"

uvicorn api:app --host 0.0.0.0 --port 8000

Example CDN configuration:

export IMAGE_MODE="cdn"
export IMAGE_BASE_URL="https://cdn.example.com/aesthetics"

Image delivery modes

Mode	Behavior
local	Serves files from IMAGE_DIR through the API or a static mount.
cdn	Joins IMAGE_BASE_URL with each record's image filename.
source	Resolves to the original image URL stored in the dataset.

---

✹ ACID DESIGN INTERFACE

The project includes two static browser interfaces built from real HTML, CSS, and JavaScript components:

File	Role
index.html	Visual landing page, endpoint overview, examples, and API explorer.
docs.html	Dense technical documentation with architecture, schemas, deployment, and troubleshooting.
styles.css	Shared landing-page Acid Design system.
script.js	Navigation, tabs, copy actions, and interactive explorer behavior.
docs.css	Technical documentation layout and component styling.
docs.js	Documentation navigation, tabs, copy actions, and expandable panels.

Run the frontend separately with any static server:

python3 -m http.server 8080

Then open:

http://127.0.0.1:8080/index.html
http://127.0.0.1:8080/docs.html

The API explorer calls the base URL configured in the interface. Start FastAPI first and confirm that the selected origin is allowed by CORS.

Full interface preview

---

◉ RECOMMENDED PROJECT LAYOUT

.
├── api.py
├── scraper.py
├── aesthetics.json
├── images/
│   └── *.png
├── index.html
├── docs.html
├── styles.css
├── docs.css
├── script.js
├── docs.js
├── assets/
│   ├── chrome-aesthetics.png
│   ├── chrome-smiley.png
│   ├── credit-texture.png
│   ├── readme-hero.png
│   └── readme-full-preview.png
└── README.md

---

⧉ PRODUCTION NOTES

The dataset is small enough to load once at application startup. Keep indexed lookups in memory rather than scanning the full list on every request.

For production deployment:

• run behind a reverse proxy or managed platform;
• set an explicit public API origin when generating absolute image URLs;
• restrict CORS to known frontend origins when the API is not intended for unrestricted public use;
• place large image collections on object storage or a CDN;
• preserve the per-record source link for attribution;
• treat the JSON file as versioned source data rather than mutable application state.

A minimal container command is:

CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "8000"]

The complete deployment and troubleshooting reference is available in docs.html.

---

☻ USE CASES

• aesthetic search and discovery tools;
• moodboard generators;
• design-reference applications;
• wallpapers and daily visual prompts;
• labeled retrieval and classification experiments;
• generative-art pipelines;
• REST API education and prototyping;
• plugins that need a lightweight aesthetic vocabulary.

---

⌖ LICENSE & ATTRIBUTION

Text and structured data

Names, links, and source material derived from the Aesthetics Wiki are subject to the Wiki's CC BY-SA 3.0 terms. Reuse must include appropriate attribution, a license reference, notice of modifications, and share-alike treatment where required.

Every API record retains its aesthetic_url so attribution can remain connected to the corresponding source article.

Moodboard images

Moodboard images are not automatically covered by the text/data license. Rights remain with their original creators. Images should be treated as reference or research material unless the individual source and usage rights have been verified.

Project code and interface

Add the repository's chosen software license in a root LICENSE file and update this section to match it before public release.

---

✦ CONTRIBUTING

Contributions should preserve four properties:

1. Traceability — retain source URLs and attribution data.
2. Determinism — produce stable slugs and predictable JSON fields.
3. Portability — keep image filenames independent from their delivery host.
4. Clarity — avoid adding authentication, state, or complexity without a concrete need.

Before submitting changes, verify the dataset and exercise the primary routes:

python -m json.tool aesthetics.json > /dev/null
curl -f http://127.0.0.1:8000/healthz
curl -f http://127.0.0.1:8000/aesthetics/acid-design
curl -f "http://127.0.0.1:8000/search?q=core"

---

GIVE CREDIT · KEEP IT REAL

AESTHETICS DB // FASTAPI // ACID SYSTEMS // NO AUTH // JUST DATA