openapi: 3.1.0
info:
  title: varlog.in Public API
  version: 1.0.0
  description: Free, read-only infrastructure health and provider-status data. No account is required.
servers:
  - url: https://api.varlog.in
paths:
  /v1/report/{domain}:
    get:
      summary: Generate or retrieve a domain health report
      operationId: getDomainReport
      parameters:
        - name: domain
          in: path
          required: true
          schema: { type: string, examples: [example.com] }
        - name: fresh
          in: query
          description: Request a fresh scan. Repeated refreshes are locked for 60 seconds.
          schema: { type: integer, enum: [1] }
      responses:
        '200':
          description: Health report
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Report' }
        '400': { description: Invalid domain }
        '403': { description: Private or internal target rejected }
        '429': { description: A fresh scan is already running }
  /v1/badge/{domain}.svg:
    get:
      summary: Render a report-grade badge
      operationId: getGradeBadge
      parameters:
        - name: domain
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: SVG badge
          content:
            image/svg+xml: { schema: { type: string } }
  /api/status:
    get:
      summary: Current status for monitored cloud and SaaS providers
      operationId: getProviderStatus
      responses:
        '200':
          description: Provider status snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated_at: { type: string, format: date-time }
                  service_count: { type: integer }
                  services: { type: array, items: { $ref: '#/components/schemas/ServiceStatus' } }
components:
  schemas:
    Report:
      type: object
      required: [domain, generatedAt, overall, categories]
      properties:
        domain: { type: string }
        scoringVersion: { type: string }
        generatedAt: { type: string, format: date-time }
        durationMs: { type: integer }
        coverage:
          type: object
          properties:
            percent: { type: integer, minimum: 0, maximum: 100 }
            confidence: { type: string }
        overall:
          type: object
          properties:
            grade: { type: [string, 'null'] }
            percent: { type: [integer, 'null'] }
            status: { type: string }
        categories: { type: object, additionalProperties: true }
        rootCause: { type: object, additionalProperties: true }
        recommendations: { type: array, items: { type: object, additionalProperties: true } }
    ServiceStatus:
      type: object
      properties:
        name: { type: string }
        category: { type: string }
        status: { type: string }
        description: { type: [string, 'null'] }