{"tags":[{"name":"Analysis","description":"Core analysis endpoints for evaluating OSS repository risk and agentic classification"},{"name":"Cache","description":"Cache management for distributable/air-gapped deployments"},{"name":"GitHub Trending","description":"GitHub trending repository analysis"}],"servers":[{"url":"/","description":"Current host"}],"security":[{"BearerAuth":[]}],"paths":{"/v1/job/{id}":{"get":{"tags":["Analysis"],"summary":"Fetch job by ID","responses":{"404":{"description":"Job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid UUID provided, no job found."}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"200":{"description":"Job report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisReport"}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path","description":"Job UUID"}],"operationId":"getJob","description":"Alias for GET /v1/analyze/:uuid. Retrieves a job by its ID."}},"/v1/gh_trending/process":{"post":{"tags":["GitHub Trending"],"summary":"Trigger GitHub trending analysis","responses":{"403":{"description":"Not an operator token"},"401":{"$ref":"#/components/responses/Unauthorized"},"200":{"description":"Processing started","content":{"application/json":{"schema":{"type":"string","example":"Processing languages..."}}}}},"operationId":"processGhTrending","description":"Parked (#206): this endpoint still answers, but nothing refreshes trending reports, so any report it returns is from before 2026-09-16 or empty. Its upstream ranking (OSS Insight) has been unavailable since 2026-03-01. Kicks off a background task to analyze all configured trending languages from GitHub. For each language, fetches the daily trending repositories, optionally filters by repository size, and runs LowEndInsight analysis on the top N repos (configured via LEI_NUM_OF_REPOS, default 10). Results are cached in Redis and viewable via GET /gh_trending/:language. Returns immediately while processing continues in the background. Operator only: requires a JWT signed with the deployment's LEI_JWT_SECRET; API keys are refused with 403.","deprecated":true}},"/v1/cache/stats":{"get":{"tags":["Cache"],"summary":"Get cache statistics","responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"200":{"description":"Cache statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheStats"},"example":{"total_entries":42,"checked_at":"2024-01-01T00:00:00Z","by_ecosystem":{"gitlab":5,"github":35,"bitbucket":2}}}}}},"operationId":"cacheStats","description":"Returns current cache statistics including total entry count and breakdown by ecosystem (e.g., github, gitlab, bitbucket)."}},"/v1/cache/probe":{"post":{"tags":["Cache"],"summary":"Ask whether repositories are already cached","responses":{"503":{"description":"The cache could not be read; no rate is reported"},"422":{"description":"Missing, empty or oversized urls array"},"403":{"description":"The key does not carry the cache scope"},"401":{"$ref":"#/components/responses/Unauthorized"},"200":{"description":"Membership for each URL","content":{"application/json":{"example":{"total":2,"results":{"https://github.com/kitplummer/lowendinsight":true,"https://github.com/elixir-lang/elixir":false},"misses":1,"hits":1}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","maxItems":500,"items":{"type":"string","format":"uri"},"description":"Repository URLs, at most 500."}}},"example":{"urls":["https://github.com/kitplummer/lowendinsight","https://github.com/elixir-lang/elixir"]}}}},"operationId":"cacheProbe","description":"Read-only membership check: does the shared cache already hold a report for each of these repositories? Nothing is cloned, nothing is analysed and no credits are charged, so this can be used to size a job before submitting it. Requires the `cache` scope. If the cache cannot be read the response is 503 rather than a list of misses -- an unreachable cache must not be reported as an empty one."}},"/v1/cache/import":{"post":{"tags":["Cache"],"summary":"Import cache","responses":{"422":{"description":"Missing entries array","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"POST body must contain 'entries' array from cache export"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"200":{"description":"Import completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheImportResponse"},"example":{"success":true,"stats":{"ttl_applied":2592000,"total":7,"skipped":2,"imported_at":"2024-01-01T00:00:00Z","imported":5,"errors":0}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheImportRequest"},"example":{"ttl":2592000,"overwrite":false,"entries":[{"key":"github:kitplummer/clikan:latest","data":{}}]}}}},"operationId":"importCache","description":"Imports pre-warmed cache entries previously exported via GET /v1/cache/export. Useful for bootstrapping air-gapped deployments with known-good analysis data."}},"/v1/cache/export":{"get":{"tags":["Cache"],"summary":"Export cache","responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"200":{"headers":{"Content-Disposition":{"schema":{"type":"string","example":"attachment; filename=\"lei-cache-export.json\""}}},"description":"Cache export as JSON download","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheExport"},"example":{"stats":{"format_version":"1.0","exported_at":"2024-01-01T00:00:00Z","count":1},"entries":[{"ttl_remaining":2592000,"key":"github:kitplummer/clikan:latest","data":{}}]}}}}},"operationId":"exportCache","description":"Exports all cached analysis reports as JSON. Intended for creating distributable cache snapshots for air-gapped deployments. Returns the file as a download attachment."}},"/v1/analyze/{uuid}":{"get":{"tags":["Analysis"],"summary":"Fetch analysis result by UUID","responses":{"404":{"description":"No job found for the given UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid UUID provided, no job found."}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"200":{"description":"Analysis report (complete or refreshed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisReport"}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"uuid","in":"path","description":"UUID returned from POST /v1/analyze"}],"operationId":"getAnalysis","description":"Retrieves a previously submitted analysis job. If the job is incomplete, the server attempts to refresh it from cache before returning."}},"/v1/analyze/sbom":{"post":{"tags":["Analysis"],"summary":"Analyze an SBOM","responses":{"422":{"description":"Invalid SBOM or parse error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parse_error":{"value":{"error":"SBOM parse error: invalid format"}},"no_urls":{"value":{"error":"no git URLs found in SBOM"}},"missing_sbom":{"value":{"error":"POST body must contain 'sbom' field with CycloneDX or SPDX JSON"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"202":{"description":"SBOM analysis timed out (blocking mode)","content":{"application/json":{"schema":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"state":{"type":"string","example":"incomplete"},"sbom_urls_found":{"type":"integer"},"error":{"type":"string"}}}}}},"200":{"description":"SBOM analysis complete","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AnalysisReport"},{"type":"object","properties":{"sbom_urls_found":{"type":"integer","example":5},"sbom_analysis":{"type":"boolean","example":true}}}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SbomRequest"},"examples":{"cyclonedx":{"value":{"sbom":{"specVersion":"1.4","components":[{"type":"library","name":"clikan","externalReferences":[{"url":"https://github.com/kitplummer/clikan","type":"vcs"}]}],"bomFormat":"CycloneDX"}},"summary":"CycloneDX SBOM"},"blocking":{"value":{"sbom":{},"cache_timeout":120000,"cache_mode":"blocking"},"summary":"SBOM with blocking mode"}}}}},"operationId":"analyzeSbom","description":"Accepts a CycloneDX or SPDX JSON SBOM, extracts git repository URLs from it, and runs LowEndInsight analysis on each. Default cache mode is `async`."}},"/v1/analyze":{"post":{"tags":["Analysis"],"summary":"Submit URLs for analysis","responses":{"422":{"description":"Invalid request body or invalid URLs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"this is a POSTful service, JSON body with valid git url param required and content-type set to application/json.  e.g. {\"urls\": [\"https://gitrepo/org/repo\"]}"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"202":{"description":"Analysis did not complete within timeout (blocking mode only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncompleteResponse"},"example":{"uuid":"ae88a430-3e1f-11ea-a207-0242ac110007","state":"incomplete","error":"analysis did not complete within 30000ms timeout"}}}},"200":{"description":"Analysis complete (blocking/stale with all cached) or async job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisReport"},"example":{"uuid":"ae88a430-3e1f-11ea-a207-0242ac110007","state":"complete","report":{"uuid":"aec93c7a-3e1f-11ea-8579-0242ac110007","repos":[{"header":{"uuid":"aec932de-3e1f-11ea-9ac3-0242ac110007","start_time":"2020-01-23T20:33:58.137963Z","source_client":"lei-get","library_version":"0.3.1","end_time":"2020-01-23T20:33:58.554693Z","duration":0},"data":{"risk":"critical","results":{"restricted_contributors":null,"recent_commit_size_in_percent_of_codebase":0.08,"large_recent_commit_risk":"medium","functional_contributors_risk":"critical","functional_contributors":1,"contributor_risk":"high","contributor_count":2,"commit_currency_weeks":51,"commit_currency_risk":"medium","agentic_contribution_ratio":0.0,"agentic_classification":"human"},"repo":"https://github.com/kitplummer/clikan","config":{}}}]},"metadata":{"times":{"start_time":"2020-01-23T20:33:58.131642Z","end_time":"2020-01-23T20:33:58.555362Z","duration":0},"risk_counts":{"critical":1},"repo_count":1,"cache_status":{"per_repo":["miss"],"misses":1,"hits":0}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeRequest"},"examples":{"stale":{"value":{"urls":["https://github.com/kitplummer/clikan"],"cache_mode":"stale"},"summary":"Accept stale cached data"},"blocking":{"value":{"urls":["https://github.com/kitplummer/clikan"],"cache_timeout":60000,"cache_mode":"blocking"},"summary":"Blocking mode with timeout"},"basic":{"value":{"urls":["https://github.com/kitplummer/clikan","https://github.com/kitplummer/xmpp4rails"]},"summary":"Analyze two repos (async)"}}}}},"operationId":"analyzeUrls","description":"Accepts a list of git repository URLs and returns an analysis report. Supports three cache modes: `blocking` (waits for completion), `async` (returns immediately with a job UUID to poll), and `stale` (returns stale cached data if available while refreshing in the background)."}},"/gh_trending/{language}":{"get":{"tags":["GitHub Trending"],"summary":"Get trending report for a language","security":[],"responses":{"200":{"description":"HTML page with trending analysis report for the language","content":{"text/html":{"schema":{"type":"string"}}}}},"parameters":[{"schema":{"type":"string"},"required":true,"name":"language","in":"path","examples":{"rust":{"value":"rust"},"python":{"value":"python"},"elixir":{"value":"elixir"}},"description":"Programming language to get trending analysis for (e.g. elixir, python, rust)"}],"operationId":"getGhTrendingByLanguage","description":"Parked (#206): this endpoint still answers, but nothing refreshes trending reports, so any report it returns is from before 2026-09-16 or empty. Its upstream ranking (OSS Insight) has been unavailable since 2026-03-01. Returns an HTML page displaying the LowEndInsight analysis report for trending GitHub repositories in the specified language. Results come from the most recent analysis run triggered via POST /v1/gh_trending/process. If no analysis has been run yet, an empty report is shown.","deprecated":true}},"/gh_trending":{"get":{"tags":["GitHub Trending"],"summary":"List configured trending languages","security":[],"responses":{"200":{"description":"HTML page listing available languages","content":{"text/html":{"schema":{"type":"string"}}}}},"operationId":"listGhTrendingLanguages","description":"Parked (#206): this endpoint still answers, but nothing refreshes trending reports, so any report it returns is from before 2026-09-16 or empty. Its upstream ranking (OSS Insight) has been unavailable since 2026-03-01. Returns an HTML page listing all configured programming languages that can be analyzed for GitHub trending repositories. Each language links to its trending analysis report.","deprecated":true}}},"openapi":"3.0.3","info":{"version":"0.16.0-beta.2","title":"LowEndInsight API","license":{"url":"https://opensource.org/licenses/BSD-3-Clause","name":"BSD 3-Clause"},"description":"Beta (0.16.0-beta.2): paths and fields may change before 1.0. OSS risk (bus-factor) analysis service. Analyzes git repositories for contributor risk, commit currency, agentic classification, and other supply-chain risk indicators."},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"JWT token using HS256. All /v1/* endpoints require authentication. Pass as `Authorization: Bearer <token>`.","bearerFormat":"JWT"}},"schemas":{"SbomRequest":{"type":"object","required":["sbom"],"properties":{"sbom":{"type":"object","description":"CycloneDX or SPDX JSON SBOM object. Git repository URLs are extracted from component external references."},"cache_timeout":{"type":"integer","description":"Timeout in milliseconds for blocking mode","default":60000},"cache_mode":{"type":"string","enum":["blocking","async","stale"],"description":"Cache mode (defaults to async for SBOMs due to potentially large number of repos)","default":"async"}}},"RiskConfig":{"type":"object","properties":{"medium_large_commit_level":{"type":"number"},"medium_functional_contributors_level":{"type":"integer"},"medium_currency_level":{"type":"integer"},"medium_contributor_level":{"type":"integer"},"high_large_commit_level":{"type":"number"},"high_functional_contributors_level":{"type":"integer"},"high_currency_level":{"type":"integer"},"high_contributor_level":{"type":"integer"},"critical_large_commit_level":{"type":"number"},"critical_functional_contributors_level":{"type":"integer"},"critical_currency_level":{"type":"integer"},"critical_contributor_level":{"type":"integer"}},"description":"Risk threshold configuration used for this analysis"},"Report":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"repos":{"type":"array","items":{"$ref":"#/components/schemas/RepoReport"}}}},"RepoResults":{"type":"object","properties":{"restricted_contributors":{"type":"boolean","nullable":true,"description":"Whether any contributors have restricted GitHub profiles. Null when no GitHub token is configured; true/false when the GitHub API is available."},"recent_commit_size_in_percent_of_codebase":{"type":"number","format":"float","description":"Most recent commit size as a fraction of the total codebase"},"large_recent_commit_risk":{"type":"string","enum":["critical","high","medium","low"],"description":"Risk based on size of recent commits relative to codebase"},"functional_contributors_risk":{"type":"string","enum":["critical","high","medium","low"],"description":"Risk based on concentration of contributions"},"functional_contributors":{"type":"integer","description":"Number of contributors making substantive contributions"},"functional_contributor_names":{"type":"array","items":{"type":"string"},"description":"Names of contributors making the bulk of contributions"},"contributor_risk":{"type":"string","enum":["critical","high","medium","low"],"description":"Risk based on contributor count"},"contributor_count":{"type":"integer","description":"Total number of unique contributors"},"commit_currency_weeks":{"type":"integer","description":"Weeks since last commit"},"commit_currency_risk":{"type":"string","enum":["critical","high","medium","low"],"description":"Risk based on how recently the repo was committed to"},"agentic_contribution_ratio":{"type":"number","minimum":0.0,"maximum":1.0,"format":"float","description":"Ratio of agentic (bot/AI) commits to total commits, ranging from 0.0 (fully human) to 1.0 (fully agentic)"},"agentic_classification":{"type":"string","enum":["human","mixed","agent"],"description":"Repository-level agentic classification based on the ratio of bot/AI commits. 'human' = ratio < 0.3, 'mixed' = ratio >= 0.3 and <= 0.7, 'agent' = ratio > 0.7"}}},"RepoReport":{"type":"object","properties":{"header":{"$ref":"#/components/schemas/RepoHeader"},"data":{"$ref":"#/components/schemas/RepoData"}}},"RepoHeader":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"start_time":{"type":"string","format":"date-time"},"source_client":{"type":"string","description":"Client identifier (e.g. lei-get)"},"library_version":{"type":"string","description":"LowEndInsight library version"},"end_time":{"type":"string","format":"date-time"},"duration":{"type":"integer","description":"Analysis duration in seconds"}}},"RepoData":{"type":"object","properties":{"risk":{"type":"string","enum":["critical","high","medium","low"],"description":"Overall risk level for this repo"},"results":{"$ref":"#/components/schemas/RepoResults"},"repo":{"type":"string","format":"uri","description":"The analyzed repository URL"},"project_types":{"type":"object","description":"Detected project types and their indicator files","additionalProperties":{"type":"array","items":{"type":"string"}}},"config":{"$ref":"#/components/schemas/RiskConfig"}}},"Metadata":{"type":"object","properties":{"times":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time"},"duration":{"type":"integer","description":"Total duration in seconds"}}},"risk_counts":{"type":"object","properties":{"medium":{"type":"integer"},"low":{"type":"integer"},"high":{"type":"integer"},"critical":{"type":"integer"}},"description":"Count of repos at each risk level"},"repo_count":{"type":"integer"},"cache_status":{"type":"object","properties":{"per_repo":{"type":"array","items":{"type":"string","enum":["hit","miss","stale"]}},"misses":{"type":"integer"},"hits":{"type":"integer"}},"description":"Cache performance for this request"}}},"IncompleteResponse":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Poll GET /v1/analyze/{uuid} for the completed result"},"state":{"type":"string","enum":["incomplete"]},"error":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}},"CacheStats":{"type":"object","properties":{"total_entries":{"type":"integer"},"checked_at":{"type":"string","format":"date-time"},"by_ecosystem":{"type":"object","example":{"gitlab":5,"github":35},"additionalProperties":{"type":"integer"}}}},"CacheImportResponse":{"type":"object","properties":{"success":{"type":"boolean"},"stats":{"type":"object","properties":{"ttl_applied":{"type":"integer"},"total":{"type":"integer"},"skipped":{"type":"integer"},"imported_at":{"type":"string","format":"date-time"},"imported":{"type":"integer"},"errors":{"type":"integer"}}}}},"CacheImportRequest":{"type":"object","required":["entries"],"properties":{"ttl":{"type":"integer","description":"TTL in seconds for imported entries. Defaults to the server's configured cache_ttl_seconds."},"overwrite":{"type":"boolean","description":"If true, overwrite existing cache entries","default":false},"entries":{"type":"array","items":{"$ref":"#/components/schemas/CacheEntry"}}}},"CacheExport":{"type":"object","properties":{"stats":{"type":"object","properties":{"format_version":{"type":"string"},"exported_at":{"type":"string","format":"date-time"},"count":{"type":"integer"}}},"entries":{"type":"array","items":{"$ref":"#/components/schemas/CacheEntry"}}}},"CacheEntry":{"type":"object","properties":{"ttl_remaining":{"type":"integer","description":"Seconds remaining before this entry expires"},"key":{"type":"string","example":"github:kitplummer/clikan:latest","description":"Cache key in format ecosystem:package:version"},"data":{"type":"object","description":"The cached analysis report"}}},"AnalyzeRequest":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string","format":"uri"},"example":["https://github.com/kitplummer/clikan"],"description":"List of git repository URLs to analyze"},"cache_timeout":{"type":"integer","description":"Timeout in milliseconds for blocking mode. Analysis that exceeds this returns 202 with a UUID to poll later.","default":30000},"cache_mode":{"type":"string","enum":["blocking","async","stale"],"description":"`blocking` waits for results (up to cache_timeout). `async` returns immediately with a UUID to poll. `stale` returns stale cache if available and refreshes in background.","default":"blocking"}}},"AnalysisReport":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Job UUID for polling"},"state":{"type":"string","enum":["complete","incomplete"],"description":"Whether all repos have been analyzed"},"report":{"$ref":"#/components/schemas/Report"},"metadata":{"$ref":"#/components/schemas/Metadata"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid JWT token","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Please make sure you have authentication header"}}}}}}}}}