{
  "openapi": "3.1.0",
  "info": {
    "title": "Geocast Public API",
    "version": "1.0.0",
    "description": "Read-only API for public property content published on Geocast. Includes property metadata, stories, and Today Feed real-time recommendations. All public endpoints are unauthenticated. This specification describes the published roadmap; specific endpoints become operational on the published timeline.",
    "contact": {
      "name": "Geocast",
      "email": "hello@geocast.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.geocast.ai/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/properties": {
      "get": {
        "summary": "List public properties",
        "operationId": "listProperties",
        "description": "Returns a paginated list of public properties published on Geocast.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "Filter by ISO 3166-1 alpha-2 country code",
            "required": false,
            "schema": { "type": "string", "example": "us" }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by property category",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["hospitality", "winery", "brewery", "museum", "city", "retail", "wellness"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of properties",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PropertyList" }
              }
            }
          }
        }
      }
    },
    "/properties/{slug}": {
      "get": {
        "summary": "Get a property",
        "operationId": "getProperty",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "sunriver-resort" }
          }
        ],
        "responses": {
          "200": {
            "description": "Property detail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Property" }
              }
            }
          },
          "404": { "description": "Property not found" }
        }
      }
    },
    "/properties/{slug}/stories": {
      "get": {
        "summary": "List stories for a property",
        "operationId": "listPropertyStories",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "guide",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "example": "camp-abbot" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of stories",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StoryList" }
              }
            }
          }
        }
      }
    },
    "/properties/{slug}/today-feed": {
      "get": {
        "summary": "Get current Today Feed for a property",
        "operationId": "getTodayFeed",
        "description": "Returns the property's current Today Feed with phase-aware recommendations and storm overrides if active.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Today Feed payload",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TodayFeed" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PropertyList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PropertySummary" }
          },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "PropertySummary": {
        "type": "object",
        "required": ["slug", "name", "country", "url"],
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "country": { "type": "string", "example": "us" },
          "category": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "Property": {
        "type": "object",
        "required": ["slug", "name", "country", "url", "address"],
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "country": { "type": "string" },
          "category": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "address": {
            "type": "object",
            "properties": {
              "streetAddress": { "type": "string" },
              "addressLocality": { "type": "string" },
              "addressRegion": { "type": "string" },
              "postalCode": { "type": "string" },
              "addressCountry": { "type": "string" }
            }
          },
          "geo": {
            "type": "object",
            "properties": {
              "latitude": { "type": "number" },
              "longitude": { "type": "number" }
            }
          },
          "guides": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": { "type": "string" },
                "name": { "type": "string" },
                "storyCount": { "type": "integer" }
              }
            }
          }
        }
      },
      "StoryList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/StorySummary" }
          }
        }
      },
      "StorySummary": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "guideSlug": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "duration": { "type": "string", "example": "3:00" },
          "sources": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "TodayFeed": {
        "type": "object",
        "properties": {
          "phase": {
            "type": "string",
            "enum": ["morning", "midday", "afternoon", "evening", "late", "storm-override"]
          },
          "freshness": { "type": "string", "format": "date-time" },
          "here": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/FeedItem" }
          },
          "nearby": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/FeedItem" }
          }
        }
      },
      "FeedItem": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "description": { "type": "string" },
          "venue": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "validUntil": { "type": "string", "format": "date-time" },
          "sources": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "perPage": { "type": "integer" },
          "total": { "type": "integer" }
        }
      }
    }
  }
}