Roman Slack API

This is the developer portal for the Roman Slack Portfolio API. Everything here is read-only, public, and served over plain HTTPS. No API key, sign-up, or sandbox provisioning is required: the live endpoints are the sandbox.

Quickstart

List Roman Slack's projects as JSON:

curl -s https://romanslack.com/projects.json

Query the portfolio through the MCP server (Streamable HTTP):

npx @modelcontextprotocol/inspector https://romanslack.com/mcp

Fetch the agent-oriented site overview:

curl -s https://romanslack.com/llms.txt

REST / JSON data API

Machine-readable description: /openapi.json (OpenAPI 3.1). All endpoints are HTTP GET and return application/json.

• /projects.json: every project, ordered by prominence (lower id first).
• /project_details.json: rich per-project detail (long description, features, tech stack, tags), keyed by project id.
• /hobbies.json: hobbies as a sized word cloud.

Command-line tool (CLI)

The official romanslack CLI wraps the same read-only endpoints so agents and developers can script against the portfolio without writing HTTP calls. Zero dependencies; no API key.

npx romanslack projects --limit 5
npx romanslack search "reinforcement learning"
npx romanslack project 1 --json
npx romanslack hobbies

Source and install instructions: cli/ on GitHub.

Versioning and deprecation

This is API version 1. Every resource is available both unversioned and under the stable /v1 base path; the two are identical aliases.

• /v1/projects.json mirrors /projects.json.
• Breaking changes ship under a new prefix such as /v2, so an integration pinned to /v1 keeps working.
• A deprecated endpoint responds for at least 6 months and carries the standard Deprecation and Sunset response headers (RFC 8594) pointing at its replacement. Nothing is currently deprecated.

MCP server

A read-only Model Context Protocol server exposes the same portfolio data as callable tools.

• Endpoint: /mcp
• Server card: /mcp/server-card
• Tools: list_projects, search_projects, get_project, list_hobbies.

Authentication

The data API and the MCP server are open by default because everything served is public portfolio data. When bearer auth is enabled, agents authenticate with OAuth 2.1. Details and the agent runbook:

• /auth.md: authentication and agent-auth guide.
• /.well-known/oauth-protected-resource: protected-resource metadata (RFC 9728), live only when auth is enabled.

Error responses

Unknown API paths and failures return a real HTTP 4xx or 5xx status with a typed JSON error object (documented as the Error schema in /openapi.json) so agents can parse and recover:

{
  "error": {
    "code": "not_found",
    "status": 404,
    "message": "No resource exists at /api/unknown.",
    "hint": "This path is not part of the site. Check the OpenAPI spec ...",
    "documentation": "https://romanslack.com/developers",
    "openapi": "https://romanslack.com/openapi.json",
    "sitemap": "https://romanslack.com/sitemap.xml",
    "llms": "https://romanslack.com/llms.txt"
  }
}

Machine-readable files

• /llms.txt: concise site overview for AI models.
• /llms-full.txt: full content export.
• /index.md: markdown twin of the homepage (also served from / via Accept: text/markdown).
• /openapi.json: OpenAPI 3.1 description of the data API.
• /.well-known/api-catalog: RFC 9727 API catalog linkset.
• /.well-known/agent-skills/index.json: discoverable Agent Skills.
• /sitemap.xml and /robots.txt: crawl map and content-usage policy.

Contact

Questions about the API or the portfolio: contact Roman Slack or email romanslack1@gmail.com.