{
  "openapi": "3.0.3",
  "info": {
    "title": "benmilne.com API",
    "description": "Public read-only API for benmilne.com content — posts, search, taxonomies, and product metadata.",
    "version": "1.0.0",
    "contact": {
      "name": "Ben Milne",
      "url": "https://preview.benmilne.com"
    }
  },
  "servers": [
    {
      "url": "https://preview.benmilne.com"
    }
  ],
  "paths": {
    "/mcp/v1/posts": {
      "get": {
        "operationId": "listPosts",
        "summary": "List posts",
        "description": "Returns a paginated list of published posts with full agent metadata envelopes.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated post list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedPostsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid pagination input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/mcp/v1/post/{id}": {
      "get": {
        "operationId": "getPostById",
        "summary": "Get a single post",
        "description": "Retrieves one published post by internal numeric ID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Post with full content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostResponse"
                }
              }
            }
          },
          "404": {
            "description": "Post not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/mcp/v1/search": {
      "get": {
        "operationId": "searchPosts",
        "summary": "Search posts",
        "description": "Full-text search over published content using a query string.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching posts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedPostsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/mcp/v1/category/{slug}": {
      "get": {
        "operationId": "listPostsByCategory",
        "summary": "List posts by category",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Category-filtered posts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedPostsResponse"
                }
              }
            }
          },
          "404": {
            "description": "Category not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/mcp/v1/tag/{slug}": {
      "get": {
        "operationId": "listPostsByTag",
        "summary": "List posts by tag",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tag-filtered posts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedPostsResponse"
                }
              }
            }
          },
          "404": {
            "description": "Tag not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/products/the-value-layer": {
      "get": {
        "operationId": "getValueLayerProduct",
        "summary": "Product metadata — The Value Layer PDF",
        "responses": {
          "200": {
            "description": "Structured product + commerce discovery URLs"
          }
        }
      }
    },
    "/x402/v1/settings": {
      "get": {
        "operationId": "getX402Settings",
        "summary": "x402 payment settings for digital goods",
        "responses": {
          "200": {
            "description": "Network, currency, SKUs"
          }
        }
      }
    },
    "/x402/v1/verify": {
      "post": {
        "operationId": "verifyX402Payment",
        "summary": "Verify / acknowledge payment and issue download token",
        "responses": {
          "200": {
            "description": "Fulfillment-ready payload + token"
          },
          "400": {
            "description": "Invalid verification request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing required payment inputs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Service health check",
        "responses": {
          "200": {
            "description": "Service status object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "PostSummary": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "modified": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "slug",
          "title",
          "date",
          "author",
          "url"
        ]
      },
      "PaginatedPostsResponse": {
        "type": "object",
        "properties": {
          "attribution": {
            "type": "string"
          },
          "page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "total_pages": {
            "type": "integer"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PostSummary"
            }
          }
        },
        "required": [
          "attribution",
          "data"
        ]
      },
      "PostResponse": {
        "type": "object",
        "properties": {
          "attribution": {
            "type": "string"
          },
          "data": {
            "type": "object"
          }
        },
        "required": [
          "attribution",
          "data"
        ]
      },
      "StatusResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "service": {
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          },
          "host": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "service",
          "timestamp",
          "host"
        ]
      }
    }
  }
}