{
  "openapi": "3.1.0",
  "info": {
    "title": "ProbleMattic Solutions Public Content API",
    "version": "1.0.0",
    "description": "Read-only static JSON API for the ProbleMattic musings archive. Essays expose a first graph (introductory paragraph) as `opening` on list/detail records and as the first paragraph in full-text fields (plainText, feeds, Markdown). Also exposes MCP tools and Markdown content negotiation."
  },
  "servers": [
    {
      "url": "https://www.problemattic1.com"
    }
  ],
  "paths": {
    "/api/v1/index.json": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "API root",
        "operationId": "getApiIndex",
        "responses": {
          "200": {
            "description": "API index document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/essays.json": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "List published essays (metadata only)",
        "operationId": "listEssays",
        "responses": {
          "200": {
            "description": "Essay list with first graph opening per item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/EssayListItem"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/essays/{slug}.json": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Get full essay by slug",
        "operationId": "getEssay",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full essay record with opening and plainText",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EssayDetail"
                }
              }
            }
          },
          "404": {
            "description": "Essay not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/collections.json": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "List collections",
        "operationId": "listCollections",
        "responses": {
          "200": {
            "description": "Collection list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Collection"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tags.json": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "List tags",
        "operationId": "listTags",
        "responses": {
          "200": {
            "description": "Tag list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Tag"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search-index.json": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Full-text search index",
        "operationId": "getSearchIndex",
        "responses": {
          "200": {
            "description": "Search index with plainText starting with first graph per essay",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SearchIndexEntry"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/feed.json": {
      "get": {
        "tags": [
          "Feeds"
        ],
        "summary": "JSON Feed of published essays",
        "operationId": "getJsonFeed",
        "responses": {
          "200": {
            "description": "JSON Feed 1.1 document with full-text items",
            "content": {
              "application/feed+json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonFeed"
                }
              }
            }
          }
        }
      }
    },
    "/feed.xml": {
      "get": {
        "tags": [
          "Feeds"
        ],
        "summary": "Atom feed of published essays",
        "operationId": "getAtomFeed",
        "responses": {
          "200": {
            "description": "Atom feed with full HTML content per entry",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/musings/{slug}": {
      "get": {
        "tags": [
          "Pages"
        ],
        "summary": "Essay page with Markdown content negotiation",
        "description": "Returns HTML by default. Send Accept: text/markdown to receive the Markdown mirror.",
        "operationId": "getEssayPage",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "schema": {
              "type": "string",
              "example": "text/markdown"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Essay page representation",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                },
                "description": "HTML essay page with first graph blockquote"
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                },
                "description": "Markdown mirror; prose after front matter starts with the first graph."
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "tags": [
          "MCP"
        ],
        "summary": "MCP Streamable HTTP endpoint",
        "operationId": "mcpEndpoint",
        "description": "Read-only Model Context Protocol server for musings archive tools.",
        "responses": {
          "200": {
            "description": "MCP JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Opening": {
        "type": "string",
        "description": "First graph — the introductory paragraph of the essay (styled opening on the page). Same text as the opening blockquote on /musings/{slug}."
      },
      "ApiIndex": {
        "type": "object",
        "required": [
          "version",
          "name",
          "description",
          "baseUrl",
          "endpoints",
          "feeds",
          "discovery"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "baseUrl": {
            "type": "string",
            "format": "uri"
          },
          "endpoints": {
            "type": "object",
            "properties": {
              "essays": {
                "type": "string",
                "format": "uri"
              },
              "collections": {
                "type": "string",
                "format": "uri"
              },
              "tags": {
                "type": "string",
                "format": "uri"
              },
              "searchIndex": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "feeds": {
            "type": "object",
            "properties": {
              "atom": {
                "type": "string",
                "format": "uri"
              },
              "json": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "discovery": {
            "type": "object",
            "properties": {
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "apiCatalog": {
                "type": "string",
                "format": "uri"
              },
              "llmsTxt": {
                "type": "string",
                "format": "uri"
              },
              "sitemap": {
                "type": "string",
                "format": "uri"
              },
              "contentUsage": {
                "type": "string",
                "format": "uri"
              },
              "mcpServerCard": {
                "type": "string",
                "format": "uri"
              },
              "mcpEndpoint": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "EssayListItem": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "collection",
          "tags",
          "summary",
          "dek",
          "readTime",
          "wordCount",
          "url",
          "markdownUrl",
          "jsonUrl",
          "ogImage",
          "opening"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "shortTitle": {
            "type": [
              "string",
              "null"
            ]
          },
          "collection": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "type": "string"
          },
          "dek": {
            "type": "string"
          },
          "readTime": {
            "type": "string"
          },
          "wordCount": {
            "type": "integer"
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          },
          "jsonUrl": {
            "type": "string",
            "format": "uri"
          },
          "ogImage": {
            "type": "string",
            "format": "uri"
          },
          "opening": {
            "$ref": "#/components/schemas/Opening"
          }
        }
      },
      "EssayDetail": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "collection",
          "tags",
          "summary",
          "dek",
          "readTime",
          "wordCount",
          "url",
          "markdownUrl",
          "jsonUrl",
          "ogImage",
          "opening",
          "body",
          "plainText",
          "seeAlsoSlugs",
          "relatedSlugs",
          "fileCode"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "shortTitle": {
            "type": [
              "string",
              "null"
            ]
          },
          "collection": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "type": "string"
          },
          "dek": {
            "type": "string"
          },
          "readTime": {
            "type": "string"
          },
          "wordCount": {
            "type": "integer"
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          },
          "jsonUrl": {
            "type": "string",
            "format": "uri"
          },
          "ogImage": {
            "type": "string",
            "format": "uri"
          },
          "opening": {
            "$ref": "#/components/schemas/Opening"
          },
          "body": {
            "type": "array",
            "description": "Raw source HTML paragraphs from essay JSON. body[0] is paragraph 2 when firstGraph is set.",
            "items": {
              "type": "string"
            }
          },
          "plainText": {
            "type": "string",
            "description": "Full essay text for search and inference. First graph (paragraph 1), then body[0] (paragraph 2) onward."
          },
          "seeAlsoSlugs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "relatedSlugs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fileCode": {
            "type": "string"
          }
        }
      },
      "Collection": {
        "type": "object",
        "required": [
          "name",
          "slug",
          "description",
          "essayCount",
          "essaySlugs",
          "url",
          "feedUrl",
          "atomFeedUrl"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "essayCount": {
            "type": "integer"
          },
          "essaySlugs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "feedUrl": {
            "type": "string",
            "format": "uri"
          },
          "atomFeedUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Tag": {
        "type": "object",
        "required": [
          "slug",
          "label",
          "essayCount",
          "essaySlugs",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "essayCount": {
            "type": "integer"
          },
          "essaySlugs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "SearchIndexEntry": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "summary",
          "tags",
          "collection",
          "plainText"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "collection": {
            "type": "string"
          },
          "plainText": {
            "type": "string",
            "description": "Full essay plain text for search. First graph (paragraph 1), then body[0] (paragraph 2) onward."
          }
        }
      },
      "JsonFeedAuthor": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "JsonFeedItem": {
        "type": "object",
        "required": [
          "id",
          "url",
          "title",
          "summary"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uri"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "content_html": {
            "type": "string",
            "description": "Full HTML essay content. The first graph appears as the opening paragraph."
          },
          "content_text": {
            "type": "string",
            "description": "Full plain-text essay content. Begins with the first graph as paragraph 1."
          },
          "date_published": {
            "type": "string",
            "format": "date"
          },
          "date_modified": {
            "type": "string",
            "format": "date"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "authors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonFeedAuthor"
            }
          }
        }
      },
      "JsonFeed": {
        "type": "object",
        "required": [
          "version",
          "title",
          "home_page_url",
          "feed_url",
          "items"
        ],
        "properties": {
          "version": {
            "type": "string",
            "const": "https://jsonfeed.org/version/1.1"
          },
          "title": {
            "type": "string"
          },
          "home_page_url": {
            "type": "string",
            "format": "uri"
          },
          "feed_url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "authors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonFeedAuthor"
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonFeedItem"
            }
          }
        }
      },
      "McpJsonRpcResponse": {
        "type": "object",
        "description": "MCP JSON-RPC response envelope.",
        "additionalProperties": true
      },
      "NotFoundError": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}