mfserna.dev document API and OpenAPI guide
This is the reading guide for mfserna.dev, my personal portfolio and browser-based N64 lab. It is not a SaaS product. There are no accounts, API keys, paid plans, write operations, or hidden customer endpoints. The interactive home page needs JavaScript because it boots an emulator, but the work is also published as ordinary HTML, markdown, text, and JSON so a person or an agent can inspect it without running the application.
The three useful starting points are the
plain-text recruiting brief at
/llms.txt, the
OpenAPI document at
/openapi.json, and the
JSON page index at
/api/v1/pages. The recruiting brief gives a short map
of my AI infrastructure, platform, and agent-runtime work, with links to
primary evidence. The OpenAPI file describes the public document
surface. The page index lists each canonical page and its direct
markdown sibling. Use the linked repositories, documentation, writeups,
and measured results when they disagree with a summary.
Authentication
There is no authentication. Every documented operation is a public,
read-only GET; the page index also accepts
HEAD. Do not send a bearer token, session cookie, or API
key. There is nothing to register for and no credential to obtain.
These endpoints expose the same public material linked from the site.
Endpoints and formats
GET /llms.txt returns the short recruiting brief as
text/plain. GET /openapi.json returns this
surface's OpenAPI 3.1 description as JSON.
GET /sitemap.xml returns the canonical public URL list as
XML. GET /api/v1/pages returns a JSON object with a
pages array. Each item contains path,
markdown, kind, url, and
markdownUrl, which is enough to walk the published pages
without scraping navigation.
Published page URLs support HTTP content negotiation. Send
Accept: text/markdown to /,
/about, /contact, /privacy,
/docs, /agentNet,
/projects/<published-slug>, or
/writing/<published-slug> to receive markdown.
Without that preference, the server returns HTML. Negotiated responses
include Vary: Accept. If the request accepts neither HTML
nor markdown, the server returns HTTP 406.
Published content also has direct .md files. For example,
/projects/serna64.md is
the markdown sibling of /projects/serna64, and
/writing/an-introductory-guide-to-harness-engineering.md is
the markdown sibling of its writing page. /agentNet.md,
/about.md, /contact.md,
/privacy.md, and /docs.md work the same way.
The home page's direct markdown file is /homepage.md.
Three convenience aliases are available: /brief and
/recruiting-brief resolve to /llms.txt, while
/sitemap resolves to /sitemap.xml. They do not
introduce separate resources or response models. Large emulator assets
under /roms/ and /n64wasm/, PDFs, images,
fonts, and Vite's hashed assets are ordinary static files and do not
participate in markdown negotiation.
Examples
Ask a published page for markdown:
curl -H 'Accept: text/markdown' https://www.mfserna.dev/projects/serna64Read the machine-friendly page index and inspect its response headers:
curl -i https://www.mfserna.dev/api/v1/pagesDownload the OpenAPI contract:
curl https://www.mfserna.dev/openapi.jsonYou can also use HEAD when you only need metadata from the index:
curl -I https://www.mfserna.dev/api/v1/pagesErrors
API mistakes use application/problem+json and follow the
RFC 9457 problem-details shape. A problem includes type,
title, numeric status, stable
code, human-readable detail, and a practical
hint. For example, /api/v1/pages?limit=10
returns HTTP 400 because the complete index is intentionally small and
does not accept query parameters. A non-GET or
non-HEAD request to that endpoint returns HTTP 405 with an
Allow header. Unknown /api/* routes return
HTTP 404 in the same problem format.
Unknown page paths return a real HTTP 404. A request that prefers
markdown receives a short markdown 404; other visitors receive an HTML
404. A negotiable page returns HTTP 406 when its Accept
header permits neither HTML nor markdown. The OpenAPI contract gives
every documented error a typed problem schema, rather than leaving
clients to infer an object from prose.
Rate-limit convention
The document index has a soft public quota, advertised on successful responses and API problem responses with the standard IETF-style headers:
RateLimit: "fixed";r=1000;t=60
RateLimit-Policy: "fixed";q=1000;w=60
This says the published policy is a fixed window of 1,000 requests per
60 seconds. This is a personal site, so normal personal-site traffic is
not aggressively throttled and clients should not treat the policy as a
service-level promise. If the endpoint ever returns HTTP 429, it will
include Retry-After along with the same rate-limit headers.
Well-behaved crawlers should still cache documents, avoid tight polling
loops, and follow the advertised metadata.
Versioning and deprecation
/api/v1/* is the current version of the JSON document
index. Additive fields may appear within v1, so clients should ignore
fields they do not understand. A breaking response change will use a
new versioned path rather than silently changing the v1 contract. The
HTML, markdown, text, XML, and OpenAPI documents are public site
resources rather than a separately versioned product API.
There are no deprecated endpoints and no sunsets today. If an API route
is retired in the future, I will announce it on /docs,
mark it in /openapi.json, and send
Deprecation and Sunset response headers before
removal. Existing aliases are conveniences, not a substitute for the
canonical URLs listed above.