openapi: 3.1.0
info:
  title: HTMLDrop API
  version: 1.0.0
  description: REST API for publishing and managing HTMLDrop pages.
servers:
  - url: https://htmldrop.in/api/v1
security:
  - bearerAuth: []
paths:
  /pages:
    get:
      summary: List pages
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Page list
    post:
      summary: Publish a page
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishBody"
      responses:
        "200":
          description: Published page
  /pages/{slug}:
    get:
      summary: Get page metadata
      parameters:
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Page metadata
    patch:
      summary: Update page content
      parameters:
        - $ref: "#/components/parameters/slug"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishBody"
      responses:
        "200":
          description: Updated page
    delete:
      summary: Delete a page
      parameters:
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Deleted
  /pages/{slug}/duplicate:
    post:
      summary: Duplicate a page to a new slug
      parameters:
        - $ref: "#/components/parameters/slug"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customSlug:
                  type: string
      responses:
        "200":
          description: Duplicated page
  /pages/{slug}/settings:
    get:
      summary: Get page settings
      parameters:
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Settings
    patch:
      summary: Update page settings
      parameters:
        - $ref: "#/components/parameters/slug"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                clearPassword:
                  type: boolean
                expiresAt:
                  type: string
                  nullable: true
      responses:
        "200":
          description: Updated settings
  /pages/{slug}/analytics:
    get:
      summary: Get page analytics
      parameters:
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Analytics payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  analytics:
                    $ref: "#/components/schemas/PageAnalytics"
  /pages/{slug}/domain:
    get:
      summary: Get custom domain for a page
      parameters:
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Domain record or null
    post:
      summary: Attach a custom domain (Pro+)
      parameters:
        - $ref: "#/components/parameters/slug"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [hostname]
              properties:
                hostname:
                  type: string
      responses:
        "200":
          description: Domain attached with DNS instructions
    delete:
      summary: Remove custom domain from page
      parameters:
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Domain removed
  /domains:
    get:
      summary: List account custom domains
      responses:
        "200":
          description: Domain inventory
    patch:
      summary: Reassign a domain to another page (Business)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [domainId, pageId]
              properties:
                domainId:
                  type: string
                pageId:
                  type: string
      responses:
        "200":
          description: Domain reassigned
  /ai/metadata:
    post:
      summary: Generate page metadata from content
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AiMetadataBody"
      responses:
        "200":
          description: Generated metadata
        "429":
          description: Quota or rate limit exceeded
        "503":
          description: AI API disabled
  /ai/generate:
    post:
      summary: Generate, improve, or fix page content
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AiGenerateBody"
      responses:
        "200":
          description: Generated content
        "429":
          description: Quota or rate limit exceeded
        "503":
          description: AI API disabled
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key prefixed with hd_live_
  parameters:
    slug:
      name: slug
      in: path
      required: true
      schema:
        type: string
  schemas:
    PageAnalytics:
      type: object
      properties:
        totalViews:
          type: integer
        viewsLast7Days:
          type: integer
        viewsLast30Days:
          type: integer
        topReferrers:
          type: array
          items:
            type: object
            properties:
              referrer:
                type: string
              count:
                type: integer
        dailyViews:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              count:
                type: integer
        averageTimeOnPageSeconds:
          type: integer
        totalEngagedSeconds:
          type: integer
        engagedViews:
          type: integer
    PublishBody:
      type: object
      properties:
        html:
          type: string
        content:
          type: string
        format:
          type: string
          enum: [html, md]
        template:
          type: string
        title:
          type: string
        customSlug:
          type: string
        newSlug:
          type: string
          description: Rename an existing page slug (Starter+)
        expiresAt:
          type: string
          nullable: true
        zipBase64:
          type: string
          description: Base64-encoded ZIP for bundle publish (alternative to session upload endpoint)
    AiMetadataBody:
      type: object
      required: [content, format]
      properties:
        content:
          type: string
        format:
          type: string
          enum: [html, md]
        fields:
          type: array
          items:
            type: string
            enum: [title, description, keywords]
        slug:
          type: string
          description: Optional page slug for content-hash idempotency
    AiGenerateBody:
      type: object
      required: [format, action]
      properties:
        format:
          type: string
          enum: [html, md]
        action:
          type: string
          enum: [generate, improve, fix]
        prompt:
          type: string
          description: Required when action is generate
        content:
          type: string
          description: Required when action is improve or fix
