api.yaml

openapi: "3.0.3"
info:
  title: API Py
  version: "1.0.0"
  description: |
    Monolith-modular Python (FastAPI) API on Hugging Face Spaces.
    Scrape any website via Jina, get favicons via Google s2.
  contact:
    name: API Py
    url: https://huggingface.co/spaces/lljz66/api
  license:
    name: MIT

servers:
  - url: https://lljz66-api.hf.space
    description: Production

tags:
  - name: Health
    description: Service status
  - name: Content
    description: Page content extraction via Jina
  - name: Favicon
    description: Favicon lookup via Google s2

paths:
  /health:
    get:
      tags: [Health]
      summary: Health check
      operationId: health
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /scrape:
    post:
      tags: [Content]
      summary: Scrape website content via Jina Reader
      operationId: scrape
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                  example: "https://example.com"
      responses:
        "200":
          description: Content extracted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScrapeResponse"
        "400":
          description: Invalid URL
        "502":
          description: Could not fetch content

  /favicon:
    get:
      tags: [Favicon]
      summary: Get favicon URL via Google s2
      operationId: favicon
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            format: uri
          description: Page URL to find the favicon for
      responses:
        "200":
          description: Favicon URL returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaviconResponse"

components:
  schemas:
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: "ok"
        service:
          type: string
          example: "API Py"
        version:
          type: string
          example: "1.0.0"

    ScrapeResponse:
      type: object
      properties:
        url:
          type: string
        source:
          type: string
          example: "jina"
        title:
          type: string
          nullable: true
        content:
          type: string

    FaviconResponse:
      type: object
      properties:
        url:
          type: string
        domain:
          type: string
        icon_url:
          type: string
          example: "https://www.google.com/s2/favicons?domain=example.com&sz=128"