{
  "openapi": "3.1.0",
  "info": {
    "title": "LFX Insights Public API",
    "description": "Public read-only endpoints that LF web properties can use to embed LFX Insights\nproject stats without requiring authentication.\n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://insights.linuxfoundation.org",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/project/{slug}/insights": {
      "get": {
        "summary": "Get project insights",
        "description": "Returns a snapshot of key health and activity metrics for a given project.\n\nThis endpoint is public and requires no authentication.\n\nRate limiting applies (default: 200 requests per 60 seconds per IP address).\nRate limit status is returned in the `X-RateLimit-Limit`, `X-RateLimit-Remaining`,\nand `X-RateLimit-Reset` response headers.\n",
        "operationId": "getProjectInsight",
        "tags": [
          "Projects"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The project slug. Matches the slug used in the LFX Insights URL —\ne.g. `k8s` in `https://insights.linuxfoundation.org/projects/k8s`.\n",
            "schema": {
              "type": "string",
              "example": "k8s"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Project insights snapshot",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Maximum number of requests allowed per window",
                "schema": {
                  "type": "integer",
                  "example": 200
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Number of requests remaining in the current window",
                "schema": {
                  "type": "integer",
                  "example": 199
                }
              },
              "X-RateLimit-Reset": {
                "description": "Seconds until the rate limit window resets",
                "schema": {
                  "type": "integer",
                  "example": 42
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectInsight"
                },
                "example": {
                  "id": "abc123",
                  "type": "project",
                  "name": "Kubernetes",
                  "slug": "k8s",
                  "logoUrl": "https://cdn.cncf.io/logos/kubernetes.svg",
                  "repoUrl": "https://github.com/kubernetes/kubernetes",
                  "isLF": true,
                  "status": "active",
                  "maturity": "graduated",
                  "healthScore": 87,
                  "healthLabel": "excellent",
                  "contributorHealthScore": 90,
                  "popularityHealthScore": 95,
                  "developmentHealthScore": 80,
                  "securityHealthScore": 85,
                  "contributorCount": 12345,
                  "organizationCount": 456,
                  "softwareValue": 987654321,
                  "contributorDependencyCount": 3,
                  "contributorDependencyPercentage": 12.5,
                  "organizationDependencyCount": 2,
                  "organizationDependencyPercentage": 8.3,
                  "firstCommit": "2014-06-06T00:00:00.000Z",
                  "starsLast365Days": 5200,
                  "forksLast365Days": 1800,
                  "activeContributorsLast365Days": 340,
                  "activeOrganizationsLast365Days": 78,
                  "starsPrevious365Days": 4900,
                  "forksPrevious365Days": 1600,
                  "activeContributorsPrevious365Days": 310,
                  "activeOrganizationsPrevious365Days": 71,
                  "achievements": [
                    {
                      "leaderboardType": "contributors",
                      "rank": 1,
                      "totalCount": 500
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "Project slug is required"
                }
              }
            }
          },
          "404": {
            "description": "No project found for the given slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "Project not found"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "Too Many Requests",
                  "message": "Rate limit exceeded. Please wait 42 seconds before trying again."
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 500,
                  "statusMessage": "Failed to fetch project insights"
                }
              }
            }
          }
        }
      }
    },
    "/api/project": {
      "get": {
        "summary": "List projects",
        "description": "Returns a page of projects. Only the parameters and fields used to look up projects in batch by slug are documented here.\n\nThis endpoint is public and requires no authentication. Rate limiting applies (default: 200 requests per 60 seconds per IP address).\nRate limit status is returned in the `X-RateLimit-Limit`, `X-RateLimit-Remaining`,\nand `X-RateLimit-Reset` response headers.\n",
        "operationId": "listProjects",
        "tags": [
          "Projects"
        ],
        "parameters": [
          {
            "name": "slugs",
            "in": "query",
            "required": false,
            "description": "Project slugs to return. Repeat the parameter (`slugs=k8s&slugs=korg`) or join the slugs with commas (`slugs=k8s,korg`).\n",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "example": [
                "k8s",
                "korg"
              ]
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "description": "Number of projects per page. Set it to at least the number of slugs to get every slug in one page. At most 100 when `healthBreakdown=true`, so split more than 100 slugs into requests of at most 100 each.\n",
            "schema": {
              "type": "integer",
              "default": 10,
              "example": 50
            }
          },
          {
            "name": "healthBreakdown",
            "in": "query",
            "required": false,
            "description": "When `true`, each project includes its Health Score v2 category scores and `coveredCategoryCount`.\n",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of projects",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Maximum number of requests allowed per window",
                "schema": {
                  "type": "integer",
                  "example": 200
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Number of requests remaining in the current window",
                "schema": {
                  "type": "integer",
                  "example": 199
                }
              },
              "X-RateLimit-Reset": {
                "description": "Seconds until the rate limit window resets",
                "schema": {
                  "type": "integer",
                  "example": 42
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "page": {
                      "type": "integer",
                      "description": "Current page number"
                    },
                    "pageSize": {
                      "type": "integer",
                      "description": "Number of projects per page"
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of matching projects"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProjectListItem"
                      }
                    }
                  }
                },
                "example": {
                  "page": 0,
                  "pageSize": 50,
                  "total": 1,
                  "data": [
                    {
                      "slug": "k8s",
                      "healthScoreV2": 71,
                      "healthMaxScore": 100,
                      "healthLabel": "healthy",
                      "healthScoreV2Normalized": 71,
                      "maintainerHealthScoreV2": 31,
                      "securitySupplyChainScoreV2": 25,
                      "developmentActivityScoreV2": 15,
                      "coveredCategoryCount": 3
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`pageSize` is over 100 while `healthBreakdown=true`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "pageSize must be at most 100 when healthBreakdown=true"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "Too Many Requests",
                  "message": "Rate limit exceeded. Please wait 42 seconds before trying again."
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 500,
                  "statusMessage": "Internal Server Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProjectInsight": {
        "type": "object",
        "required": [
          "id",
          "type",
          "name",
          "slug",
          "logoUrl",
          "repoUrl",
          "isLF",
          "status",
          "healthScore",
          "contributorHealthScore",
          "popularityHealthScore",
          "developmentHealthScore",
          "securityHealthScore",
          "contributorCount",
          "organizationCount",
          "softwareValue",
          "contributorDependencyCount",
          "contributorDependencyPercentage",
          "organizationDependencyCount",
          "organizationDependencyPercentage",
          "firstCommit",
          "starsLast365Days",
          "forksLast365Days",
          "activeContributorsLast365Days",
          "activeOrganizationsLast365Days",
          "starsPrevious365Days",
          "forksPrevious365Days",
          "activeContributorsPrevious365Days",
          "activeOrganizationsPrevious365Days",
          "achievements"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Internal project identifier"
          },
          "type": {
            "type": "string",
            "enum": [
              "project",
              "repo"
            ],
            "description": "Whether this entry represents a full project or a single repository"
          },
          "name": {
            "type": "string",
            "description": "Display name of the project"
          },
          "slug": {
            "type": "string",
            "description": "URL slug used to identify the project"
          },
          "logoUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL of the project logo"
          },
          "repoUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL of the primary repository"
          },
          "isLF": {
            "type": "boolean",
            "description": "Whether the project is hosted by The Linux Foundation"
          },
          "status": {
            "type": "string",
            "description": "Project status (e.g. active, archived)",
            "example": "active"
          },
          "maturity": {
            "type": "string",
            "description": "Maturity level (e.g. sandbox, incubating, graduated). May be absent for non-foundation projects.",
            "example": "graduated"
          },
          "healthScore": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Overall health score"
          },
          "healthLabel": {
            "type": "string",
            "nullable": true,
            "enum": [
              "excellent",
              "healthy",
              "fair",
              "concerning",
              "critical",
              null
            ],
            "description": "Qualitative band for healthScore. Null if not yet computed for this project."
          },
          "contributorHealthScore": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Health score sub-dimension — contributor activity"
          },
          "popularityHealthScore": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Health score sub-dimension — popularity signals"
          },
          "developmentHealthScore": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Health score sub-dimension — development activity"
          },
          "securityHealthScore": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Health score sub-dimension — security posture"
          },
          "contributorCount": {
            "type": "integer",
            "description": "Total number of contributors, all time"
          },
          "organizationCount": {
            "type": "integer",
            "description": "Total number of contributing organizations, all time"
          },
          "softwareValue": {
            "type": "integer",
            "description": "Estimated value of the project's software in USD (COCOMO model)"
          },
          "contributorDependencyCount": {
            "type": "integer",
            "description": "Number of contributors that account for a disproportionate share of commits"
          },
          "contributorDependencyPercentage": {
            "type": "number",
            "description": "Percentage of commits attributed to those contributors"
          },
          "organizationDependencyCount": {
            "type": "integer",
            "description": "Number of organizations that account for a disproportionate share of commits"
          },
          "organizationDependencyPercentage": {
            "type": "number",
            "description": "Percentage of commits attributed to those organizations"
          },
          "firstCommit": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 date of the earliest recorded commit"
          },
          "starsLast365Days": {
            "type": "integer",
            "description": "GitHub stars gained in the last 365 days"
          },
          "forksLast365Days": {
            "type": "integer",
            "description": "GitHub forks gained in the last 365 days"
          },
          "activeContributorsLast365Days": {
            "type": "integer",
            "description": "Unique contributors active in the last 365 days"
          },
          "activeOrganizationsLast365Days": {
            "type": "integer",
            "description": "Unique contributing organizations active in the last 365 days"
          },
          "starsPrevious365Days": {
            "type": "integer",
            "description": "GitHub stars gained in the 365-day period prior to the last 365 days"
          },
          "forksPrevious365Days": {
            "type": "integer",
            "description": "GitHub forks gained in the 365-day period prior to the last 365 days"
          },
          "activeContributorsPrevious365Days": {
            "type": "integer",
            "description": "Unique contributors active in the prior 365-day period"
          },
          "activeOrganizationsPrevious365Days": {
            "type": "integer",
            "description": "Unique contributing organizations active in the prior 365-day period"
          },
          "achievements": {
            "type": "array",
            "description": "List of leaderboard rankings earned by the project (may be empty)",
            "items": {
              "$ref": "#/components/schemas/Achievement"
            }
          }
        }
      },
      "Achievement": {
        "type": "object",
        "required": [
          "leaderboardType",
          "rank",
          "totalCount"
        ],
        "properties": {
          "leaderboardType": {
            "type": "string",
            "description": "The leaderboard category (e.g. contributors, stars)"
          },
          "rank": {
            "type": "integer",
            "description": "The project's rank in that leaderboard"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of projects in that leaderboard"
          }
        }
      },
      "ProjectListItem": {
        "type": "object",
        "description": "A project in the list. Other project fields are returned but not documented here.",
        "required": [
          "slug",
          "healthScoreV2",
          "healthMaxScore",
          "healthLabel",
          "healthScoreV2Normalized"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "description": "URL slug used to identify the project"
          },
          "healthScoreV2": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 100,
            "description": "Overall Health Score v2, in points out of `healthMaxScore`. Always returned. Null when the project is unscored (fewer than 2 categories covered), archived, or one of a few special projects (e.g. the Linux kernel)."
          },
          "healthMaxScore": {
            "type": "integer",
            "nullable": true,
            "enum": [
              100,
              75,
              65,
              60,
              null
            ],
            "description": "Points available for `healthScoreV2`: 100 when all 3 categories are covered, or 60, 65 or 75 when Maintainer Health, Security & Supply Chain or Development Activity is missing. Always returned. Null whenever `healthScoreV2` is null."
          },
          "healthLabel": {
            "type": "string",
            "nullable": true,
            "enum": [
              "excellent",
              "healthy",
              "fair",
              "concerning",
              "critical",
              null
            ],
            "description": "Band of `healthScoreV2Normalized`. Use it for display instead of grading the raw `healthScoreV2`. Always returned. Null whenever `healthScoreV2` is null."
          },
          "healthScoreV2Normalized": {
            "type": "number",
            "nullable": true,
            "minimum": 0,
            "maximum": 100,
            "description": "`healthScoreV2 * 100 / healthMaxScore` on a 0-100 scale, for sorting and comparing partial and full scores. Always returned. Null whenever `healthScoreV2` is null."
          },
          "maintainerHealthScoreV2": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 40,
            "description": "Health Score v2 Maintainer Health category score. Returned when `healthBreakdown=true`. Null when the project has no value for this category."
          },
          "securitySupplyChainScoreV2": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 35,
            "description": "Health Score v2 Security & Supply Chain category score. Returned when `healthBreakdown=true`. Null when the project has no value for this category."
          },
          "developmentActivityScoreV2": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 25,
            "description": "Health Score v2 Development Activity category score. Returned when `healthBreakdown=true`. Null when the project has no value for this category."
          },
          "coveredCategoryCount": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 3,
            "description": "Number of the 3 Health Score v2 categories that have a score. Returned when `healthBreakdown=true`. Null when the count is not available, including for archived projects and a few special projects (e.g. the Linux kernel), which can still have category scores. Treat a null `healthScoreV2` or `healthLabel` as unscored instead of inferring it from the category scores."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer"
          },
          "statusMessage": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}