{
  "openapi": "3.0.3",
  "info": {
    "title": "GIGA.FORA Agent API",
    "version": "2.0.0",
    "description": "Agent-focused endpoints for Fora comments embed, install, validation, and quickstart."
  },
  "servers": [
    { "url": "https://giga.mobile" }
  ],
  "components": {
    "securitySchemes": {
      "AgentBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "token"
      },
      "TenantSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "gf_tenant_session"
      }
    }
  },
  "paths": {
    "/api/embed/quickstart-anon": {
      "post": {
        "summary": "Create an anonymous site — no auth required (recommended)",
        "description": "One-shot anonymous site creation. No login, no signup. Rate limited to 3 sites per IP per hour. Returns siteKey, snippet, and portal URL. Use /api/embed/quickstart for authenticated sites.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "domain"],
                "properties": {
                  "name": { "type": "string", "example": "My Blog" },
                  "domain": { "type": "string", "example": "myblog.com" },
                  "framework": {
                    "type": "string",
                    "enum": ["astro", "hugo", "jekyll", "11ty", "hakyll", "html"],
                    "default": "html"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Anonymous site created with snippet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "siteKey": { "type": "string", "description": "anon_ prefixed site key" },
                    "name": { "type": "string" },
                    "domain": { "type": "string" },
                    "framework": { "type": "string" },
                    "snippet": { "type": "string" },
                    "portalUrl": { "type": "string" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "429": { "description": "Rate limit reached (3 sites per IP per hour)" }
        }
      }
    },
    "/api/embed/quickstart": {
      "post": {
        "summary": "Create a site under your account (requires auth)",
        "description": "One-shot authenticated site creation. Requires tenant auth (magic link session). Returns siteKey, framework-specific snippet, and portal URL.",
        "security": [{ "TenantSession": [] }],
        "security": [{ "TenantSession": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "domain"],
                "properties": {
                  "name": { "type": "string", "example": "My Blog" },
                  "domain": { "type": "string", "example": "myblog.com" },
                  "framework": {
                    "type": "string",
                    "enum": ["astro", "hugo", "jekyll", "11ty", "html", "react", "vue", "svelte", "nextjs"],
                    "default": "html"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Site created with snippet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "siteKey": { "type": "string" },
                    "siteId": { "type": "string" },
                    "name": { "type": "string" },
                    "domain": { "type": "string" },
                    "framework": { "type": "string" },
                    "snippet": { "type": "string" },
                    "portalUrl": { "type": "string" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": { "description": "Not authenticated. Run: npx fora login" },
          "403": { "description": "Site limit reached or invalid domain" }
        }
      }
    },
    "/api/embed/count": {
      "get": {
        "summary": "Get comment count for a page (SSR-safe, cacheable)",
        "description": "Returns the number of active comments for a given site and page. Use at build time for static site generators.",
        "parameters": [
          { "name": "site_key", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "page_id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Comment count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "thread_id": { "type": "string", "nullable": true },
                    "site_key": { "type": "string" },
                    "page_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/embed/structured-data": {
      "get": {
        "summary": "Get JSON-LD structured data for a page (SEO)",
        "description": "Returns DiscussionForumPosting schema with top comments for rich search results.",
        "parameters": [
          { "name": "site_key", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "page_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 5 } }
        ],
        "responses": {
          "200": {
            "description": "JSON-LD structured data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonld": { "type": "object", "nullable": true },
                    "site_key": { "type": "string" },
                    "page_id": { "type": "string" },
                    "thread_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/embed/config": {
      "post": {
        "summary": "Get embed configuration for direct-render mode",
        "description": "Returns context token, thread/post IDs, theme defaults, and features. Used by direct-render (Shadow DOM) mode.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["site_key", "page_identifier"],
                "properties": {
                  "site_key": { "type": "string" },
                  "page_identifier": { "type": "string" },
                  "page_url": { "type": "string" },
                  "page_title": { "type": "string" },
                  "requested_features": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embed configuration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ctx": { "type": "string" },
                    "thread_id": { "type": "string" },
                    "post_id": { "type": "string" },
                    "site_plan": { "type": "string" },
                    "effective_features": { "type": "array", "items": { "type": "string" } },
                    "theme_defaults": { "type": "object" },
                    "ui_customization": { "type": "object" }
                  }
                }
              }
            }
          },
          "403": { "description": "Invalid site or origin not allowed" }
        }
      }
    },
    "/api/agent/embed/install": {
      "post": {
        "summary": "Generate install snippet for a site (legacy agent API)",
        "security": [{ "AgentBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site_id": { "type": "string" },
                  "domain": { "type": "string" },
                  "route_pattern": { "type": "string", "example": "/blog/:slug" },
                  "container_id": { "type": "string", "example": "comments" },
                  "theme": { "type": "string", "enum": ["auto", "light", "dark"] },
                  "requested_features": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Install payload with snippet" },
          "401": { "description": "Invalid or missing agent token" },
          "403": { "description": "Token cannot access requested site" }
        }
      }
    },
    "/api/agent/embed/validate": {
      "post": {
        "summary": "Validate domain/page/feature setup for embed integration",
        "security": [{ "AgentBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "site_id": { "type": "string" },
                  "domain": { "type": "string" },
                  "page_id": { "type": "string" },
                  "page_url": { "type": "string" },
                  "requested_features": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }
                },
                "required": ["page_id", "page_url"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Validation result" },
          "401": { "description": "Invalid or missing agent token" },
          "403": { "description": "Token cannot access requested site" }
        }
      }
    }
  }
}