{
  "openapi": "3.1.0",
  "info": {
    "title": "iammatthias.com content API",
    "version": "1.0.0",
    "summary": "Read-only access to a personal site's published content.",
    "description": "Public, unauthenticated, read-only endpoints over the published content of iammatthias.com. There is nothing to buy and no account to create; rate limits are Cloudflare's defaults. Every document is also available as markdown by appending .md to its URL, and the same content is exposed as MCP tools at /mcp.",
    "contact": {
      "name": "Matthias Jordan",
      "email": "hey@iammatthias.com",
      "url": "https://iammatthias.com/contact"
    },
    "license": {
      "name": "All rights reserved",
      "url": "https://iammatthias.com/privacy"
    }
  },
  "servers": [
    {
      "url": "https://iammatthias.com",
      "description": "Production (current version)"
    },
    {
      "url": "https://iammatthias.com/api/v1",
      "description": "Version-pinned aliases of the query endpoints. Same behaviour as the unversioned paths; pin here if you need a surface guaranteed not to change shape."
    }
  ],
  "x-api-version": "1",
  "x-deprecation-policy": {
    "summary": "Breaking changes land at a new version path; the previous version keeps working for at least 180 days.",
    "signals": [
      "Responses from a deprecated version carry RFC 9745 Deprecation and RFC 8594 Sunset headers.",
      "Every response carries an API-Version header naming the version that served it.",
      "Removals are announced at https://iammatthias.com/developers before they ship."
    ],
    "minimumNoticeDays": 180
  },
  "paths": {
    "/api/search-corpus.json": {
      "get": {
        "operationId": "getSearchCorpus",
        "summary": "Full searchable corpus",
        "description": "Every searchable item on the site (documents and feed posts) as compact text, each carrying its Farfield content hash (cid). Intended for building your own index; the site's own search embeds this locally in the browser.",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Pin the API version. Omit to use the current version; the response always names the version that served it."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/search-vectors.json": {
      "get": {
        "operationId": "getSearchVectors",
        "summary": "Prebuilt embedding vectors",
        "description": "Precomputed embedding vectors for the corpus, keyed by cid, with the model name and dimension count. Built at deploy time with the ternlight model.",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Pin the API version. Omit to use the current version; the response always names the version that served it."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/content.json": {
      "get": {
        "operationId": "listContent",
        "summary": "List published documents",
        "description": "Every published document as structured JSON: title, section, tags, dates, content hash, canonical URL, and markdown URL. Filterable by section and tag.",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "name": "section",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Restrict to one publication slug (art, posts, recipes, melange, open-source)."
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Restrict to documents carrying this tag."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum number of items to return (default 100)."
          },
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Pin the API version. Omit to use the current version; the response always names the version that served it."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/search.json": {
      "get": {
        "operationId": "searchContent",
        "summary": "Keyword search across the site",
        "description": "Ranked keyword search over titles, excerpts, tags, and body text of every published document and feed post. Returns canonical and markdown URLs per hit.",
        "tags": [
          "content"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search terms."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum number of hits (default 10, max 50)."
          },
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Pin the API version. Omit to use the current version; the response always names the version that served it."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem document with an added resolution hint.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "code": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "resolution": {
            "type": "string",
            "description": "How to fix the request and retry."
          }
        },
        "required": [
          "status",
          "code",
          "detail"
        ]
      }
    }
  },
  "externalDocs": {
    "description": "Developer notes",
    "url": "https://iammatthias.com/developers"
  }
}