openapi: 3.0.3
servers:
  - url: https://prod.api.market/api/v1/gomsilo/crypto-news
info:
  title: Crypto News Aggregator and Sentiment Analysis
  description: Get real-time cryptocurrency news with AI-powered market analysis.
  version: 1.0.0
  contact:
    name: Coin Echo Crypto News Aggregator
    url: https://github.com/degola
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
paths:
  /api/news:
    get:
      tags:
        - News
      summary: Get paginated live news
      description: >
        Retrieve paginated live cryptocurrency news items with real-time
        sentiment analysis.

        News items are sorted by publication date (newest first).
      parameters:
        - name: page
          in: query
          description: Page number for pagination (starts from 1)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/NewsItem"
                  pagination:
                    $ref: "#/components/schemas/PaginationInfo"
              example:
                items:
                  - _id: 507f1f77bcf86cd799439011
                    title: Bitcoin ETF Approval Leads to Market Rally
                    link: https://example.com/bitcoin-etf-approval
                    description: Major cryptocurrency ETF gets regulatory approval...
                    content: Full article content...
                    markdownContent: "**Bitcoin ETF Approval** leads to..."
                    plainText: Bitcoin ETF Approval leads to increased institutional investment...
                    pubDate: 2024-01-15T10:30:00Z
                    categories:
                      - Cryptocurrency
                      - Regulation
                    tags:
                      - bitcoin
                      - etf
                      - regulation
                    author: John Doe
                    imageUrl: https://example.com/image.jpg
                    isBull: true
                    source:
                      _id: 507f1f77bcf86cd799439012
                      domain: cryptonews.com
                      websiteTitle: Crypto News
                    analysis:
                      summary: Bitcoin ETF approval leads to increased institutional investment and
                        market optimism.
                      marketImpactScore: 0.9
                      cryptoRelevanceScore: 1
                      sentimentScore: 0.8
                      tags:
                        - bullish_prediction
                        - etfs
                        - market_situation
                pagination:
                  total: 1250
                  page: 1
                  limit: 10
                  hasMore: true
        "400":
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    parameters:
      - &a1
        description: API.market API Key
        in: header
        name: x-api-market-key
        value: Please Login/Signup to get an API Key
        required: true
        schema:
          type: string
  /api/top-news:
    get:
      summary: Get top news by time interval
      tags:
        - Top News
      description: >
        Retrieve top cryptocurrency news items based on market impact, crypto
        relevance, and sentiment scores.

        News items are ranked by a composite relevance score and filtered by
        time interval.
      parameters:
        - name: interval
          in: query
          description: Time interval for news filtering
          required: true
          schema:
            type: string
            enum:
              - 6h
              - 24h
              - 7d
          example: 24h
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/NewsItem"
              example:
                items:
                  - _id: 507f1f77bcf86cd799439013
                    title: Ethereum Upgrade Boosts DeFi Ecosystem
                    link: https://example.com/ethereum-upgrade
                    description: Latest Ethereum upgrade brings significant improvements...
                    pubDate: 2024-01-15T08:00:00Z
                    categories:
                      - DeFi
                      - Ethereum
                    isBull: true
                    source:
                      _id: 507f1f77bcf86cd799439014
                      domain: defipulse.com
                      websiteTitle: DeFi Pulse
                    analysis:
                      summary: Ethereum upgrade significantly improves DeFi ecosystem performance and
                        user experience.
                      marketImpactScore: 0.85
                      cryptoRelevanceScore: 0.95
                      sentimentScore: 0.7
                      tags:
                        - innovation
                        - defi
                        - ethereum
        "400":
          description: Invalid time interval
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    parameters:
      - *a1
  /api/bulls-bears:
    get:
      summary: Get bull and bear news analysis
      tags:
        - Sentiment Analysis
      description: >
        Retrieve cryptocurrency news items categorized by bull/bear sentiment
        with market impact filtering.

        Only includes news items with high market impact scores (≥0.8).
      parameters:
        - name: interval
          in: query
          description: Time interval for news filtering
          required: true
          schema:
            type: string
            enum:
              - 6h
              - 24h
              - 7d
          example: 24h
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  bullNews:
                    type: array
                    items:
                      $ref: "#/components/schemas/NewsItem"
                    description: News items with bullish sentiment (sentiment score > 0)
                  bearNews:
                    type: array
                    items:
                      $ref: "#/components/schemas/NewsItem"
                    description: News items with bearish sentiment (sentiment score ≤ 0)
                  totalBullCount:
                    type: integer
                    description: Total count of bullish news items in the time period
                  totalBearCount:
                    type: integer
                    description: Total count of bearish news items in the time period
              example:
                bullNews:
                  - _id: 507f1f77bcf86cd799439015
                    title: Institutional Bitcoin Adoption Accelerates
                    link: https://example.com/institutional-bitcoin
                    pubDate: 2024-01-15T09:00:00Z
                    isBull: true
                    source:
                      _id: 507f1f77bcf86cd799439016
                      domain: coindesk.com
                      websiteTitle: CoinDesk
                    analysis:
                      summary: Major institutions increasing Bitcoin allocations, signaling strong
                        market confidence.
                      marketImpactScore: 0.95
                      cryptoRelevanceScore: 1
                      sentimentScore: 0.9
                      tags:
                        - institutional
                        - bullish_prediction
                        - bitcoin
                bearNews:
                  - _id: 507f1f77bcf86cd799439017
                    title: Regulatory Crackdown on Crypto Exchanges
                    link: https://example.com/regulatory-crackdown
                    pubDate: 2024-01-15T07:00:00Z
                    isBull: false
                    source:
                      _id: 507f1f77bcf86cd799439018
                      domain: reuters.com
                      websiteTitle: Reuters
                    analysis:
                      summary: Global regulatory authorities announce stricter crypto exchange
                        regulations.
                      marketImpactScore: 0.9
                      cryptoRelevanceScore: 0.95
                      sentimentScore: -0.6
                      tags:
                        - regulation
                        - bearish_prediction
                        - exchanges
                totalBullCount: 15
                totalBearCount: 8
        "400":
          description: Invalid time interval
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    parameters:
      - *a1
  /api/status:
    get:
      tags:
        - System
      summary: Health check endpoint
      description: |
        Simple health check endpoint to verify API and database connectivity.
        Returns system status, uptime, and service health information.
      responses:
        "200":
          description: System is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - healthy
                      - unhealthy
                    example: healthy
                  timestamp:
                    type: string
                    format: date-time
                    description: Current timestamp
                    example: 2024-01-15T10:30:00Z
                  version:
                    type: string
                    description: API version
                    example: 1.0.0
                  services:
                    type: object
                    properties:
                      database:
                        type: string
                        enum:
                          - connected
                          - disconnected
                          - error
                        example: connected
                      api:
                        type: string
                        example: running
                  uptime:
                    type: number
                    format: float
                    description: Process uptime in seconds
                    example: 3600.5
                  environment:
                    type: string
                    description: Current environment
                    example: production
              example:
                status: healthy
                timestamp: 2024-01-15T10:30:00Z
                version: 1.0.0
                services:
                  database: connected
                  api: running
                uptime: 3600.5
                environment: production
        "503":
          description: System is unhealthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - healthy
                      - unhealthy
                    example: unhealthy
                  timestamp:
                    type: string
                    format: date-time
                    example: 2024-01-15T10:30:00Z
                  error:
                    type: string
                    example: Health check failed
                  services:
                    type: object
                    properties:
                      database:
                        type: string
                        enum:
                          - connected
                          - disconnected
                          - error
                          - unknown
                        example: error
                      api:
                        type: string
                        example: error
              example:
                status: unhealthy
                timestamp: 2024-01-15T10:30:00Z
                error: Health check failed
                services:
                  database: error
                  api: error
    parameters:
      - *a1
components:
  schemas:
    NewsItem:
      type: object
      required:
        - _id
        - title
        - link
        - pubDate
        - categories
        - tags
        - source
      properties:
        _id:
          type: string
          description: Unique identifier for the news item
          example: 507f1f77bcf86cd799439011
        title:
          type: string
          description: News article title
          example: Bitcoin ETF Approval Leads to Market Rally
        link:
          type: string
          format: uri
          description: URL to the original news article
          example: https://example.com/bitcoin-etf-approval
        description:
          type: string
          description: News article description/summary
          example: Major cryptocurrency ETF gets regulatory approval...
        content:
          type: string
          description: Full HTML content of the news article
        markdownContent:
          type: string
          description: Markdown version of the article content
        plainText:
          type: string
          description: Plain text version of the article content
        pubDate:
          type: string
          format: date-time
          description: Publication date and time
          example: 2024-01-15T10:30:00Z
        categories:
          type: array
          items:
            type: string
          description: News categories/topics
          example:
            - Cryptocurrency
            - Regulation
        tags:
          type: array
          items:
            type: string
          description: News tags/keywords
          example:
            - bitcoin
            - etf
            - regulation
        author:
          type: string
          description: Article author name
          example: John Doe
        imageUrl:
          type: string
          format: uri
          description: URL to the article's featured image
          example: https://example.com/image.jpg
        isBull:
          type: boolean
          description: Bull/bear sentiment signal (true = bullish, false = bearish)
          example: true
        source:
          $ref: "#/components/schemas/NewsSource"
        analysis:
          $ref: "#/components/schemas/NewsAnalysis"
        publishedAt:
          type: string
          format: date-time
          description: Timestamp when the item was published to real-time feed
          example: 2024-01-15T10:30:00Z
    NewsSource:
      type: object
      required:
        - _id
        - domain
        - websiteTitle
      properties:
        _id:
          type: string
          description: Unique identifier for the news source
          example: 507f1f77bcf86cd799439012
        domain:
          type: string
          description: News source domain
          example: cryptonews.com
        websiteTitle:
          type: string
          description: News source website title
          example: Crypto News
        websiteUrl:
          type: string
          format: uri
          description: News source website URL
          example: https://cryptonews.com
        contentSourceType:
          type: string
          enum:
            - rss
            - crawler
            - unknown
          description: Type of content source
          example: rss
        isActive:
          type: boolean
          description: Whether the news source is currently active
          example: true
    NewsAnalysis:
      type: object
      required:
        - summary
        - marketImpactScore
        - cryptoRelevanceScore
        - sentimentScore
        - tags
      properties:
        summary:
          type: string
          description: AI-generated summary of the news content
          example: Bitcoin ETF approval leads to increased institutional investment and
            market optimism.
        marketImpactScore:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Market impact score (0 = no impact, 1 = highest impact)
          example: 0.9
        cryptoRelevanceScore:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Cryptocurrency relevance score (0 = not relevant, 1 = highly
            relevant)
          example: 1
        sentimentScore:
          type: number
          format: float
          minimum: -1
          maximum: 1
          description: Sentiment score (-1 = most bearish, 0 = neutral, 1 = most bullish)
          example: 0.8
        tags:
          type: array
          items:
            type: string
            enum:
              - bearish_prediction
              - bullish_prediction
              - market_situation
              - new_coins
              - coin_pump
              - coin_dump
              - innovation
              - new_product
              - regulation
              - earnings_staking
              - large_purchase
              - large_sell
              - whale_movement
              - etfs
          description: Analysis tags categorizing the news content
          example:
            - bullish_prediction
            - etfs
            - market_situation
    PaginationInfo:
      type: object
      required:
        - total
        - page
        - limit
        - hasMore
      properties:
        total:
          type: integer
          description: Total number of items available
          example: 1250
        page:
          type: integer
          description: Current page number
          example: 1
        limit:
          type: integer
          description: Number of items per page
          example: 10
        hasMore:
          type: boolean
          description: Whether there are more items available
          example: true
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
          example: "Invalid time interval. Must be one of: 6h, 24h, 7d"
tags:
  - name: System
    description: System health and status endpoints
  - name: News
    description: Live news feed operations
  - name: Top News
    description: Top news based on relevance and impact
  - name: Sentiment Analysis
    description: Bull/bear sentiment analysis
  - name: cryptography
    description: Operations related to cryptography
  - name: finance
    description: Operations related to finance
  - name: artificial-intelligence
    description: Operations related to artificial-intelligence
  - name: news
    description: Operations related to news
  - name: media
    description: Operations related to media
  - name: tools
    description: Operations related to tools
security: {}