Public content and agent access

Use the public interfaces to read portfolio content without driving the visual site. The JSON API, Markdown representations, and MCP server serve different clients while drawing on the same underlying notes and project data.

Choose an interface

These public interfaces are separate from dashboard and delivery endpoints. Do not use a dashboard credential in examples intended for public readers. See the API routes for integration-specific endpoint behavior.

Read structured notes

The notes collection returns the published note list and its count. The detail route uses the note filename's slug.

Copycurl --fail --silent \
  https://nicholasadamou.com/api/v1/notes

Copycurl --fail --silent \
  https://nicholasadamou.com/api/v1/notes/what-happens-when-you-type-google-com

The API also exposes project listings and search. Use the live OpenAPI document at /openapi.json to confirm the supported parameters and response schemas before building a client. Versioned JSON routes use the shared API response and error helpers rather than independent error shapes for each handler.

Request Markdown

For a supported portfolio page, send an explicit Accept header:

Copycurl --fail --silent \
  -H 'Accept: text/markdown' \
  https://nicholasadamou.com/about

An explicit export endpoint is useful when a client cannot control request headers:

Copycurl --fail --silent \
  https://nicholasadamou.com/api/markdown/about

The response declares its Markdown content type. Routes that negotiate HTML and Markdown vary their response by Accept so caches can distinguish the two formats. A missing page should remain a real missing page rather than returning a success status with unrelated content.

Documentation exports

The docs application provides the same readable format through its own zone. Append .md to a documentation URL or request Markdown with the Accept header.

Copycurl --fail --silent \
  https://nicholasadamou.com/docs/using-the-site/layouts-and-scenes.md

Guide cards become ordinary linked lists in Markdown. Diagrams become fenced Mermaid source. This preserves the meaning and destinations of interactive content without requiring the assistant to interpret a screenshot.

MCP discovery

The MCP endpoint is available at /mcp. A compatible client can discover the server and expose tools for searching the site, listing notes, and reading a note. The developer resources page describes the connection and the available client workflows. Use /server.json and the published protocol metadata when configuring a client; do not substitute a private dashboard API for the public MCP endpoint.

Client behavior

Check HTTP status before interpreting a response body. Preserve the content type when storing or forwarding an export. Avoid retrying a missing slug indefinitely; refresh the collection or discovery index to find the current URL. Treat external integration availability separately from public static content: a failed music, chat, or dashboard integration does not imply the notes collection is unavailable.