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.
  /search:
    get:
      tags:
        - Pages
      summary: Get search page
      operationId: getSearchPage
      description: Returns the AI-powered semantic search interface for discovering AIC services, labs experiments, and blog content.
      responses:
        '200':
          description: Successful response
          content:
            text/html:
              schema:
                type: string
                description: HTML search page with semantic search interface powered by neural embeddings.
  /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/search:
    get:
      tags:
        - AI Discovery
      summary: Semantic search across AIC content
      operationId: searchContent
      description: |
        Performs semantic search across all AIC services, labs experiments, blog posts, and content using neural embeddings.
        Returns ranked results with deep linking metadata to navigate users to specific page sections.

        This endpoint supports natural language queries and uses vector similarity matching (not keyword-based).
        Results include section anchors for precise navigation (e.g., /#services, /labs#focus-areas).
      parameters:
        - name: q
          in: query
          required: true
          description: Natural language search query
          schema:
            type: string
          examples:
            ai-search:
              summary: Search for AI search expertise
              value: AI Search development
            agentic:
              summary: Search for agentic AI
              value: agentic AI systems
            cloud:
              summary: Search for cloud architecture
              value: AWS serverless architecture
      responses:
        '200':
          description: Search results with deep linking metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Missing or invalid query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchErrorResponse'
        '500':
          description: Search service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - AI Discovery
      summary: Semantic search with JSON body
      operationId: searchContentPost
      description: |
        Alternative POST endpoint for semantic search. Accepts JSON body with query field.
        Returns the same results as GET endpoint. Use GET for simplicity or POST for complex queries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: Natural language search query
                  example: AI Search SDK
      responses:
        '200':
          description: Search results with deep linking metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Missing or invalid query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Search service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /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