openapi: 3.0.3
info:
  title: Fluent Agent API
  description: |
    Semantic search API for Fluent Commerce documentation.

    This API enables AI coding agents to search through documentation for configurable
    assets (rules, components, utilities, etc.) using vector embeddings and semantic search.

    ## Features
    - Semantic search using Amazon Titan Text Embeddings V2
    - Module/version filtering for targeted results
    - Optional reranking with Cohere Rerank 3.5
    - Sub-second query latency

    ## Pipeline
    The search uses a 5-stage pipeline:
    1. **Vectorize**: Generate embedding from query
    2. **Retrieve**: Find top 100 matches in S3 Vectors
    3. **Hydrate**: Fetch full documents from S3
    4. **Rerank**: Improve result order with cross-encoder (optional)
    5. **Return**: Send top N results to client
  version: 1.0.0
  contact:
    name: Fluent Commerce
    url: https://fluentcommerce.com
  license:
    name: Proprietary

servers:
  - url: http://localhost:3000
    description: Local development server
  - url: https://agent-api.fluentcommerce.com
    description: Production server

tags:
  - name: search
    description: Semantic search operations
  - name: health
    description: Health check and monitoring
  - name: feedback
    description: Content quality feedback

paths:
  /api/v1/search:
    get:
      summary: Health check
      description: Simple health check endpoint that returns OK status
      operationId: healthCheck
      tags:
        - search
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
              example:
                status: ok

    post:
      summary: Semantic search
      description: |
        Search documentation using semantic vector search.

        Supports filtering by module and version, and returns ranked results
        with relevance scores.
      operationId: search
      tags:
        - search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              basic:
                summary: Basic search
                value:
                  query: How do I implement a custom fulfillment rule?
              withFilters:
                summary: Search with module filter
                value:
                  query: split shipment configuration
                  modules:
                    - name: module-order
                      version: 2.x
                  first: 5
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                results:
                  - id: doc_12345
                    title: Split Shipment Rule
                    module: module-order
                    version: 2.x
                    content: "# Split Shipment Rule\n\nThis rule handles..."
                    relevance_score: 0.98
                  - id: doc_12346
                    title: Custom Fulfillment Logic
                    module: module-order
                    version: 2.x
                    content: "# Custom Fulfillment\n\nImplement custom..."
                    relevance_score: 0.95
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error: Validation failed
                details:
                  - path: query
                    message: Query cannot be empty
        '404':
          description: No documents found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Not found
                message: No documents match the search criteria
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Service unavailable
                message: Unable to connect to AWS services

  /api/v1/report:
    post:
      summary: Report incorrect content
      description: |
        Report incorrect or misleading content in a vector search result or agent skill.

        Reports are logged to CloudWatch for internal review. The endpoint acknowledges
        immediately — no action is guaranteed synchronously.
      operationId: reportFeedback
      tags:
        - feedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
            examples:
              vectorSearch:
                summary: Report a bad vector search result
                value:
                  documentId: doc_12345
                  type: vector_search
                  issue: Content describes an outdated API that was changed in v2.1
                  module: module-order
                  version: 2.x
                  query: How do I implement a custom fulfillment rule?
              agentSkill:
                summary: Report a bad agent skill
                value:
                  documentId: skill_abc
                  type: agent_skill
                  issue: Example code uses a deprecated method signature
      responses:
        '202':
          description: Report received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportAck'
              example:
                status: received
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error: Validation failed
                details:
                  - path: issue
                    message: Issue description is required
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Internal server error
                message: An unexpected error occurred

  /api/v1/health:
    get:
      summary: Comprehensive health check
      description: |
        Detailed health check that verifies all service dependencies:
        - AWS credentials
        - S3 Vectors bucket access
        - S3 document bucket access
        - Bedrock model access

        Returns health status with latency for each check.
      operationId: comprehensiveHealthCheck
      tags:
        - health
      responses:
        '200':
          description: Service health status (healthy or degraded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
              examples:
                healthy:
                  summary: All services healthy
                  value:
                    status: healthy
                    timestamp: '2026-03-12T10:30:00Z'
                    checks:
                      aws_credentials:
                        status: ok
                        latency: 45
                      s3_vectors:
                        status: ok
                        latency: 123
                      s3_documents:
                        status: ok
                        latency: 89
                      bedrock:
                        status: ok
                        latency: 234
                degraded:
                  summary: Some services failing
                  value:
                    status: degraded
                    timestamp: '2026-03-12T10:30:00Z'
                    checks:
                      aws_credentials:
                        status: ok
                        latency: 45
                      s3_vectors:
                        status: error
                        message: Vector bucket 'fluent-vector-embeddings' not found
                        latency: 123
                      s3_documents:
                        status: ok
                        latency: 89
                      bedrock:
                        status: ok
                        latency: 234
        '503':
          description: Service is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
              example:
                status: unhealthy
                timestamp: '2026-03-12T10:30:00Z'
                checks:
                  aws_credentials:
                    status: error
                    message: Failed to get AWS credentials
                    latency: 45
                  s3_vectors:
                    status: error
                    message: Failed to access S3 Vectors
                    latency: 0
                  s3_documents:
                    status: error
                    message: Failed to access S3 document bucket
                    latency: 0
                  bedrock:
                    status: error
                    message: Failed to access Bedrock
                    latency: 0

components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 20000
          description: Search query text (1-20,000 characters)
          example: How do I implement a custom fulfillment rule?
        modules:
          type: array
          description: Optional filter to search within specific modules
          items:
            $ref: '#/components/schemas/ModuleFilter'
          example:
            - name: module-order
              version: 2.x
        first:
          type: integer
          minimum: 1
          maximum: 10
          default: 10
          description: Number of results to return (1-10)
          example: 5

    ModuleFilter:
      type: object
      required:
        - name
        - version
      properties:
        name:
          type: string
          minLength: 1
          description: Module name
          example: module-order
        version:
          type: string
          minLength: 1
          description: Module version
          example: 2.x

    SearchResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'

    SearchResult:
      type: object
      required:
        - id
        - title
        - module
        - version
        - content
        - relevance_score
      properties:
        id:
          type: string
          description: Unique document identifier
          example: doc_12345
        title:
          type: string
          description: Document title
          example: Split Shipment Rule
        module:
          type: string
          description: Module name
          example: module-order
        version:
          type: string
          description: Module version
          example: 2.x
        content:
          type: string
          description: Full document content in Markdown format
          example: "# Split Shipment Rule\n\nThis rule handles split shipments..."
        relevance_score:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Relevance score (0-1, higher is more relevant)
          example: 0.98

    ReportRequest:
      type: object
      required:
        - documentId
        - type
        - issue
      properties:
        documentId:
          type: string
          minLength: 1
          description: ID of the document or skill being reported
          example: doc_12345
        type:
          type: string
          enum: [vector_search, agent_skill]
          description: Surface where the incorrect content was encountered
          example: vector_search
        issue:
          type: string
          minLength: 1
          maxLength: 1000
          description: Description of the problem (1-1,000 characters)
          example: Content describes an outdated API
        module:
          type: string
          description: Module context (optional)
          example: module-order
        version:
          type: string
          description: Version context (optional)
          example: 2.x
        query:
          type: string
          description: The search query that surfaced this result (optional)
          example: How do I implement a custom fulfillment rule?

    ReportAck:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum: [received]
          example: received

    ValidationError:
      type: object
      required:
        - error
        - details
      properties:
        error:
          type: string
          example: Validation failed
        details:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: JSON path to the invalid field
                example: query
              message:
                type: string
                description: Validation error message
                example: Query cannot be empty

    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error type
          example: Service unavailable
        message:
          type: string
          description: Detailed error message
          example: Unable to connect to AWS services

    HealthStatus:
      type: object
      required:
        - status
        - timestamp
        - checks
      properties:
        status:
          type: string
          enum: [healthy, degraded, unhealthy]
          description: |
            Overall health status:
            - healthy: All checks passed
            - degraded: Some checks failed
            - unhealthy: All checks failed
          example: healthy
        timestamp:
          type: string
          format: date-time
          description: Timestamp of health check
          example: '2026-03-12T10:30:00Z'
        checks:
          type: object
          required:
            - aws_credentials
            - s3_vectors
            - s3_documents
            - bedrock
          properties:
            aws_credentials:
              $ref: '#/components/schemas/HealthCheck'
            s3_vectors:
              $ref: '#/components/schemas/HealthCheck'
            s3_documents:
              $ref: '#/components/schemas/HealthCheck'
            bedrock:
              $ref: '#/components/schemas/HealthCheck'

    HealthCheck:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum: [ok, error]
          description: Check status
          example: ok
        message:
          type: string
          description: Error message (only present if status is error)
          example: Failed to access S3 Vectors
        latency:
          type: integer
          description: Check latency in milliseconds
          example: 123