openapi: 3.0.0
info:
  title: Ambition Innovation Creativity API
  version: 2.0.0
  description: |
    API surface for Ambition Innovation Creativity (AIC): Where Art Meets Intelligence.

    We design and ship:
    - **AI Search Development**: Advanced semantic search systems with neural embeddings with embedded widgets, OAuth integrations, and branded conversational interfaces for enterprise platforms.
    - **Mobile & Backend Ecosystems**: Native iOS/Android apps on AWS for luxury hospitality: data sync from SMS Host (Springer-Miller), SevenRooms, TrackMyShuttle, and Selfbook into secure APIs powering guest apps and staff dashboards.
    - **Cloud-Native Architecture**: Scalable cloud infrastructures on Google Cloud Platform and AWS with serverless functions, managed databases, and containerized workloads.
    - **AI Integration Services**: Semantic search with embeddings, conversational AI chatbots, and agentic AI workflows for websites and enterprise systems.
    - **Hospitality Integration**: Connect luxury hospitality systems with Springer-Miller (SMS Host) and TrackMyShuttle for seamless guest experiences.

    This specification exposes AI-discoverable endpoints plus machine-callable actions for assistants and agents.
  contact:
    name: Ambition Innovation Creativity
    email: contact@ambitioninnovationcreativity.com
    url: https://ambitioninnovationcreativity.com
servers:
  - url: https://ambitioninnovationcreativity.com
    description: Production server
  - url: http://localhost:3000
    description: Local development server
tags:
  - name: Pages
    description: Website pages rendered as HTML
  - name: AI Discovery
    description: Structured metadata for AI agents and copilots
  - name: Content
    description: Blog articles, feeds, and machine-readable dispatches
  - name: SEO
    description: Crawlable files for classic search engines and AI crawlers
paths:
  "/":
    get:
      tags:
        - Pages
      summary: Get homepage
      operationId: getHomepage
      description: Returns the main landing page with services, expertise, and contact information.
      responses:
        '200':
          description: Successful response
          content:
            text/html:
              schema:
                type: string
                description: HTML homepage with company information and services.
  /labs:
    get:
      tags:
        - Pages
      summary: Get AIC Labs page
      operationId: getLabsPage
      description: Returns the innovation laboratory page showcasing agentic systems and AI Search SDK experiments.
      responses:
        '200':
          description: Successful response
          content:
            text/html:
              schema:
                type: string
                description: HTML page detailing AIC Labs focus areas and current experiments.
  /blog:
    get:
      tags:
        - Pages
      summary: Get blog index
      operationId: getBlogIndex
      description: Returns the AIC Blog overview with the newest dispatches and topic filters.
      responses:
        '200':
          description: Successful response
          content:
            text/html:
              schema:
                type: string
                description: Blog index with article summaries and navigation.
  /blog/{slug}:
    get:
      tags:
        - Pages
      summary: Get blog dispatch
      operationId: getBlogPostPage
      description: Returns a single AIC Blog dispatch rendered as HTML.
      parameters:
        - name: slug
          in: path
          required: true
          description: Blog slug (e.g., companion-intelligence)
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            text/html:
              schema:
                type: string
                description: Full HTML article.
  /ai-context.json:
    get:
      tags:
        - AI Discovery
      summary: Get AI context
      operationId: getAiContext
      description: Returns structured context about the site for AI agents and companion AI systems.
      responses:
        '200':
          description: AI context metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIContext'
  /mcp-manifest.json:
    get:
      tags:
        - AI Discovery
      summary: Get MCP manifest
      operationId: getMcpManifest
      description: Returns Model Context Protocol manifest for AI tools and MCP clients.
      responses:
        '200':
          description: MCP manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPManifest'
  /blog/feed.xml:
    get:
      tags:
        - Content
      summary: Get blog RSS feed
      operationId: getBlogRssFeed
      description: Returns the RSS 2.0 feed for the AIC Blog (optimized for AI agents and traditional readers).
      responses:
        '200':
          description: RSS feed
          content:
            application/rss+xml:
              schema:
                type: string
                description: XML feed containing latest blog posts.
  /blog/feed.json:
    get:
      tags:
        - Content
      summary: Get blog JSON feed
      operationId: getBlogJsonFeed
      description: Returns the JSON Feed representation of the latest AIC Blog dispatches.
      responses:
        '200':
          description: JSON feed
          content:
            application/feed+json:
              schema:
                type: object
                description: JSON Feed per https://jsonfeed.org/version/1.1.
            application/json:
              schema:
                type: object
                description: JSON Feed per https://jsonfeed.org/version/1.1.
  /sitemap.xml:
    get:
      tags:
        - SEO
      summary: Get sitemap
      operationId: getSitemap
      description: Returns XML sitemap for search engines and AI crawlers.
      responses:
        '200':
          description: XML sitemap
          content:
            application/xml:
              schema:
                type: string
            text/xml:
              schema:
                type: string
  /robots.txt:
    get:
      tags:
        - SEO
      summary: Get robots.txt
      operationId: getRobotsTxt
      description: Returns crawling rules for search engines and AI bots.
      responses:
        '200':
          description: Robots.txt file
          content:
            text/plain:
              schema:
                type: string
  /api/blog:
    get:
      tags:
        - Content
      summary: List blog posts
      operationId: listBlogPosts
      description: Returns normalized metadata for every published AIC Blog dispatch.
      responses:
        '200':
          description: Blog posts returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogListResponse'
  /api/blog/latest:
    get:
      tags:
        - Content
      summary: Get latest blog post
      operationId: getLatestBlogPost
      description: Returns only the most recent AIC Blog dispatch for lightweight assistant consumption.
      responses:
        '200':
          description: Latest blog post metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogLatestResponse'
components:
  schemas:
    AIContext:
      type: object
      description: Structured metadata for AI agent consumption.
      properties:
        version:
          type: string
        site:
          type: object
        organization:
          type: object
        services:
          type: array
          items:
            type: object
        labs:
          type: object
    MCPManifest:
      type: object
      description: Model Context Protocol manifest.
      properties:
        version:
          type: string
        name:
          type: string
        description:
          type: string
        transport:
          type: object
        tools:
          type: array
          items:
            type: object
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
        issues:
          type: array
          items:
            type: string
    BlogPost:
      type: object
      description: Blog dispatch metadata optimized for assistants.
      properties:
        slug:
          type: string
        title:
          type: string
        excerpt:
          type: string
        theme:
          type: string
        coverImage:
          type: string
          description: Image path or URL for the cover image
        coverAlt:
          type: string
          description: Alt text for the cover image
        ogImage:
          type: string
          description: Optional Open Graph image path or URL
        publishedAt:
          type: string
          format: date
        updatedAt:
          type: string
          format: date
        topics:
          type: array
          items:
            type: string
        tone:
          type: string
        audioMood:
          type: string
        ctaLabel:
          type: string
        ctaHref:
          type: string
        aiSummary:
          type: string
        author:
          type: string
        authorLink:
          type: string
          format: uri
        authorXHandle:
          type: string
          description: Optional author X/Twitter handle (e.g., @handle)
    BlogListResponse:
      type: object
      properties:
        updatedAt:
          type: string
          nullable: true
        count:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/BlogPost'
    BlogLatestResponse:
      type: object
      properties:
        item:
          oneOf:
            - $ref: '#/components/schemas/BlogPost'
            - type: 'null'
    SearchResponse:
      type: object
      description: Semantic search results with deep linking metadata.
      properties:
        schema:
          type: string
          description: API schema version for versioned datasets
          example: v1
        query:
          type: string
          description: The processed search query
          example: AI Search development
        count:
          type: integer
          description: Number of results found
          example: 5
        results:
          type: array
          description: Array of search results ranked by relevance
          items:
            $ref: '#/components/schemas/SearchResult'
    SearchResult:
      type: object
      description: Individual search result with deep linking support.
      properties:
        id:
          type: string
          description: Unique identifier for the content
          example: service-ai-search-optimization
        type:
          type: string
          description: Content type
          enum:
            - service
            - labs-focus
            - labs-experiment
            - blog
            - page
          example: service
        itemType:
          type: string
          description: Entity type for AI classification (same as type, used for entity recognition)
          enum:
            - service
            - labs-focus
            - labs-experiment
            - blog
            - page
          example: service
        category:
          type: string
          description: Category derived from type and section (e.g., 'services', 'focus-areas')
          example: services
        title:
          type: string
          description: Title of the content
          example: AI Search Development
        summary:
          type: string
          description: Short summary or excerpt (first 200 chars if no excerpt available)
          example: We design and develop advanced semantic search systems with neural embeddings. From embedded widgets and OAuth integrations to complete conversational interfaces...
        content:
          type: string
          description: Full content or excerpt
        url:
          type: string
          description: Absolute page URL
          example: https://ambitioninnovationcreativity.com/
        deepLink:
          type: string
          description: Complete deep link URL with section anchor for direct navigation
          example: https://ambitioninnovationcreativity.com/#services
        sectionId:
          type: string
          description: Section ID for deep linking (combine with url for full path like /#services)
          example: services
        excerpt:
          type: string
          description: Short excerpt of the content
        keywords:
          type: array
          description: Combined keywords from technologies, topics, and type for better AI indexing
          items:
            type: string
          example:
            - AI Search SDK
            - Neural Embeddings
            - React
            - OAuth
            - service
        topics:
          type: array
          description: Related topics
          items:
            type: string
        technologies:
          type: array
          description: Related technologies
          items:
            type: string
          example:
            - AI Search SDK
            - Neural Embeddings
            - React
        similarity:
          type: number
          format: float
          description: Match score between 0.0 and 1.0 (>0.6 is highly relevant)
          minimum: 0.0
          maximum: 1.0
          example: 0.71
    SearchErrorResponse:
      type: object
      description: Search endpoint error response with usage examples.
      properties:
        error:
          type: string
          example: Missing query parameter
        usage:
          type: string
          example: Use ?q=your+search+query
        examples:
          type: array
          items:
            type: string
          example:
            - /api/search?q=semantic+search
            - /api/search?q=agentic+AI
            - /api/search?q=cloud+architecture