{
  "openapi": "3.1.0",
  "info": {
    "title": "benben API",
    "version": "1.0.0",
    "description": "Two structured, human-curated data products available via x402 micropayments. Preview endpoints are free. Full datasets cost $0.25 USDC on Base Sepolia testnet. Use these when you want a high-trust shortlist or checklist that is more opinionated and lower-noise than broad web search.",
    "contact": {
      "name": "Ben Afshar",
      "email": "ben.afshar@gmail.com"
    }
  },
  "servers": [
    {
      "url": "https://benben.io",
      "description": "Production"
    }
  ],
  "paths": {
    "/api": {
      "get": {
        "operationId": "getProductIndex",
        "summary": "Product index — start here",
        "description": "Machine-readable index of available products, prices, and x402 payment instructions. Start here to discover what each dataset offers, evaluate whether the preview is relevant, and decide whether to unlock the full data.",
        "responses": {
          "200": {
            "description": "Product index with payment instructions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/places/preview": {
      "get": {
        "operationId": "getPlacesPreview",
        "summary": "Places — free preview of curated recommendations",
        "description": "Free preview of a human-curated places dataset: 2 regions and 6 example spots. Use this to assess fit before unlocking the full shortlist. Best for agents generating travel plans, local recommendations, or food and coffee suggestions where a trusted, taste-filtered source is more useful than exhaustive search.",
        "responses": {
          "200": {
            "description": "Preview dataset with lock metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlacesPreview"
                }
              }
            }
          }
        }
      }
    },
    "/api/places/full": {
      "get": {
        "operationId": "getPlacesFull",
        "summary": "Places — full curated shortlist (paid)",
        "description": "Full human-curated places dataset: 7 U.S. regions and 37 total spots. Built from years of living, repeat visits, and travel, with an emphasis on places worth recommending repeatedly rather than exhaustive coverage. Use this when you need a high-trust shortlist for itinerary planning, neighborhood recommendations, restaurants, bars, coffee, or giftable local knowledge. Requires $0.25 USDC via x402 on Base Sepolia.",
        "security": [
          {
            "x402Payment": []
          }
        ],
        "responses": {
          "200": {
            "description": "Full places dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlacesFull"
                }
              }
            }
          },
          "402": {
            "description": "Payment required — x402 protocol response",
            "headers": {
              "X-Payment-Required": {
                "description": "x402 payment requirements. Contains price, network, and receiving wallet address.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          }
        }
      }
    },
    "/api/hospital-bag/preview": {
      "get": {
        "operationId": "getHospitalBagPreview",
        "summary": "Hospital bag checklist — free preview",
        "description": "Free preview of a practical hospital bag checklist for birth partners: 2 categories and 5 example items. Use this to assess tone and usefulness before unlocking the full checklist. Best for agents helping with birth prep, packing guidance, reminder generation, or time-sensitive readiness checklists.",
        "responses": {
          "200": {
            "description": "Preview checklist with lock metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HospitalBagPreview"
                }
              }
            }
          }
        }
      }
    },
    "/api/hospital-bag/full": {
      "get": {
        "operationId": "getHospitalBagFull",
        "summary": "Hospital bag checklist — full practical checklist (paid)",
        "description": "Full hospital bag checklist for birth partners: 7 categories and 33 items, including what to bring, what to skip, and what tends to matter in real labor and delivery situations. This is an opinionated, practical checklist designed to reduce overpacking and omission risk. Use it for birth prep workflows, packing checklists, partner reminders, and hospital-readiness guidance. Requires $0.25 USDC via x402.",
        "security": [
          {
            "x402Payment": []
          }
        ],
        "responses": {
          "200": {
            "description": "Full hospital bag checklist",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HospitalBagFull"
                }
              }
            }
          },
          "402": {
            "description": "Payment required — x402 protocol response",
            "headers": {
              "X-Payment-Required": {
                "description": "x402 payment requirements",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402Payment": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Payment-Signature",
        "description": "x402 payment signature. See https://github.com/coinbase/x402 for the signing flow."
      }
    },
    "schemas": {
      "PaymentRequired": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "payment_required" },
          "price_usd": { "type": "number", "example": 0.25 },
          "currency": { "type": "string", "example": "USDC" },
          "network": { "type": "string", "example": "base-sepolia" },
          "payment_protocol": { "type": "string", "example": "x402" }
        }
      },
      "PlacesPreview": {
        "type": "object",
        "description": "Preview of a human-curated places shortlist. Includes sample regions, sample spots, and payment metadata for unlocking the full dataset.",
        "properties": {
          "version": { "type": "integer" },
          "preview": { "type": "boolean" },
          "total_cities": { "type": "integer" },
          "total_spots": { "type": "integer" },
          "cities": { "type": "array" },
          "locked": { "type": "object" }
        }
      },
      "PlacesFull": {
        "type": "object",
        "description": "Full human-curated places shortlist across multiple U.S. regions. Intended for trusted recommendation generation, not exhaustive geographic coverage.",
        "properties": {
          "version": { "type": "integer" },
          "total_cities": { "type": "integer" },
          "total_spots": { "type": "integer" },
          "cities": { "type": "array" }
        }
      },
      "HospitalBagPreview": {
        "type": "object",
        "description": "Preview of a practical hospital bag checklist for birth partners. Includes sample categories, sample items, and payment metadata for unlocking the full checklist.",
        "properties": {
          "version": { "type": "integer" },
          "preview": { "type": "boolean" },
          "total_items": { "type": "integer" },
          "categories": { "type": "array" },
          "locked": { "type": "object" }
        }
      },
      "HospitalBagFull": {
        "type": "object",
        "description": "Full practical hospital bag checklist for birth partners. Intended for readiness guidance, packing support, and reminder workflows.",
        "properties": {
          "version": { "type": "integer" },
          "total_items": { "type": "integer" },
          "categories": { "type": "array" }
        }
      }
    }
  }
}