krz/skunky-art

 1# API
 2
 3JSON endpoints under `/api`. Read-only, no authentication, no state.
 4
 5Every response is `application/json`. Errors are `{"error":"..."}` with a real
 6HTTP status — 400 for a bad request, 403 when the instance forbids the content,
 7404 for an unknown endpoint or deviation, 502 when DeviantArt fails.
 8
 9An instance's settings apply here exactly as they do to the pages. `hide-ai`
10omits AI work from listings, `nsfw` gates mature content, and both are decided
11by the same predicate the HTML listing uses, so the API cannot serve what the
12site withholds.
13
14Media URLs point back at this instance when `proxy` is on, so a consumer never
15has to talk to wixmp itself.
16
17## GET /api/instance
18
19Version and the instance's settings.
20
21    {"version":"1.4.0","settings":{"nsfw":false,"proxy":true,"hide-ai":false,"theme":"auto"}}
22
23## GET /api/search
24
25Parameters:
26
27* `q` — required. The search query.
28* `type` — `a` art (default), `t` text, `g` gallery, `f` favourites.
29* `usr` — required for `g` and `f`; the user whose gallery or favourites to read.
30* `p` — page number, default 0.
31
32    {
33      "query": "fox",
34      "type": "a",
35      "page": 0,
36      "results": [
37        {
38          "id": 123456789,
39          "title": "A Title",
40          "author": "alice",
41          "url": "https://instance/post/alice/a-title-123456789",
42          "published": "2026-01-02T15:04:05Z",
43          "nsfw": false,
44          "ai": false,
45          "daily_deviation": false,
46          "tags": ["cats"],
47          "preview": "https://instance/media/file/...",
48          "fullview": "https://instance/media/file/...",
49          "favourites": 7,
50          "views": 99
51        }
52      ]
53    }
54
55`results` is always an array; an empty page is `[]`, never `null`.
56
57## GET /api/post/{author}/{postname}
58
59One deviation. `postname` carries the numeric id the way the site's own URLs do,
60e.g. `a-title-123456789`.
61
62Returns the fields above plus `description`, `downloads`, `filesize`, `width`
63and `height`.
64
65Gated on `nsfw` only, matching the page: `hide-ai` omits AI work from listings,
66and a reader following a direct link to one still gets it.
67
68## GET /api/random
69
70A random artwork's media — the image itself, not JSON. Honours `nsfw`.