openapi: 3.0.3
info:
  title: QuantSearch API
  description: |
    AI-powered search for your website. This API allows you to:
    - Search your indexed content
    - Get AI-generated answers
    - Manage sites and crawl jobs
    - Create search groups for federated search
    - Ingest content programmatically
    
    ## Authentication
    
    API access requires a Pro or Enterprise subscription. Generate API keys in your dashboard.
    
    Include your API key in the `Authorization` header:
    ```
    Authorization: Bearer YOUR_API_KEY
    ```
    
    ## Public Endpoints
    
    Public search and chat endpoints don't require authentication, but:
    - Public access must be enabled for your site/group
    - The request origin must match your allowed domains
    - Rate limits apply per IP address
    
    ## Base URLs
    
    - **SaaS API**: `https://www.quantsearch.ai/api` - Authenticated endpoints
    - **Public Search CDN**: `https://cdn.quantsearch.ai/v1` - Public widget/search
  version: 1.1.0
  contact:
    name: QuantSearch Support
    email: support@quantsearch.ai
    url: https://quantsearch.ai/docs
  license:
    name: Proprietary
    url: https://quantsearch.ai/terms

servers:
  - url: https://www.quantsearch.ai/api
    description: SaaS API (authenticated endpoints)
  - url: https://cdn.quantsearch.ai/v1
    description: Public Search CDN (widget, public search/chat)

tags:
  - name: Public Search
    description: Unauthenticated search endpoints (origin-validated)
  - name: Sites
    description: Manage AI Search sites
  - name: Groups
    description: Search groups for federated search (Pro+)
  - name: Content
    description: Ingest and manage indexed content
  - name: Crawler
    description: Manage crawler jobs

paths:
  # =============================================================================
  # PUBLIC ENDPOINTS (No Auth - Origin Validated)
  # =============================================================================
  
  /public/sites/{siteId}/search:
    get:
      tags: [Public Search]
      summary: Search site content
      description: |
        Search your indexed content. Results are cached by CloudFront for performance.
        
        Public access must be enabled for your site, and the request origin must be allowed.
      operationId: publicSearchGet
      servers:
        - url: https://cdn.quantsearch.ai/v1
      parameters:
        - name: siteId
          in: path
          required: true
          schema:
            type: string
          description: Your site ID
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
          example: how to reset password
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            maximum: 100
          description: Maximum results to return
        - name: minScore
          in: query
          schema:
            type: number
            default: 0.3
          description: Minimum relevance score (0-1)
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
    
    post:
      tags: [Public Search]
      summary: Search site content (POST)
      description: Same as GET but accepts JSON body. Useful for complex queries.
      operationId: publicSearchPost
      servers:
        - url: https://cdn.quantsearch.ai/v1
      parameters:
        - name: siteId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                  description: Search query
                limit:
                  type: integer
                  default: 10
                  maximum: 100
                minScore:
                  type: number
                  default: 0.3
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'

  /public/sites/{siteId}/chat:
    post:
      tags: [Public Search]
      summary: Get AI-generated answer
      description: |
        Ask a question and get an AI-generated answer based on your indexed content.
        
        Optionally include a `sessionId` for conversation continuity.
      operationId: publicChat
      servers:
        - url: https://cdn.quantsearch.ai/v1
      parameters:
        - name: siteId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message:
                  type: string
                  description: User question
                  example: How do I reset my password?
                sessionId:
                  type: string
                  description: Optional session ID for conversation history
      responses:
        '200':
          description: AI-generated answer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'

  /public/groups/{groupId}/search:
    get:
      tags: [Public Search, Groups]
      summary: Federated search across group
      description: |
        Search across all sites in a search group. Returns unified results ranked by relevance.
        
        Requires the group to have public access enabled.
      operationId: publicGroupSearchGet
      servers:
        - url: https://cdn.quantsearch.ai/v1
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
          description: Search group ID
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            maximum: 50
        - name: minScore
          in: query
          schema:
            type: number
            default: 0.3
      responses:
        '200':
          description: Federated search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupSearchResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

    post:
      tags: [Public Search, Groups]
      summary: Federated search across group (POST)
      operationId: publicGroupSearchPost
      servers:
        - url: https://cdn.quantsearch.ai/v1
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                limit:
                  type: integer
                  default: 10
                minScore:
                  type: number
                  default: 0.3
      responses:
        '200':
          description: Federated search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupSearchResponse'

  # =============================================================================
  # SITES (Authenticated)
  # =============================================================================

  /sites:
    get:
      tags: [Sites]
      summary: List sites
      description: Get all AI Search sites for your organization.
      operationId: listSites
      security:
        - BearerAuth: []
      responses:
        '200':
          description: List of sites
          content:
            application/json:
              schema:
                type: object
                properties:
                  sites:
                    type: array
                    items:
                      $ref: '#/components/schemas/Site'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags: [Sites]
      summary: Create site
      description: Create a new AI Search site.
      operationId: createSite
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSiteRequest'
      responses:
        '201':
          description: Site created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /sites/{siteId}:
    get:
      tags: [Sites]
      summary: Get site
      description: Get details of a specific site.
      operationId: getSite
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: Site details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags: [Sites]
      summary: Update site
      description: Update site configuration.
      operationId: updateSite
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSiteRequest'
      responses:
        '200':
          description: Site updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'

    delete:
      tags: [Sites]
      summary: Delete site
      description: Delete a site and all its indexed content.
      operationId: deleteSite
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/SiteId'
      responses:
        '204':
          description: Site deleted

  /sites/{siteId}/crawl:
    post:
      tags: [Sites, Crawler]
      summary: Start crawl
      description: Start a new crawl job for the site.
      operationId: startCrawl
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/SiteId'
      responses:
        '201':
          description: Crawl started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlJob'
        '409':
          description: Crawl already in progress

  /sites/{siteId}/purge:
    delete:
      tags: [Sites, Content]
      summary: Purge site index
      description: Delete all indexed content for a site.
      operationId: purgeSite
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: Index purged
          content:
            application/json:
              schema:
                type: object
                properties:
                  deletedPages:
                    type: integer
                  message:
                    type: string

  /sites/{siteId}/pages:
    get:
      tags: [Sites, Content]
      summary: List indexed pages
      description: List pages indexed for this site with pagination.
      operationId: listPages
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/SiteId'
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 200
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor (URL of last item)
        - name: search
          in: query
          schema:
            type: string
          description: Filter by title or URL
      responses:
        '200':
          description: List of indexed pages
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/IndexedPage'
                  nextCursor:
                    type: string
                  hasMore:
                    type: boolean

    post:
      tags: [Content]
      summary: Ingest content
      description: |
        Ingest content directly without crawling. Useful for:
        - CMS integrations
        - Dynamic content
        - Bulk imports
        
        Content is processed with AI to extract metadata and generate embeddings.
      operationId: ingestPages
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pages]
              properties:
                pages:
                  type: array
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/PageContent'
      responses:
        '200':
          description: Content ingested
          content:
            application/json:
              schema:
                type: object
                properties:
                  processed:
                    type: integer
                  skipped:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                        status:
                          type: string
                          enum: [success, skipped, error]
                        error:
                          type: string

    delete:
      tags: [Content]
      summary: Delete pages
      description: Delete specific pages from the index by URL or pattern.
      operationId: deletePages
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                urls:
                  type: array
                  items:
                    type: string
                  description: Exact URLs to delete
                patterns:
                  type: array
                  items:
                    type: string
                  description: URL patterns with wildcards (*)
      responses:
        '200':
          description: Pages deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deletedPages:
                    type: integer
                  deletedChunks:
                    type: integer

  # =============================================================================
  # SEARCH GROUPS (Pro+ Feature)
  # =============================================================================

  /groups:
    get:
      tags: [Groups]
      summary: List search groups
      description: List all search groups for your organization.
      operationId: listGroups
      security:
        - BearerAuth: []
      responses:
        '200':
          description: List of groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchGroup'

    post:
      tags: [Groups]
      summary: Create search group
      description: |
        Create a new search group for federated search across multiple sites.
        Requires Pro or Enterprise subscription.
      operationId: createGroup
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '201':
          description: Group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchGroup'
        '402':
          description: Pro subscription required

  /groups/{groupId}:
    get:
      tags: [Groups]
      summary: Get search group
      operationId: getGroup
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GroupId'
      responses:
        '200':
          description: Group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchGroup'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags: [Groups]
      summary: Update search group
      operationId: updateGroup
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequest'
      responses:
        '200':
          description: Group updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchGroup'

    delete:
      tags: [Groups]
      summary: Delete search group
      operationId: deleteGroup
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GroupId'
      responses:
        '204':
          description: Group deleted

  # =============================================================================
  # JOBS
  # =============================================================================

  /jobs/{jobId}:
    get:
      tags: [Crawler]
      summary: Get crawl job status
      operationId: getJob
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlJob'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags: [Crawler]
      summary: Cancel crawl job
      operationId: cancelJob
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlJob'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key from your dashboard

  parameters:
    SiteId:
      name: siteId
      in: path
      required: true
      schema:
        type: string
      description: Site ID
    
    GroupId:
      name: groupId
      in: path
      required: true
      schema:
        type: string
      description: Search group ID

  schemas:
    SearchResponse:
      type: object
      properties:
        query:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        totalResults:
          type: integer
        timingMs:
          type: integer

    SearchResult:
      type: object
      properties:
        url:
          type: string
        title:
          type: string
        snippet:
          type: string
        score:
          type: number
        metadata:
          type: object
          properties:
            summary:
              type: string
            tags:
              type: array
              items:
                type: string
            publishedAt:
              type: string
              format: date
              description: Content publication date (if detected)
            crawledAt:
              type: string
              format: date
              description: When content was last indexed

    GroupSearchResponse:
      type: object
      properties:
        query:
          type: string
        groupId:
          type: string
        results:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/SearchResult'
              - type: object
                properties:
                  siteId:
                    type: string
                  siteName:
                    type: string
        totalResults:
          type: integer
        timingMs:
          type: integer

    ChatResponse:
      type: object
      properties:
        response:
          type: string
        sources:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              title:
                type: string
              relevance:
                type: number
        sessionId:
          type: string
        tokensUsed:
          type: integer

    Site:
      type: object
      properties:
        siteId:
          type: string
        name:
          type: string
        baseUrl:
          type: string
        domain:
          type: string
          description: Domain for URL prefixing in search results (useful for multi-site)
        status:
          type: string
          enum: [pending, crawling, ready, error]
        pageCount:
          type: integer
        lastCrawledAt:
          type: integer
        createdAt:
          type: integer
        publicAccess:
          $ref: '#/components/schemas/PublicAccess'
        rateLimits:
          $ref: '#/components/schemas/RateLimits'
        metadataSchema:
          type: array
          description: Custom metadata fields for filtering/faceting.
          items:
            $ref: '#/components/schemas/MetadataField'
        tagBoosts:
          type: array
          description: Per-tag score multipliers applied at query time. No reindex needed.
          items:
            $ref: '#/components/schemas/TagBoost'
        urlBoosts:
          type: array
          description: Per-URL-prefix score multipliers applied at query time. No reindex needed.
          items:
            $ref: '#/components/schemas/UrlBoost'

    CreateSiteRequest:
      type: object
      required: [name, baseUrl]
      properties:
        name:
          type: string
        baseUrl:
          type: string
        domain:
          type: string
          description: Optional domain for URL prefixing
        crawlerConfig:
          $ref: '#/components/schemas/CrawlerConfig'

    UpdateSiteRequest:
      type: object
      properties:
        name:
          type: string
        domain:
          type: string
        publicAccess:
          $ref: '#/components/schemas/PublicAccess'
        rateLimits:
          $ref: '#/components/schemas/RateLimits'
        crawlerConfig:
          $ref: '#/components/schemas/CrawlerConfig'
        metadataSchema:
          type: array
          items:
            $ref: '#/components/schemas/MetadataField'
        tagBoosts:
          type: array
          items:
            $ref: '#/components/schemas/TagBoost'
        urlBoosts:
          type: array
          items:
            $ref: '#/components/schemas/UrlBoost'

    MetadataField:
      type: object
      required: [name, type]
      properties:
        name:
          type: string
          description: Field name (alphanumeric + underscore).
        type:
          type: string
          enum: [string, number, date]
        label:
          type: string
          description: Human-readable display label for facets.
        facet:
          type: boolean
          description: When true, the field is exposed via the /facets endpoint.

    TagBoost:
      type: object
      required: [tag, boost]
      description: |
        Multiply each result's score by `boost` if the result has `tag` in its
        `metadata.tags` array. Values >1 boost, <1 deboost. Applied at query
        time before URL deduplication; affects both the rendered results list
        and the AI summary's source selection. Negative or zero boosts are
        silently skipped.
      properties:
        tag:
          type: string
          example: type:product
        boost:
          type: number
          format: float
          minimum: 0
          example: 2.0

    UrlBoost:
      type: object
      required: [urlPrefix, boost]
      description: |
        Multiply each result's score by `boost` when the result URL's path
        starts with `urlPrefix`. Same semantics as TagBoost otherwise.
      properties:
        urlPrefix:
          type: string
          description: Path prefix (e.g. `/products`) or full URL prefix.
          example: /products
        boost:
          type: number
          format: float
          minimum: 0
          example: 2.0

    SearchGroup:
      type: object
      properties:
        groupId:
          type: string
        name:
          type: string
        description:
          type: string
        siteIds:
          type: array
          items:
            type: string
          description: Sites included in this group
        publicAccess:
          $ref: '#/components/schemas/PublicAccess'
        rateLimits:
          $ref: '#/components/schemas/RateLimits'
        createdAt:
          type: integer

    CreateGroupRequest:
      type: object
      required: [name, siteIds]
      properties:
        name:
          type: string
        description:
          type: string
        siteIds:
          type: array
          items:
            type: string
          minItems: 1
        publicAccess:
          $ref: '#/components/schemas/PublicAccess'

    UpdateGroupRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        siteIds:
          type: array
          items:
            type: string
        publicAccess:
          $ref: '#/components/schemas/PublicAccess'
        rateLimits:
          $ref: '#/components/schemas/RateLimits'

    IndexedPage:
      type: object
      properties:
        url:
          type: string
        title:
          type: string
        summary:
          type: string
        tags:
          type: array
          items:
            type: string
        publishedAt:
          type: string
          format: date
        crawledAt:
          type: string
          format: date

    PublicAccess:
      type: object
      properties:
        enabled:
          type: boolean
        searchEnabled:
          type: boolean
        chatEnabled:
          type: boolean
        allowedDomains:
          type: array
          items:
            type: string
          description: Domains allowed to embed (use * for all)
        anonymousSessions:
          type: boolean
        sessionTTLMinutes:
          type: integer

    RateLimits:
      type: object
      properties:
        searchPerMinute:
          type: integer
        chatPerMinute:
          type: integer
        perIpPerMinute:
          type: integer

    CrawlerConfig:
      type: object
      properties:
        maxPages:
          type: integer
        maxDepth:
          type: integer
        respectRobotsTxt:
          type: boolean
        excludePatterns:
          type: array
          items:
            type: string
        includePatterns:
          type: array
          items:
            type: string
        javascriptEnabled:
          type: boolean
        delayMs:
          type: integer
          description: Delay between requests in milliseconds

    PageContent:
      type: object
      required: [url, content]
      properties:
        url:
          type: string
        title:
          type: string
        content:
          type: string
          description: HTML or plain text content
        contentType:
          type: string
          enum: [html, text]
          default: html
        summary:
          type: string
        tags:
          type: array
          items:
            type: string
        preProcessed:
          type: boolean
          default: false
          description: Skip AI processing if content is already cleaned

    CrawlJob:
      type: object
      properties:
        jobId:
          type: string
        siteId:
          type: string
        status:
          type: string
          enum: [pending, running, completed, failed, cancelled]
        pagesDiscovered:
          type: integer
        pagesCrawled:
          type: integer
        pagesProcessed:
          type: integer
        pagesErrored:
          type: integer
        startedAt:
          type: integer
        completedAt:
          type: integer
        taskId:
          type: string
          description: ECS task ID (for cancellation)

    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    Forbidden:
      description: Forbidden - origin not allowed or feature disabled
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              retryAfter:
                type: integer