openapi.yaml

openapi: 3.0.3
info:
  title: Emailibrium API
  version: 0.1.0
  description: |
    Vector-native email intelligence platform API.

    Emailibrium provides semantic search, email classification, ingestion
    orchestration, and inbox intelligence via a REST + SSE interface backed
    by vector embeddings and HNSW indexing.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    name: Emailibrium Team

servers:
  - url: http://localhost:8080/api/v1
    description: Local development server

tags:
  - name: vectors
    description: Vector search, classification, and store operations
  - name: ingestion
    description: Email ingestion pipeline control and SSE progress streaming
  - name: insights
    description: Inbox intelligence -- subscriptions, recurring senders, reports

paths:
  # ---------------------------------------------------------------------------
  # Vectors
  # ---------------------------------------------------------------------------
  /vectors/search/semantic:
    post:
      tags: [vectors]
      summary: Semantic vector search
      description: |
        Embed the query text and perform a cosine similarity search across
        the vector store. Returns ranked results above the minimum score
        threshold.
      operationId: semanticSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SemanticSearchRequest"
            example:
              query: "quarterly budget report from finance team"
              limit: 20
              collection: "email_text"
              min_score: 0.5
      responses:
        "200":
          description: Search results ranked by cosine similarity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
              example:
                results:
                  - email_id: "abc-123"
                    score: 0.94
                    collection: "email_text"
                    metadata:
                      category: "Finance"
                  - email_id: "def-456"
                    score: 0.87
                    collection: "email_text"
                    metadata:
                      category: "Work"
                total: 2
                latency_ms: 12
        "500":
          description: Internal server error (embedding or store failure)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /vectors/search/similar/{email_id}:
    post:
      tags: [vectors]
      summary: Find similar emails
      description: |
        Look up the vector for the given email_id and perform a nearest-neighbor
        search to find similar emails. The source email is excluded from results.
      operationId: findSimilar
      parameters:
        - name: email_id
          in: path
          required: true
          schema:
            type: string
          description: The email ID whose similar emails to find
          example: "abc-123"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FindSimilarRequest"
            example:
              limit: 10
      responses:
        "200":
          description: Similar emails ranked by cosine similarity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "404":
          description: No vector found for the given email_id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /vectors/classify:
    post:
      tags: [vectors]
      summary: Classify email by category
      description: |
        Generate an embedding for the email content and classify it against
        known category centroids. Uses vector similarity first; falls back to
        LLM classification if confidence is below the configured threshold
        (ADR-004).
      operationId: classifyEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClassifyRequest"
            example:
              email_id: "abc-123"
              subject: "Q4 Budget Review"
              from_addr: "finance@company.com"
              body_text: "Please review the attached Q4 budget spreadsheet."
      responses:
        "200":
          description: Classification result with category and confidence
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClassifyResponse"
              example:
                email_id: "abc-123"
                category: "Finance"
                confidence: 0.92
                method: "vector_centroid"
        "500":
          description: Classification failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /vectors/health:
    get:
      tags: [vectors]
      summary: Vector service health check
      description: |
        Returns the health status of the vector store and embedding pipeline.
        A "healthy" status means both the store and at least one embedding
        provider are operational. A "degraded" status means one or more
        components have issues but the service may still function.
      operationId: vectorHealth
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
              example:
                status: "healthy"
                store_healthy: true
                embedding_available: true
                store_stats:
                  total_vectors: 10523
                  collections:
                    email_text: 10000
                    image_text: 523
                  dimensions: 384
                  memory_bytes: 16834560
                  index_type: "in_memory_brute_force"
        "503":
          description: Service is degraded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

  /vectors/stats:
    get:
      tags: [vectors]
      summary: Vector store statistics
      description: |
        Returns detailed statistics about the vector store including total
        vectors, per-collection counts, dimensionality, memory usage, and
        the index type in use.
      operationId: vectorStats
      responses:
        "200":
          description: Store statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VectorStats"
              example:
                total_vectors: 10523
                collections:
                  email_text: 10000
                  image_text: 523
                dimensions: 384
                memory_bytes: 16834560
                index_type: "in_memory_brute_force"
        "500":
          description: Failed to retrieve statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ---------------------------------------------------------------------------
  # Ingestion
  # ---------------------------------------------------------------------------
  /ingestion/status:
    get:
      tags: [ingestion]
      summary: Ingestion progress (SSE stream)
      description: |
        Server-Sent Events stream that emits `progress` events with
        `IngestionProgress` payloads. Optionally filter by job_id.

        The stream sends a `ping` keep-alive every 15 seconds.
      operationId: ingestionStatus
      parameters:
        - name: job_id
          in: query
          required: false
          schema:
            type: string
          description: Filter events to a specific ingestion job
      responses:
        "200":
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string
                description: |
                  Each event has the format:
                  ```
                  event: progress
                  data: {"job_id":"...","total":100,"processed":50,...}
                  ```

  /ingestion/start:
    post:
      tags: [ingestion]
      summary: Start email ingestion
      description: |
        Start a new ingestion job for the specified account. Returns
        immediately with a job_id that can be used to track progress
        via the SSE status endpoint.
      operationId: startIngestion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartRequest"
            example:
              account_id: "gmail-user-1"
              full_sync: false
      responses:
        "200":
          description: Ingestion job started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
              example:
                job_id: "550e8400-e29b-41d4-a716-446655440000"
                status: "started"
                message: "Ingestion started for account gmail-user-1"
        "500":
          description: Failed to start ingestion
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /ingestion/pause:
    post:
      tags: [ingestion]
      summary: Pause ingestion
      description: Pause a running ingestion job. The job can be resumed later.
      operationId: pauseIngestion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PauseResumeRequest"
            example:
              job_id: "550e8400-e29b-41d4-a716-446655440000"
      responses:
        "200":
          description: Ingestion job paused
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
              example:
                job_id: "550e8400-e29b-41d4-a716-446655440000"
                status: "paused"
                message: "Ingestion job paused"
        "500":
          description: Failed to pause ingestion
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /ingestion/resume:
    post:
      tags: [ingestion]
      summary: Resume ingestion
      description: Resume a previously paused ingestion job.
      operationId: resumeIngestion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PauseResumeRequest"
            example:
              job_id: "550e8400-e29b-41d4-a716-446655440000"
      responses:
        "200":
          description: Ingestion job resumed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
              example:
                job_id: "550e8400-e29b-41d4-a716-446655440000"
                status: "resumed"
                message: "Ingestion job resumed"
        "500":
          description: Failed to resume ingestion
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ---------------------------------------------------------------------------
  # Insights
  # ---------------------------------------------------------------------------
  /insights/subscriptions:
    get:
      tags: [insights]
      summary: Detected subscriptions
      description: |
        Analyse the email corpus to detect subscription patterns based on
        List-Unsubscribe headers, sender frequency, and content similarity.
      operationId: getSubscriptions
      responses:
        "200":
          description: List of detected subscriptions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SubscriptionInsight"
              example:
                - sender: "newsletter@techblog.com"
                  sender_name: "TechBlog Weekly"
                  category: "Newsletter"
                  email_count: 52
                  recurrence_pattern: "weekly"
                  has_unsubscribe: true
                  first_seen: "2025-01-15T10:00:00Z"
                  last_seen: "2026-03-20T10:00:00Z"
                  estimated_read_rate: 0.35
        "500":
          description: Insight analysis failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /insights/recurring:
    get:
      tags: [insights]
      summary: Recurring sender patterns
      description: |
        Identify senders who email at regular intervals and classify
        their communication patterns.
      operationId: getRecurringSenders
      responses:
        "200":
          description: List of recurring sender patterns
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RecurringSenderInsight"
              example:
                - sender: "reports@analytics.com"
                  sender_name: "Analytics Dashboard"
                  email_count: 90
                  recurrence_pattern: "daily"
                  avg_interval_days: 1.02
                  first_seen: "2025-12-01T08:00:00Z"
                  last_seen: "2026-03-22T08:00:00Z"
        "500":
          description: Insight analysis failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /insights/report:
    get:
      tags: [insights]
      summary: Inbox intelligence report
      description: |
        Generate an aggregated inbox health report including total email
        count, category breakdown, top senders, subscription count,
        and recommended actions.
      operationId: getInboxReport
      responses:
        "200":
          description: Inbox intelligence report
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InboxReport"
              example:
                total_emails: 12450
                categories:
                  Work: 4200
                  Newsletter: 3100
                  Marketing: 2800
                  Personal: 1500
                  Finance: 450
                  Uncategorized: 400
                top_senders:
                  - sender: "notifications@github.com"
                    count: 1200
                  - sender: "newsletter@techblog.com"
                    count: 520
                subscription_count: 45
                estimated_time_savings_minutes: 120
                generated_at: "2026-03-23T14:30:00Z"
        "500":
          description: Report generation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

# ---------------------------------------------------------------------------
# Schemas
# ---------------------------------------------------------------------------
components:
  schemas:
    SemanticSearchRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
          description: Natural language search query
          example: "quarterly budget report"
        limit:
          type: integer
          description: Maximum number of results (default from server config)
          example: 20
        collection:
          type: string
          enum: [email_text, image_text, image_visual, attachment_text]
          description: Vector collection to search (defaults to email_text)
          example: "email_text"
        filters:
          type: object
          additionalProperties:
            type: string
          description: Metadata key-value filters
          example:
            category: "Finance"
        min_score:
          type: number
          format: float
          description: Minimum cosine similarity score (default from server config)
          example: 0.5

    FindSimilarRequest:
      type: object
      properties:
        limit:
          type: integer
          description: Maximum number of similar emails to return (default 10)
          example: 10

    ClassifyRequest:
      type: object
      required: [email_id, subject, from_addr, body_text]
      properties:
        email_id:
          type: string
          description: Unique identifier of the email to classify
          example: "abc-123"
        subject:
          type: string
          description: Email subject line
          example: "Q4 Budget Review"
        from_addr:
          type: string
          format: email
          description: Sender email address
          example: "finance@company.com"
        body_text:
          type: string
          description: Plain text body of the email
          example: "Please review the attached Q4 budget spreadsheet."

    ClassifyResponse:
      type: object
      properties:
        email_id:
          type: string
          description: The classified email ID
        category:
          type: string
          description: Predicted category
          enum:
            [
              Work,
              Personal,
              Finance,
              Shopping,
              Social,
              Newsletter,
              Marketing,
              Notification,
              Alerts,
              Promotions,
              Uncategorized,
            ]
        confidence:
          type: number
          format: float
          description: Confidence score (0.0 to 1.0)
        method:
          type: string
          description: Classification method used
          enum: [vector_centroid, llm_fallback]

    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/SearchResultItem"
        total:
          type: integer
          description: Number of results returned
        latency_ms:
          type: integer
          format: int64
          description: Server-side search latency in milliseconds

    SearchResultItem:
      type: object
      properties:
        email_id:
          type: string
          description: Source email identifier
        score:
          type: number
          format: float
          description: Cosine similarity score (0.0 to 1.0)
        collection:
          type: string
          description: Vector collection the result belongs to
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Filterable metadata attributes

    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum: [healthy, degraded]
          description: Overall service health
        store_healthy:
          type: boolean
          description: Whether the vector store is operational
        embedding_available:
          type: boolean
          description: Whether at least one embedding provider is available
        store_stats:
          $ref: "#/components/schemas/VectorStats"

    VectorStats:
      type: object
      properties:
        total_vectors:
          type: integer
          format: int64
          description: Total number of stored vectors
        collections:
          type: object
          additionalProperties:
            type: integer
            format: int64
          description: Vector count per collection
        dimensions:
          type: integer
          description: Embedding dimensionality (e.g., 384 for MiniLM)
        memory_bytes:
          type: integer
          format: int64
          description: Estimated memory usage in bytes
        index_type:
          type: string
          description: Type of vector index in use

    StartRequest:
      type: object
      properties:
        account_id:
          type: string
          description: Email account identifier (defaults to "default")
        full_sync:
          type: boolean
          description: Whether to re-sync all emails (default false)

    PauseResumeRequest:
      type: object
      required: [job_id]
      properties:
        job_id:
          type: string
          description: Ingestion job identifier

    JobResponse:
      type: object
      properties:
        job_id:
          type: string
          description: Unique job identifier (UUID)
        status:
          type: string
          enum: [started, paused, resumed]
          description: Current job status
        message:
          type: string
          description: Human-readable status message

    IngestionProgress:
      type: object
      description: Real-time progress update for an ingestion job (emitted via SSE)
      properties:
        job_id:
          type: string
        total:
          type: integer
          format: int64
          description: Total emails to process
        processed:
          type: integer
          format: int64
          description: Emails processed so far
        embedded:
          type: integer
          format: int64
          description: Emails with generated embeddings
        categorized:
          type: integer
          format: int64
          description: Emails categorized
        failed:
          type: integer
          format: int64
          description: Emails that failed processing
        phase:
          type: string
          enum: [syncing, embedding, categorizing, clustering, analyzing, complete]
          description: Current pipeline phase
        eta_seconds:
          type: integer
          format: int64
          nullable: true
          description: Estimated seconds remaining
        emails_per_second:
          type: number
          format: double
          description: Current processing throughput

    SubscriptionInsight:
      type: object
      properties:
        sender:
          type: string
          format: email
          description: Sender email address
        sender_name:
          type: string
          description: Display name of the sender
        category:
          type: string
          enum: [Newsletter, Marketing, Notification, Receipt, Social, Unknown]
          description: Subscription category
        email_count:
          type: integer
          format: int64
          description: Total emails received from this sender
        recurrence_pattern:
          type: string
          description: Detected send frequency
        has_unsubscribe:
          type: boolean
          description: Whether List-Unsubscribe header is present
        first_seen:
          type: string
          format: date-time
          description: Date of the earliest email from this sender
        last_seen:
          type: string
          format: date-time
          description: Date of the most recent email from this sender
        estimated_read_rate:
          type: number
          format: float
          description: Estimated percentage of emails opened (0.0 to 1.0)

    RecurringSenderInsight:
      type: object
      properties:
        sender:
          type: string
          format: email
        sender_name:
          type: string
        email_count:
          type: integer
          format: int64
        recurrence_pattern:
          type: string
          description: Detected pattern (daily, weekly, monthly, etc.)
        avg_interval_days:
          type: number
          format: float
          description: Average days between emails
        first_seen:
          type: string
          format: date-time
        last_seen:
          type: string
          format: date-time

    InboxReport:
      type: object
      properties:
        total_emails:
          type: integer
          format: int64
        categories:
          type: object
          additionalProperties:
            type: integer
            format: int64
          description: Email count per category
        top_senders:
          type: array
          items:
            type: object
            properties:
              sender:
                type: string
              count:
                type: integer
                format: int64
        subscription_count:
          type: integer
          description: Number of detected subscriptions
        estimated_time_savings_minutes:
          type: integer
          description: Estimated minutes saved by using Emailibrium
        generated_at:
          type: string
          format: date-time

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message