# Developers

Everything on this portfolio is available to programs as well as people. All of it is public, read-only, and needs no API key.

## Quick start

```bash
curl https://frzxw.me/api/v1/portfolio
```

The whole portfolio as JSON: profile, experience, education, certifications, skills, projects, websites and posts.

## REST API

- `GET /api/v1/portfolio`: the portfolio as JSON. Described by the [OpenAPI document](/openapi.json).
- `GET /api/portfolio`: the same response, kept for older clients. It links to its successor in a `Link` header.
- `GET /openapi.json`: OpenAPI 3.1 description of every endpoint, including the error model.
- `GET /.well-known/api-catalog`: an RFC 9727 API catalog that lists the API and the MCP server.

Responses are cached at the edge and send `Access-Control-Allow-Origin: *`, so they work from a browser.

## Errors

Errors use RFC 9457 problem details with the `application/problem+json` media type. Every error has a stable `code` and a `resolution` hint. An unknown path under /api returns 404 in this format, never an HTML page.

```json
{
  "type": "https://frzxw.me/developers#errors",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No API endpoint at /api/v1/unknown.",
  "resolution": "See https://frzxw.me/openapi.json for every endpoint."
}
```

## Versioning

The API is versioned in the path: /api/v1. A breaking change ships as a new major version (/api/v2) alongside the old one. Before a version is removed, its responses announce it with `Deprecation` and `Sunset` headers (RFC 9745 and RFC 8594) and a link to the successor. Adding fields is not a breaking change, so clients should ignore fields they do not know.

## MCP server

A read-only Model Context Protocol server runs at [/mcp](/mcp) over Streamable HTTP. It is stateless and needs no authentication.

- `get_profile`: who I am, contact links, education and skills.
- `list_experience`: roles, dates, what I did, and the stack.
- `list_projects`: products and websites, with ids for get_page.
- `list_posts`: blog posts.
- `get_page`: any page of the site as Markdown.

Its server card is at [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json).

## Markdown for agents

Every page has a Markdown version. Add `.md` to the path (`/about.md`, `/index.md` for the home page), or request any page with `Accept: text/markdown`. The [llms.txt](/llms.txt) file indexes them all, and [llms-full.txt](/llms-full.txt) has the full text in one file.

## Discovery

- `Link` headers on every page point to the Markdown version, sitemap, llms.txt, API catalog, OpenAPI document, MCP server card and Agent Skills index.
- [Agent Skills index](/.well-known/agent-skills/index.json): a skill that explains how to read this site.
- [ARD manifest](/.well-known/ard.json): Agentic Resource Discovery entries for the MCP server, API and skill.
- WebMCP: in browsers that support it, the page registers `read_page` and `get_portfolio` tools.

## Source

The site is open source at [github.com/frzxw/portfolio](https://github.com/frzxw/portfolio). Next.js, TypeScript, and content in plain JSON and Markdown files edited with Decap CMS.