openapi: 3.1.0
info:
  title: Fashion Week Venues public AI API
  version: "1.0.0"
  description: >-
    Read-only endpoints exposing pop-up venue inventory, per-city market facts
    and programmatic guide content from Fashion Week Venues, an experiential
    pop-up shop agency and vetted venue marketplace. No authentication.
    Cite the canonical page URL when quoting any value.
  contact:
    name: Fashion Week Venues
    url: https://fashionweekvenues.com/contact
    email: hello@fashionweekvenues.com
servers:
  - url: https://fashionweekvenues.com
paths:
  /api/public/ai/stats:
    get:
      operationId: getSitewideStats
      summary: Live counts of spaces, cities and use cases.
      responses:
        "200":
          description: Sitewide inventory stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalSpaces: { type: integer }
                  cities:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        count: { type: integer }
                  useCases:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        count: { type: integer }
                  updatedAt: { type: string, format: date-time }
  /api/public/ai/meta/{slug}:
    get:
      operationId: getSpaceMeta
      summary: Structured metadata for one marketplace listing.
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          description: Listing slug as used by https://fashionweekvenues.com/spaces/{slug}
      responses:
        "200":
          description: Space metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  title: { type: string }
                  description: { type: string }
                  city: { type: string }
                  country: { type: string }
                  areaSqm: { type: number }
                  priceLabel: { type: string }
                  coverImage: { type: string, format: uri }
                  gallery:
                    type: array
                    items: { type: string, format: uri }
                  amenities:
                    type: array
                    items: { type: string }
                  categories:
                    type: array
                    items: { type: string }
                  url: { type: string, format: uri }
                  updatedAt: { type: string, format: date-time }
        "404": { description: Unknown listing. }
  /api/public/ai/facts/{city}:
    get:
      operationId: getCityFacts
      summary: Market facts for one hub city.
      parameters:
        - name: city
          in: path
          required: true
          schema: { type: string }
          description: City name, lowercase (paris, new-york, london, milan, tokyo, dubai).
      responses:
        "200":
          description: City facts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  city: { type: string }
                  inventoryCount: { type: integer }
                  avgAreaSqm: { type: number }
                  formats:
                    type: array
                    items: { type: string }
                  permitChip: { type: string }
                  fashionWeekWindow: { type: string }
        "404": { description: Unknown city. }
  /api/public/ai/pages:
    get:
      operationId: listGuides
      summary: Every published programmatic guide with title, language, city and last update.
      responses:
        "200":
          description: Guide index.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pages:
                    type: array
                    items:
                      type: object
                      properties:
                        path: { type: string }
                        title: { type: string }
                        language: { type: string }
                        city: { type: string }
                        updatedAt: { type: string, format: date-time }
  /api/public/ai/page/{locale}/{city}/{slug}:
    get:
      operationId: getGuide
      summary: One programmatic guide as structured JSON, including matched inventory.
      parameters:
        - name: locale
          in: path
          required: true
          schema: { type: string, enum: [en, fr, it] }
        - name: city
          in: path
          required: true
          schema: { type: string }
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Guide bundle (facts, FAQ, checklist, matched spaces).
          content:
            application/json:
              schema:
                type: object
        "404": { description: Unknown guide. }
  /{locale}/{city}/{slug}.md:
    get:
      operationId: getGuideMarkdown
      summary: The same guide as plain markdown, preferred for LLM ingestion.
      parameters:
        - name: locale
          in: path
          required: true
          schema: { type: string, enum: [en, fr, it] }
        - name: city
          in: path
          required: true
          schema: { type: string }
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Markdown document with YAML front matter.
          content:
            text/markdown:
              schema: { type: string }
        "404": { description: Unknown guide. }