openapi.yaml

openapi: 3.0.3
info:
  title: Reddit AI Curator API
  description: |
    AI-powered Reddit search and curation platform.
    
    ## Features
    - **Multi-Query Tournament**: Run multiple query variants and select the best performers
    - **Smart Cascade**: Adaptive search with fallback logic for high recall
    - **AI Scoring**: LLM-powered relevance scoring with rule-based fallback
    - **Tag Learning**: Extract semantic tags from high-scoring posts
    
    ## Authentication
    Currently, the API is open. Future versions will require JWT authentication.
    
    ## Rate Limiting
    - 60 requests per minute (configurable)
    - Responses include rate limit headers
  version: 2.0.0
  contact:
    name: API Support
    url: https://github.com/yourusername/reddit-ai-curator

servers:
  - url: http://localhost:5000/api/v2
    description: Development server
  - url: https://api.reddit-ai-curator.com/v2
    description: Production server

tags:
  - name: Search
    description: AI-powered Reddit search operations
  - name: LLM
    description: Large Language Model operations
  - name: Subreddits
    description: Subreddit management
  - name: Queries
    description: Saved query management
  - name: Tags
    description: Tagged results for AI learning
  - name: Blacklist
    description: Blacklist management

paths:
  /health:
    get:
      tags:
        - Health
      summary: Health check
      description: Check if the API and its dependencies are healthy
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Service is degraded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /search:
    post:
      tags:
        - Search
      summary: Execute AI-powered search
      description: |
        Creates a search session, generates query variants using LLM,
        executes cascade search, and returns scored results.
      operationId: executeSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            example:
              description: "Sexual assault while sleeping"
              target_posts: 100
              provider: mistral
              subreddits:
                - sexualassault
                - TwoXChromosomes
              deep_scan: true
              sort: relevance
              time_filter: month
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /search/sessions:
    get:
      tags:
        - Search
      summary: List search sessions
      description: Retrieve a paginated list of recent search sessions
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: List of search sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSessions'

  /search/sessions/{session_id}:
    get:
      tags:
        - Search
      summary: Get search session details
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionDetail'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /llm/generate:
    post:
      tags:
        - LLM
      summary: Generate query variants
      description: Generate Boolean search query variants using LLM
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMGenerateRequest'
      responses:
        '200':
          description: Generated query variants
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMGenerateResponse'
        '400':
          description: Invalid request or provider not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /llm/score:
    post:
      tags:
        - LLM
      summary: Score a post
      description: Score a Reddit post for relevance to criteria using LLM
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMScoreRequest'
      responses:
        '200':
          description: Scoring result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMScoreResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /subreddits:
    get:
      tags:
        - Subreddits
      summary: List subreddits
      description: Get all active subreddits configured for searches
      responses:
        '200':
          description: List of subreddits
          content:
            application/json:
              schema:
                type: object
                properties:
                  subreddits:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subreddit'
                  total:
                    type: integer

    post:
      tags:
        - Subreddits
      summary: Add subreddit
      description: Add a new subreddit to the search configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubredditCreate'
      responses:
        '201':
          description: Subreddit added
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  id:
                    type: integer
                  name:
                    type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /queries:
    get:
      tags:
        - Queries
      summary: List saved queries
      description: Get a paginated list of saved search queries
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of saved queries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedQueries'

    post:
      tags:
        - Queries
      summary: Save a query
      description: Save a new search query configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedQueryCreate'
      responses:
        '201':
          description: Query saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  id:
                    type: integer
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /tags:
    get:
      tags:
        - Tags
      summary: List tagged results
      description: Get tagged results for AI learning, optionally filtered by minimum score
      parameters:
        - name: min_score
          in: query
          schema:
            type: number
            default: 0
      responses:
        '200':
          description: List of tagged results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'

    post:
      tags:
        - Tags
      summary: Add tagged result
      description: Add a new tagged result for AI learning
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaggedResultCreate'
      responses:
        '201':
          description: Result tagged
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  id:
                    type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /blacklist:
    get:
      tags:
        - Blacklist
      summary: List blacklisted posts
      description: Get the list of posts excluded from search results
      responses:
        '200':
          description: List of blacklisted posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlacklistResponse'

    post:
      tags:
        - Blacklist
      summary: Add to blacklist
      description: Add a post to the blacklist to exclude from future searches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlacklistCreate'
      responses:
        '201':
          description: Post blacklisted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  id:
                    type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum: [healthy, degraded, unhealthy]
        version:
          type: string
        database:
          type: string
          enum: [connected, disconnected, unknown]
        cache:
          type: string
          enum: [connected, disconnected, unknown]
        uptime_seconds:
          type: number
        timestamp:
          type: string
          format: date-time

    SearchRequest:
      type: object
      required:
        - description
      properties:
        description:
          type: string
          minLength: 10
          maxLength: 1000
          description: Natural language search description
        target_posts:
          type: integer
          default: 100
          minimum: 1
          maximum: 500
        provider:
          type: string
          enum: [mistral, gemini]
          default: mistral
        subreddits:
          type: array
          items:
            type: string
          description: Specific subreddits to search
        deep_scan:
          type: boolean
          default: false
        sort:
          type: string
          enum: [relevance, hot, new, top]
          default: relevance
        time_filter:
          type: string
          enum: [hour, day, week, month, year, all]
          default: month

    SearchResponse:
      type: object
      properties:
        session_id:
          type: integer
        query:
          type: string
        query_variants:
          type: array
          items:
            type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/PostResult'
        total_found:
          type: integer
        total_scanned:
          type: integer
        duration_seconds:
          type: number
        status:
          type: string
          enum: [completed, partial, failed]
        error_message:
          type: string

    PostResult:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        content:
          type: string
        url:
          type: string
        score:
          type: number
          minimum: 0
          maximum: 100
        tags:
          type: array
          items:
            type: string
        subreddit:
          type: string
        author:
          type: string
        created_utc:
          type: number
        comments_count:
          type: integer

    LLMGenerateRequest:
      type: object
      required:
        - description
      properties:
        description:
          type: string
          minLength: 10
          maxLength: 1000
        provider:
          type: string
          enum: [mistral, gemini]
          default: mistral
        num_variants:
          type: integer
          default: 4
          minimum: 1
          maximum: 10

    LLMGenerateResponse:
      type: object
      properties:
        description:
          type: string
        variants:
          type: array
          items:
            type: object
            properties:
              query:
                type: string
              strategy:
                type: string
              confidence:
                type: number
        generated_at:
          type: string
          format: date-time

    LLMScoreRequest:
      type: object
      required:
        - post_title
        - criteria
      properties:
        post_title:
          type: string
        post_content:
          type: string
        criteria:
          type: string
          minLength: 10
        provider:
          type: string
          enum: [mistral, gemini]
          default: mistral

    LLMScoreResponse:
      type: object
      properties:
        post_id:
          type: string
        score:
          type: number
        tags:
          type: array
          items:
            type: string
        reasoning:
          type: string
        cached:
          type: boolean
        scored_at:
          type: string
          format: date-time

    SubredditCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100

    Subreddit:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time

    SavedQueryCreate:
      type: object
      required:
        - name
        - groups
      properties:
        name:
          type: string
          maxLength: 200
        groups:
          type: array
          items:
            type: array
            items:
              type: string
          minItems: 1
        criteria:
          type: string
        target_posts:
          type: integer
          default: 100
        deep_scan:
          type: boolean
          default: false
        provider:
          type: string
          enum: [mistral, gemini]
          default: mistral
        subreddits:
          type: array
          items:
            type: string
        sort:
          type: string
        time_filter:
          type: string

    SavedQuery:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        groups:
          type: array
        criteria:
          type: string
        provider:
          type: string
        target_posts:
          type: integer
        deep_scan:
          type: boolean
        subreddits:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        is_active:
          type: boolean

    PaginatedSessions:
      type: object
      properties:
        sessions:
          type: array
          items:
            type: object
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer

    SessionDetail:
      type: object
      properties:
        id:
          type: integer
        query:
          type: string
        variants:
          type: array
        status:
          type: string
        total_results:
          type: integer
        total_found:
          type: integer
        started_at:
          type: string
        completed_at:
          type: string
        duration_seconds:
          type: number

    PaginatedQueries:
      type: object
      properties:
        queries:
          type: array
          items:
            $ref: '#/components/schemas/SavedQuery'
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer

    TaggedResultCreate:
      type: object
      required:
        - id
        - title
        - score
      properties:
        id:
          type: string
        title:
          type: string
          maxLength: 500
        content:
          type: string
          maxLength: 10000
        score:
          type: number
          minimum: 0
          maximum: 100
        original_query:
          type: string
        tags:
          type: array
          items:
            type: string
        effective_terms:
          type: array
          items:
            type: string

    TagListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
        total:
          type: integer
        min_score_filter:
          type: number

    BlacklistCreate:
      type: object
      required:
        - id
        - title
        - url
      properties:
        id:
          type: string
        title:
          type: string
          maxLength: 500
        url:
          type: string
        keywords:
          type: string
        criteria:
          type: string

    BlacklistResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
              url:
                type: string
              timestamp:
                type: number
              created_at:
                type: string
                format: date-time
        total:
          type: integer

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
        code:
          type: string
        timestamp:
          type: string
          format: date-time

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT