API Documentation

Quick Links

• OpenAPI Specification — Machine-readable API description
• Service Metadata — Collection counts and capabilities
• Service Status — Health and status information
• MCP Endpoint — Public read-only MCP Streamable HTTP endpoint
• MCP Server Card — MCP discovery document for clients
• MCP Discovery Alias — Secondary MCP discovery document
• Cap’n Web Endpoint — Experimental read-only HTTP batch RPC endpoint
• API Catalog — RFC 9727 discovery (application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727")
• Problem Types — RFC 9457 error type registry
• Agent Skills Index — Public skill discovery endpoint

Collections

Standards Compliance

This API implements the following standards:

Content Negotiation

All collection endpoints support multiple response formats via the Accept header:

• application/json — JSON (default)
• text/csv — CSV export
• application/geo+json — GeoJSON (/api/places.json and /api/photos.json)

curl -H "Accept: text/csv" https://irvinebroque.com/api/movies.json

curl -H "Accept: application/geo+json" https://irvinebroque.com/api/places.json

curl -H "Accept: text/markdown" https://irvinebroque.com/movies

Cap’n Web (Experimental Read-Only)

The Cap’n Web endpoint lives at /api/rpc and supports HTTP batch requests only. It is a TypeScript-friendly adapter over the same query behavior as REST; REST and OpenAPI remain the stable, language-neutral public contract.

The endpoint is unauthenticated, read-only, and intentionally does not expose WebSocket sessions, callbacks, subscriptions, or generated protocol schemas.

Available methods:

• query(collection, params) — Query any public list surface with the same filters, sorting, pagination, and response envelope as REST
• getMeta() — Return service metadata, interface discovery, and collection counts
• getStatus() — Return the current public service health snapshot

TypeScript HTTP batch example:

import { newHttpBatchRpcSession } from 'capnweb';

interface PublicApi {
  query(
    collection: string,
    params?: Record<string, string | number | boolean | null | undefined>
  ): Promise<{
    data: Array<Record<string, unknown>>;
    meta: { totalCount: number; pageSize: number; timestamp: string };
    links: Record<string, string>;
  }>;
}

using api = newHttpBatchRpcSession<PublicApi>(
  'https://irvinebroque.com/api/rpc'
);

const movies = await api.query('movies', {
  limit: 10,
  sort: 'releaseDate:desc'
});

MCP (Public Read-Only)

The public MCP endpoint lives at /mcp and uses Model Context Protocol (2025-11-25) over Streamable HTTP. Discovery is available at /.well-known/mcp/server-card.json and/.well-known/mcp.json.

This MCP server is unauthenticated and read-only. It is separate from private interface-gateway capture workflows and complements the REST API rather than replacing it.

Available tools:

• taste.recommend — Deterministic recommendations from Brendan’s corpus with evidence and canonical citations
• taste.find — Known-item lookup across titles, names, URLs, and collection fields
• taste.get — Canonical detail rehydration for bounded item IDs
• places.plan — Approximate place planning with explicit straight-line-distance limits
• taste.render_recommendations — Taste Explorer list for model-selected canonical IDs
• places.render_map — Taste Explorer real map for model-selected canonical place IDs

Migration notes:

• Code Mode and its Worker Loader binding are removed; task-shaped read tools are the stable public contract.
• Data tools stand alone in non-App clients. Render tools receive bounded canonical IDs and rehydrate trusted records server-side.
• Owner writes are absent from /mcp and appear only on OAuth-protected /owner/mcp with taste:write.

Initialize request example:

curl -X POST https://irvinebroque.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {
        "extensions": {
          "io.modelcontextprotocol/ui": {
            "mimeTypes": ["text/html;profile=mcp-app"]
          }
        }
      },
      "clientInfo": { "name": "curl", "version": "1.0.0" }
    }
  }'

List tools example:

curl -X POST https://irvinebroque.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

OpenCode remote MCP config example:

{
  "mcp": {
    "brendan-website": {
      "type": "remote",
      "url": "https://irvinebroque.com/mcp"
    }
  }
}

Claude Code command:

claude mcp add --transport http brendan-website https://irvinebroque.com/mcp

In ChatGPT developer mode, connect `https://irvinebroque.com/mcp` for anonymous read tools and Taste Explorer, or `https://irvinebroque.com/owner/mcp` for the owner OAuth lane.

Pagination

Collection endpoints support cursor-based pagination:

• limit — Items per page (default: 50, max: 100)
• cursor — Pagination cursor from links.next
• sort — Sort field and direction (e.g., year:desc)
• facets — Optional facet metadata in meta.facets when set to 1

Pagination links are provided in both the response body and Link header (RFC 8288).

Endpoints also publish a Link-Template header (RFC 9652) with query templates for pagination and capability-specific filters.

Conditional Requests

Use If-None-Match or If-Modified-Since headers to receive 304 Not Modified responses:

curl -H "If-None-Match: "abc123"" https://irvinebroque.com/api/movies.json

Deprecation and Sunset

Endpoints scheduled for lifecycle changes include Deprecation and optional Sunset headers, with a rel="deprecation" link to migration guidance.

No endpoints are currently scheduled for deprecation.

CORS

Cross-origin requests are enabled for all origins. The following headers are exposed:

• Link — Pagination and discovery links
• Link-Template — RFC 9652 parameterized collection query template
• ETag — Entity tag for conditional requests
• Last-Modified — Last modification timestamp
• X-Total-Count — Total items in collection

Errors

Errors are returned as RFC 9457 Problem Details with stable type URIs:

{
  "type": "https://irvinebroque.com/problems/invalid-cursor",
  "title": "Bad Request",
  "status": 400,
  "detail": "The cursor parameter must be a valid opaque cursor value returned by this API."
}

See /problems/ for the full registry.