{
  "openapi": "3.1.0",
  "info": {
    "title": "RankSight Public REST API",
    "version": "1.0.0",
    "description": "Production-ready, machine-readable API for RankSight.lol — an open discovery and algorithmic ranking platform for internet software, startups, SaaS, developer tools, and AI applications.",
    "contact": {
      "name": "RankSight API Team",
      "url": "https://ranksight.lol/ai",
      "email": "support@ranksight.lol"
    },
    "license": {
      "name": "Open Data / Attribution Required",
      "url": "https://ranksight.lol/terms"
    }
  },
  "servers": [
    {
      "url": "https://ranksight.lol",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/v1/projects": {
      "get": {
        "summary": "List Public Projects",
        "description": "Retrieve a paginated collection of publicly listed projects with optional filters for category, product type, pricing model, verification status, and sorting.",
        "operationId": "listProjects",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search term for name, description, or domain",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Category ID or category slug filter",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "product_type",
            "in": "query",
            "description": "Product classification (e.g., SaaS, AI Tool, Developer Tool, Open Source)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pricing_type",
            "in": "query",
            "description": "Pricing model (e.g., free, freemium, paid, open_source)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "verified",
            "in": "query",
            "description": "Filter only verified domain owner projects (true/false)",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorting order",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "rank",
                "trending",
                "new",
                "shares",
                "name"
              ],
              "default": "rank"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (1-indexed)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of items per page (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful project list response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectListResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit a New Project",
        "description": "Submit an internet project for public listing and leaderboard ranking. Subject to rate limits, anti-abuse checks, and duplicate detection.",
        "operationId": "submitProject",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProjectSubmissionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Project successfully created and listed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectSubmissionSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate project or domain conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed on email or URL format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects/{slug}": {
      "get": {
        "summary": "Get Project Profile by Slug",
        "description": "Retrieve full public metadata, social links, updates, relationships, and historical rank snapshots for a single project.",
        "operationId": "getProjectBySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Unique project URL slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full public project profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "Project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects/check": {
      "get": {
        "summary": "Check Project Existence",
        "description": "Verify whether a website domain or project slug already exists on RankSight using normalized URL parsing.",
        "operationId": "checkProjectExists",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Target website URL or domain (e.g., https://example.com or example.com)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Target domain string",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Existence verification status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects/new": {
      "get": {
        "summary": "List Recently Added Projects",
        "description": "Retrieve newly listed projects ordered chronologically by created_at timestamp.",
        "operationId": "getNewProjects",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page limit (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of recently created projects",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/rankings": {
      "get": {
        "summary": "Get Public Leaderboard Rankings",
        "description": "Retrieve the official, deterministic RankSight leaderboard rankings calculated from verified distribution on X, unique sharers, freshness, and quality.",
        "operationId": "getRankings",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category ID or slug",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "description": "Ranking period (all_time, today, 7d, 30d)",
            "required": false,
            "schema": {
              "type": "string",
              "default": "all_time"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Limit (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rankings collection matching the live website",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RankingsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/trending": {
      "get": {
        "summary": "Get Trending Projects",
        "description": "Retrieve projects with the highest active momentum based on exponential time-decayed X share velocity within the last 7 days.",
        "operationId": "getTrendingProjects",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Category filter",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Limit (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trending projects collection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrendingResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/categories": {
      "get": {
        "summary": "List All Categories",
        "description": "Retrieve the complete category taxonomy with live project counts computed from the database.",
        "operationId": "listCategories",
        "responses": {
          "200": {
            "description": "List of categories",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoriesListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/categories/{slug}": {
      "get": {
        "summary": "Get Category by Slug",
        "description": "Retrieve detailed category taxonomy, definition, scope, FAQs, and top ranked projects.",
        "operationId": "getCategoryBySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Category slug (e.g., ai-tools, developer-tools)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number for projects",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Projects limit (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Category details and projects",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "Category not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "summary": "Search Projects",
        "description": "Full-text pattern search against name, slug, tagline, description, features, company name, founder, category, or domain.",
        "operationId": "searchProjects",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search term",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Limit (max 50)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/link-exchange": {
      "get": {
        "summary": "List Public Link Exchange Offers",
        "description": "Browse active editorial and reciprocal link exchange opportunities across verified partner websites.",
        "operationId": "listLinkExchangeOffers",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search term",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "website_type",
            "in": "query",
            "description": "Filter by website type (Blog, SaaS, Directory, etc.)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "description": "Filter by country",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "language",
            "in": "query",
            "description": "Filter by language",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Limit (max 50)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public link exchange offers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkExchangeListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "summary": "Get Platform Statistics",
        "description": "Retrieve real-time aggregate statistics from the RankSight production database.",
        "operationId": "getStats",
        "responses": {
          "200": {
            "description": "Live aggregate platform statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PublicProject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "proj_abc123"
          },
          "name": {
            "type": "string",
            "example": "Linear"
          },
          "slug": {
            "type": "string",
            "example": "linear"
          },
          "tagline": {
            "type": "string",
            "example": "Issue tracking built for speed"
          },
          "description": {
            "type": "string",
            "example": "Linear is a purpose-built tool for planning and building products."
          },
          "what_it_does": {
            "type": "string",
            "example": "Streamlines software issue tracking and product roadmaps."
          },
          "key_features": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Keyboard-first workflows",
              "Real-time sync",
              "Git integrations"
            ]
          },
          "target_audience": {
            "type": "string",
            "example": "Engineers and product designers"
          },
          "pricing_type": {
            "type": "string",
            "example": "freemium"
          },
          "pricing_details": {
            "type": "string",
            "example": "Free plan available, paid tiers from $8/mo"
          },
          "product_type": {
            "type": "string",
            "example": "SaaS"
          },
          "category": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string",
                "example": "Developer Tools"
              },
              "slug": {
                "type": "string",
                "example": "developer-tools"
              },
              "icon": {
                "type": "string",
                "example": "Code"
              }
            }
          },
          "subcategory": {
            "type": "string"
          },
          "website_url": {
            "type": "string",
            "format": "uri",
            "example": "https://linear.app"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "example": "https://ranksight.lol/project/linear"
          },
          "logo_url": {
            "type": "string",
            "format": "uri"
          },
          "github_url": {
            "type": "string",
            "format": "uri"
          },
          "doc_url": {
            "type": "string",
            "format": "uri"
          },
          "app_store_url": {
            "type": "string",
            "format": "uri"
          },
          "play_store_url": {
            "type": "string",
            "format": "uri"
          },
          "product_hunt_url": {
            "type": "string",
            "format": "uri"
          },
          "founder_name": {
            "type": "string",
            "example": "Karri Saarinen"
          },
          "company_name": {
            "type": "string",
            "example": "Linear Orbit, Inc."
          },
          "founded_year": {
            "type": "integer",
            "nullable": true,
            "example": 2019
          },
          "location": {
            "type": "string",
            "example": "San Francisco, CA"
          },
          "rank": {
            "type": "object",
            "properties": {
              "current": {
                "type": "integer",
                "example": 1
              },
              "previous": {
                "type": "integer",
                "example": 1
              },
              "category": {
                "type": "integer",
                "example": 1
              },
              "score": {
                "type": "number",
                "example": 95.4
              },
              "trending_score": {
                "type": "number",
                "example": 42.1
              },
              "last_updated": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "metrics": {
            "type": "object",
            "properties": {
              "share_count": {
                "type": "integer",
                "example": 12
              },
              "verified_share_count": {
                "type": "integer",
                "example": 8
              },
              "unique_sharers_count": {
                "type": "integer",
                "example": 8
              },
              "view_count": {
                "type": "integer",
                "example": 340
              },
              "click_count": {
                "type": "integer",
                "example": 120
              }
            }
          },
          "verification": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "unverified",
                  "claimed",
                  "verified"
                ],
                "example": "verified"
              },
              "is_verified": {
                "type": "boolean",
                "example": true
              },
              "verified_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "is_featured": {
            "type": "boolean",
            "example": false
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "example": 1
          },
          "limit": {
            "type": "integer",
            "example": 20
          },
          "total": {
            "type": "integer",
            "example": 85
          },
          "total_pages": {
            "type": "integer",
            "example": 5
          },
          "has_next": {
            "type": "boolean",
            "example": true
          },
          "has_prev": {
            "type": "boolean",
            "example": false
          }
        }
      },
      "ProjectListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicProject"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "ProjectDetailResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "project": {
                "$ref": "#/components/schemas/PublicProject"
              },
              "socials": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "updates": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "relationships": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "rank_history": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "ProjectCheckResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "exists": {
                "type": "boolean",
                "example": true
              },
              "project": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "website_url": {
                    "type": "string"
                  },
                  "current_rank": {
                    "type": "integer"
                  },
                  "category_name": {
                    "type": "string"
                  },
                  "category_slug": {
                    "type": "string"
                  },
                  "verified_status": {
                    "type": "string"
                  },
                  "created_at": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "ProjectSubmissionRequest": {
        "type": "object",
        "required": [
          "name",
          "website_url",
          "category_id",
          "tagline",
          "what_it_does",
          "owner_email"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "My AI Tool"
          },
          "website_url": {
            "type": "string",
            "format": "uri",
            "example": "https://myaitool.example.com"
          },
          "category_id": {
            "type": "string",
            "example": "ai-tools"
          },
          "tagline": {
            "type": "string",
            "maxLength": 140,
            "example": "Automated research assistant"
          },
          "what_it_does": {
            "type": "string",
            "example": "Summarizes papers into key actionable insights."
          },
          "description": {
            "type": "string"
          },
          "owner_email": {
            "type": "string",
            "format": "email",
            "example": "founder@example.com"
          },
          "pricing_type": {
            "type": "string",
            "enum": [
              "free",
              "freemium",
              "paid",
              "open_source",
              "contact"
            ],
            "default": "freemium"
          },
          "pricing_details": {
            "type": "string"
          },
          "product_type": {
            "type": "string",
            "default": "SaaS"
          },
          "key_features": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 5
          },
          "target_audience": {
            "type": "string"
          },
          "founder_name": {
            "type": "string"
          },
          "company_name": {
            "type": "string"
          },
          "logo_url": {
            "type": "string",
            "format": "uri"
          },
          "github_url": {
            "type": "string",
            "format": "uri"
          },
          "doc_url": {
            "type": "string",
            "format": "uri"
          },
          "twitter_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ProjectSubmissionSuccess": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "website_url": {
                "type": "string"
              },
              "canonical_url": {
                "type": "string"
              },
              "verification_token": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "RankingsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "period": {
                "type": "string",
                "example": "all_time"
              },
              "category": {
                "type": "string",
                "example": "all"
              },
              "rankings": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "rank": {
                      "type": "integer"
                    },
                    "category_rank": {
                      "type": "integer"
                    },
                    "score": {
                      "type": "number"
                    },
                    "project": {
                      "$ref": "#/components/schemas/PublicProject"
                    }
                  }
                }
              }
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "TrendingResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "category": {
                "type": "string",
                "example": "all"
              },
              "trending": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "trending_score": {
                      "type": "number"
                    },
                    "overall_rank": {
                      "type": "integer"
                    },
                    "project": {
                      "$ref": "#/components/schemas/PublicProject"
                    }
                  }
                }
              }
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "CategoriesListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "icon": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "what_it_means": {
                  "type": "string"
                },
                "definitions": {
                  "type": "string"
                },
                "faq_count": {
                  "type": "integer"
                },
                "project_count": {
                  "type": "integer"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "CategoryDetailResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "category": {
                "type": "object"
              },
              "projects": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PublicProject"
                }
              }
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "query": {
                "type": "string"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PublicProject"
                }
              }
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "LinkExchangeListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "total_projects": {
                "type": "integer",
                "example": 85
              },
              "total_categories": {
                "type": "integer",
                "example": 12
              },
              "total_verified_shares": {
                "type": "integer",
                "example": 142
              },
              "total_views": {
                "type": "integer",
                "example": 4520
              },
              "total_clicks": {
                "type": "integer",
                "example": 1890
              },
              "last_updated": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "PROJECT_NOT_FOUND"
              },
              "message": {
                "type": "string",
                "example": "Project not found."
              },
              "details": {
                "type": "object",
                "nullable": true
              }
            }
          }
        }
      }
    }
  }
}