{
  "openapi": "3.1.0",
  "info": {
    "title": "Head of Engineering Public Content API",
    "version": "1.0.0",
    "description": "API for published posts, journal entries, static pages, and a lightweight D1-backed counter endpoint. Use .json for structured responses and .md for raw markdown documents."
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://headofengineering.com"
    }
  ],
  "externalDocs": {
    "description": "Human-readable API reference",
    "url": "https://headofengineering.com/api"
  },
  "tags": [
    {
      "name": "Posts",
      "description": "Published blog posts"
    },
    {
      "name": "Journal",
      "description": "Journal entries"
    },
    {
      "name": "Pages",
      "description": "Static pages"
    },
    {
      "name": "Counters",
      "description": "Simple key-based counters backed by D1"
    }
  ],
  "paths": {
    "/api/posts.json": {
      "get": {
        "tags": [
          "Posts"
        ],
        "operationId": "listPosts",
        "summary": "List posts",
        "description": "Returns all published posts sorted by publication date descending.",
        "responses": {
          "200": {
            "description": "Posts list response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/posts.md": {
      "get": {
        "tags": [
          "Posts"
        ],
        "operationId": "listPostsMarkdown",
        "summary": "List posts as markdown",
        "description": "Returns a markdown index of published posts.",
        "responses": {
          "200": {
            "description": "Posts list as markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/posts/{slug}.json": {
      "get": {
        "tags": [
          "Posts"
        ],
        "operationId": "getPost",
        "summary": "Retrieve a post",
        "description": "Returns one published post including its full markdown body.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The post slug, for example \"the-startup-minded-engineers\".",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Posts detail response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostResponse"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/posts/{slug}.md": {
      "get": {
        "tags": [
          "Posts"
        ],
        "operationId": "getPostMarkdown",
        "summary": "Retrieve post markdown",
        "description": "Returns the raw markdown document including frontmatter.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The post slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Posts document as raw markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/journal.json": {
      "get": {
        "tags": [
          "Journal"
        ],
        "operationId": "listJournalEntries",
        "summary": "List journal entries",
        "description": "Returns all published journal entries sorted by publication date descending.",
        "responses": {
          "200": {
            "description": "Journal list response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JournalListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/journal.md": {
      "get": {
        "tags": [
          "Journal"
        ],
        "operationId": "listJournalEntriesMarkdown",
        "summary": "List journal entries as markdown",
        "description": "Returns a markdown index of journal entries.",
        "responses": {
          "200": {
            "description": "Journal list as markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/journal/{slug}.json": {
      "get": {
        "tags": [
          "Journal"
        ],
        "operationId": "getJournalEntry",
        "summary": "Retrieve a journal entry",
        "description": "Returns one journal entry including its full markdown body.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The journal slug, for example \"2025-11-16\".",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Journal detail response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JournalEntryResponse"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/journal/{slug}.md": {
      "get": {
        "tags": [
          "Journal"
        ],
        "operationId": "getJournalEntryMarkdown",
        "summary": "Retrieve journal markdown",
        "description": "Returns the raw markdown document including frontmatter.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The journal slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Journal document as raw markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/pages.json": {
      "get": {
        "tags": [
          "Pages"
        ],
        "operationId": "listPages",
        "summary": "List pages",
        "description": "Returns all public static pages.",
        "responses": {
          "200": {
            "description": "Pages list response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/pages.md": {
      "get": {
        "tags": [
          "Pages"
        ],
        "operationId": "listPagesMarkdown",
        "summary": "List pages as markdown",
        "description": "Returns a markdown index of public static pages.",
        "responses": {
          "200": {
            "description": "Pages list as markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/pages/{slug}.json": {
      "get": {
        "tags": [
          "Pages"
        ],
        "operationId": "getPage",
        "summary": "Retrieve a page",
        "description": "Returns one static page including its full markdown body.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The page slug, for example \"about\".",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pages detail response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageResponse"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/pages/{slug}.md": {
      "get": {
        "tags": [
          "Pages"
        ],
        "operationId": "getPageMarkdown",
        "summary": "Retrieve page markdown",
        "description": "Returns the raw markdown document including frontmatter.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The page slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pages document as raw markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    },
    "/api/counter.json": {
      "get": {
        "tags": [
          "Counters"
        ],
        "operationId": "getCounter",
        "summary": "Read or increment a counter",
        "description": "Returns a key-based counter from D1. By default this endpoint increments the counter on each request. Pass increment=0 for read-only access.",
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "required": false,
            "description": "Counter key. Defaults to \"retro9500:visitors\".",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9:_-]{1,64}$"
            }
          },
          {
            "name": "increment",
            "in": "query",
            "required": false,
            "description": "Set to 0 to read without incrementing.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Counter response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CounterResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid counter key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Counter query failure or missing migration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "D1 binding is not configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContentSummary": {
        "type": "object",
        "description": "Compact metadata for a published content item.",
        "required": [
          "slug",
          "title",
          "url",
          "excerpt",
          "readingTime",
          "wordCount"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "pubDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "excerpt": {
            "type": "string"
          },
          "readingTime": {
            "type": "integer",
            "minimum": 1
          },
          "wordCount": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "PostSummary": {
        "type": "object",
        "description": "Compact metadata for a published post.",
        "required": [
          "slug",
          "title",
          "url",
          "excerpt",
          "readingTime",
          "wordCount"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "pubDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "excerpt": {
            "type": "string"
          },
          "readingTime": {
            "type": "integer",
            "minimum": 1
          },
          "wordCount": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "JournalEntrySummary": {
        "type": "object",
        "description": "Compact metadata for a journal entry.",
        "required": [
          "slug",
          "title",
          "url",
          "excerpt",
          "readingTime",
          "wordCount"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "pubDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "excerpt": {
            "type": "string"
          },
          "readingTime": {
            "type": "integer",
            "minimum": 1
          },
          "wordCount": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "PageSummary": {
        "type": "object",
        "description": "Compact metadata for a static page.",
        "required": [
          "slug",
          "title",
          "url",
          "excerpt",
          "readingTime",
          "wordCount"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "pubDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "excerpt": {
            "type": "string"
          },
          "readingTime": {
            "type": "integer",
            "minimum": 1
          },
          "wordCount": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "PostResponse": {
        "type": "object",
        "description": "A published post with full markdown content.",
        "required": [
          "object",
          "slug",
          "title",
          "url",
          "excerpt",
          "readingTime",
          "wordCount",
          "content"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "post"
            ]
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "pubDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "excerpt": {
            "type": "string"
          },
          "readingTime": {
            "type": "integer",
            "minimum": 1
          },
          "wordCount": {
            "type": "integer",
            "minimum": 0
          },
          "content": {
            "type": "string"
          }
        }
      },
      "JournalEntryResponse": {
        "type": "object",
        "description": "A journal entry with full markdown content.",
        "required": [
          "object",
          "slug",
          "title",
          "url",
          "excerpt",
          "readingTime",
          "wordCount",
          "content"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "journal_entry"
            ]
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "pubDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "excerpt": {
            "type": "string"
          },
          "readingTime": {
            "type": "integer",
            "minimum": 1
          },
          "wordCount": {
            "type": "integer",
            "minimum": 0
          },
          "content": {
            "type": "string"
          }
        }
      },
      "PageResponse": {
        "type": "object",
        "description": "A static page with full markdown content.",
        "required": [
          "object",
          "slug",
          "title",
          "url",
          "excerpt",
          "readingTime",
          "wordCount",
          "content"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "page"
            ]
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "pubDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "excerpt": {
            "type": "string"
          },
          "readingTime": {
            "type": "integer",
            "minimum": 1
          },
          "wordCount": {
            "type": "integer",
            "minimum": 0
          },
          "content": {
            "type": "string"
          }
        }
      },
      "PostListResponse": {
        "type": "object",
        "description": "A list of published posts.",
        "required": [
          "object",
          "data",
          "count"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PostSummary"
            }
          },
          "count": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "JournalListResponse": {
        "type": "object",
        "description": "A list of journal entries.",
        "required": [
          "object",
          "data",
          "count"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JournalEntrySummary"
            }
          },
          "count": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "PageListResponse": {
        "type": "object",
        "description": "A list of static pages.",
        "required": [
          "object",
          "data",
          "count"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PageSummary"
            }
          },
          "count": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "CounterResponse": {
        "type": "object",
        "required": [
          "object",
          "key",
          "count",
          "formatted",
          "incremented"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "counter"
            ]
          },
          "key": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "formatted": {
            "type": "string",
            "pattern": "^\\d{6,}$"
          },
          "incremented": {
            "type": "boolean"
          }
        }
      },
      "MarkdownDocument": {
        "type": "string",
        "description": "Raw markdown content, including YAML frontmatter where applicable."
      },
      "APIErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "type",
              "code",
              "message"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "not_found",
                  "invalid_request",
                  "internal_error"
                ]
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "param": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}