meta docs: type-scoped search endpoints and the OpenAPI spec route - #17
Merged
Conversation
metaserve gained three type-scoped searches (/api/v1/works/search, /api/v1/people/search, /api/v1/series/search) sharing the combined search's contract, and /api/v1/openapi.json, the embedded OpenAPI 3.1 description of the whole public surface. Documents the three together (one shared contract, per-kind result shape, the kind filter applied inside the query, and the series-position boost applying to the combined search and works/search only), adds a section for the spec route (static, embedded, outside the loaded-artifact gate so it never 503s, drift-guarded against the mux registrations), and points the intro at the interactive reference on the meta site plus the spec itself.
The API's literal route segments (works/search, works/latest, the typed search endpoints) reserve those two words in the works, people and series id namespaces; validation rejects them and the importers mint a disambiguated slug instead.
KodeStar
force-pushed
the
docs/meta-typed-search-openapi
branch
from
August 7, 2026 18:28
c9d8683 to
734d386
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the metaserve additions from KodeStar/audiosilo-meta#1443 on
docs-developers/meta/api.md.https://meta.audiosilo.app/docs/api) and the machine-readable spec (https://meta.audiosilo.app/api/v1/openapi.json), noting both are the same embedded file./api/v1/openapi.jsonsection: OpenAPI 3.1, embedded viago:embed, registered outside the loaded-artifact gate so it never 503s, CORS-open and gzipped, path set drift-guarded against the mux registrations byTestOpenAPICoversEveryRoute./api/v1/works/search,/api/v1/people/searchand/api/v1/series/searchtogether: the shared contract stated once (q required, limit default 20 clamped[1, 50], same FTS escaping,{"results": [...]}ranked by bm25), the per-endpoint result shape by reference to the combined search's three shapes, the kind filter applied inside the query (so?limit=20returns 20 of that kind), and the series-position boost applying to the combined search andworks/searchonly.Every claim was verified against the PR diff (
internal/serve/serve.goroute table,internal/serve/search.go,internal/serve/openapi.go+openapi.json). No other page indocs-developers/meta/enumerates API routes or links to an API reference, so nothing else went stale.npm run buildpasses (the broken-link/anchor gate).Pairs with KodeStar/audiosilo-meta#1443.
🤖 Generated with Claude Code