# 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



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 [#choose-an-interface]

| Interface | Use it for                                                  | Entry point                                    |
| --------- | ----------------------------------------------------------- | ---------------------------------------------- |
| Browser   | Reading and exploring the published pages                   | `https://nicholasadamou.com`                   |
| JSON API  | Structured content in scripts and applications              | `/api/v1` routes                               |
| Markdown  | Reading a page as text or supplying context to an assistant | `Accept: text/markdown` or `/api/markdown/...` |
| MCP       | Exposing site content as tools in a compatible client       | `/mcp`                                         |
| Discovery | Finding available content and protocol descriptions         | `/llms.txt`, `/openapi.json`, `/server.json`   |

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](/docs/api/routes) for integration-specific endpoint behavior.

## Read structured notes [#read-structured-notes]

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

```bash title="List published notes"
curl --fail --silent \
  https://nicholasadamou.com/api/v1/notes
```

```bash title="Read a note"
curl --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 [#request-markdown]

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

```bash title="Read About as Markdown"
curl --fail --silent \
  -H 'Accept: text/markdown' \
  https://nicholasadamou.com/about
```

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

```bash title="Use an explicit Markdown endpoint"
curl --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 [#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.

```bash title="Export a documentation guide"
curl --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 [#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.

```mermaid
"flowchart LR\n    Client[Script or assistant] --> Choice{Required format}\n    Choice -->|Structured data| JSON[Versioned JSON API]\n    Choice -->|Readable page| Markdown[Markdown representation]\n    Choice -->|Tool protocol| MCP[MCP endpoint]\n    JSON --> Content[Published content]\n    Markdown --> Content\n    MCP --> Content"
```

## Client behavior [#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.

- [API route reference](/docs/api/routes): Public and integration endpoints, including view tracking and dashboard routes.
- [Content authoring](/docs/features/mdx-content): How note metadata, filenames and headings become published content.
- [Developer setup](/docs/getting-started/installation): Run the site and optional integrations locally.