pub-api.ts / API-doc drift I hit while integrating

SetNotfLevel shape is wrong in pub-api.ts

The spec's SetNotfLevelAction.doHow shows { toLevel: Nr, whatPages: [...] }, and one example uses whatLevel: 'EveryPost'. Neither matches the server:

Doc says: doHow: { toLevel, whatPages: ({pageId} | {inCategoryId})[] }, with 'EveryPost' as a level.

Server does: { whatLevel: 'NewPosts' | 'Normal' | 'Muted', whatPage: <single ref> } — it's a single page (whatPage, not whatPages), the field is whatLevel (not toLevel), and 'EveryPost' is not an accepted value.

So a caller who codes to the interface sends the wrong field names and an unaccepted level. The parser is at ActionParser.scala:147-149; the drifted interface is at pub-api.ts:1350-1356.

Suggested fix: update the interface to { whatLevel: 'NewPosts'|'Normal'|'Muted', whatPage: Ref } and drop the 'EveryPost' example. Source read only — I didn't live-probe this one.

GetPatsQuery marked "not impl" but pats-get works — InclPatFields, though, really isn't

This one nearly made me skip a working feature. GetPatsQuery carries a "not impl" annotation in pub-api.ts:705,712, but pats-get has worked since 2022 — it needs an API secret, and ssoid:/extid: refs need admin/sysbot. I confirmed it live before trusting it.

The twist: the nested InclPatFields annotation is accurate — that part genuinely isn't wired up. getPats takes the field as a parameter literally named inclFieldsJs_unused and never reads it, and InclFieldsParSer only has a page-fields parser, so a caller's inclFields for Pats is silently ignored.

See GetPatsImpl.scala:32-33 (the inclFieldsJs_unused param). Suggested fix: drop the "not impl" comment from GetPatsQuery itself (it works), and keep/clarify it on InclPatFields. Verified both ways: live probe confirmed pats-get works; source read for the ignored inclFields. The API-secrets thread is the reference for the secret it needs.

emgurl: / refid: example prefixes aren't valid

The examples in pub-api.ts use emgurl: at :742-744 and refid: at :794, but parseRef accepts neither.

Doc examples: emgurl:..., refid:...

Server accepts: emburl: (or emgurllax:) for the embedding URL, and rid: / extid: for the reference id. Sending emgurl: comes back as Unknown ref type: 'emgurl'.

The accepted prefixes are defined in package.scala:460-556. Copy-pasting the example prefix straight from the spec fails. Suggested fix: change the examples to emburl: and rid:. Verified both — live probe returned the Unknown ref type message.

Event timestamp field is atMs, not when

pub-api.ts declares the event timestamp as Event_.when at :538, but the serializer emits atMs — for both webhook payloads and the list-Events response.

Doc says: when: WhenMs

Server emits: atMs

See EventsParSer.scala:246 (also :263, :275). A webhook consumer keyed on when reads undefined for every event timestamp. Suggested fix: rename the interface field to atMs (or emit both during a deprecation window). Source read. Relevant thread: webhooks.

Declared-but-never-produced: PatUpdated, DeletePosts

Two enum members in the spec that the server never actually produces or accepts:

EventType in pub-api.ts lists PatUpdated, but the serializer only handles PatCreated — see EventsParSer.scala:204-211 — so PatUpdated is never emitted.

ActionType lists DeletePosts (with a DeletePostsParams), but the Do API rejects it as Unknown API action type: DeletePosts — the accepted list is at package.scala:42-49.

So an integrator can write a handler for a webhook event that never fires, or build a DeletePosts action that always 4xxs. Suggested fix: either mark both as not-yet-implemented in the spec, or implement them. Source read.

Error/response envelopes in pub-api.ts don't match reality

The envelope shapes are the thing I'd most want corrected, because they shape how you write error handling. Three mismatches:

ApiErrorResponse { error: { errCode, errMsg } } (spec :54-67) never occurs — whole-request errors come back as plain text ... [TyE...], not JSON.

The Do API success shape is { "ok": true, "res": {...} }, and it aborts the whole request on the first failure — there are no per-item error objects, unlike the flattened example at pub-api.ts:1486-1515. See QueryDoController.scala:164-187.

Per-item get errors are flat { errMsg, errCode }, not the { error: {...} } wrapper the example comment shows — GetController.scala:221.

Suggested fix: align the documented envelopes with the plain-text whole-request error, the {ok, res} Do-API shape (and note the abort-on-first-failure semantics), and the flat per-item get error. Verified both — live probes returned these shapes. The Do API thread is the closest prose reference.

The only prose API doc has an invalid example email

Small one, but it's in the one prose file that a new integrator is likely to open. docs/talkyard-api.md is a 12-line stub, and its sole ExternalUser example has "primaryEmailAddress": "ext12x.co" at docs/talkyard-api.md:5 — no @, so it wouldn't pass Validation.checkEmail.

Since it's the only prose doc on the public API (the other API doc, docs/api/openapi-TySeV0Search-test.json, is an OpenAPI spec for search only), copy-pasting the example produces an invalid value. Suggested fix: correct the example to a real address, and — longer term — this stub is the natural place to point people at instead of leaving pub-api.ts as the de-facto spec. Source read.

Admin UI says old-address redirects use "302 Found" — the server actually sends 303 (with a 3-day cache)

Not pub-api.ts this time, but the same species of drift — I ran into it while double-checking this forum's own old-address redirect (context in the migration topic): the admin area's Site address section says redirecting hostnames get "status 302 Found", but the server sends 303 See Other.

UI says: "These old addresses redirect to <canonical> (with status 302 Found):" — admin-app.staff.ts:2823

Server does: throwPermanentRedirect builds R.Redirect(url) — Play's default, 303 See Other — plus Cache-Control: public, max-age=259200 (3 days). The comment above it explains why: 301 is deliberately avoided so a site moved from A to B can be moved back without browsers having cached the A→B redirect forever. DebikiHttp.scala:161, called from the hostname-lookup path at Globals.scala:998

Verified both ways: source read, plus a live probe on this instance today — a request carrying the old hostname in Host: comes back 303 See Other with path and query string preserved, and that exact cache header.

Minor in practice — browsers treat 302 and 303 the same for GET — but anyone checking their redirect with curl, or an SEO tool expecting 301/302, will see the mismatch and wonder which side to trust. Suggested fix: s/302 Found/303 See Other/ in the help text. And since the redirect is intentionally not permanent, the name throwPermanentRedirect is a small trap for contributors too — a rename or a one-line comment at the call site would save the next reader a puzzled minute. (The cache-it-briefly-so-it-stays-undoable reasoning in the existing comment is sound — this is only about the label.)