{"openapi":"3.1.0","info":{"title":"Apira API","version":"0.0.1","description":"Semantic search API for GitHub repositories. Built for AI agents. In the API reference, Models are OpenAPI request and response schemas, not machine-learning models."},"servers":[{"url":"/","description":"Current server"}],"tags":[{"name":"GitHub Search","description":"Search indexed GitHub repositories by natural-language implementation intent."},{"name":"Health","description":"Operational health for the API and backing services."}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"services":{"type":"object","properties":{"db":{"$ref":"#/components/schemas/ServiceHealth"},"redis":{"$ref":"#/components/schemas/ServiceHealth"}},"required":["db","redis"]},"version":{"type":"string"},"uptime":{"type":"number"}},"required":["status","services","version","uptime"]},"ServiceHealth":{"type":"object","properties":{"status":{"type":"string","enum":["up","down"]},"latencyMs":{"type":"number"},"error":{"type":"string"}},"required":["status","latencyMs"]},"GitHubSearchResponse":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/GitHubSearchResponseResult"}},"meta":{"$ref":"#/components/schemas/GitHubSearchResponseMeta"}},"required":["query","results","meta"]},"GitHubSearchResponseResult":{"type":"object","properties":{"url":{"type":["string","null"]},"name":{"type":"string"},"description":{"type":["string","null"]},"score":{"type":"number"},"language":{"type":["string","null"]},"stars":{"type":["number","null"]},"forks":{"type":["number","null"]},"topics":{"type":"array","items":{"type":"string"}},"pushedAt":{"type":["string","null"]},"isArchived":{"type":["boolean","null"],"description":"Whether the repo is archived on GitHub. null means we have not yet captured the archived flag for this row (pre-backfill)."},"llmsUrl":{"type":["string","null"]},"tree":{"type":["string","null"]},"evidence":{"type":"array","items":{"type":"string"}}},"required":["url","name","description","score","language","stars","forks","topics","pushedAt","isArchived","llmsUrl","evidence"]},"GitHubSearchResponseMeta":{"type":"object","properties":{"total":{"type":"number"},"timeMs":{"type":"number"},"methods":{"type":"object","additionalProperties":{"type":"object","properties":{"hits":{"type":"number"},"weight":{"type":"number"}},"required":["hits","weight"]}},"appliedFilters":{"$ref":"#/components/schemas/GitHubSearchAppliedFilters"},"reranked":{"type":"boolean","description":"Present when the reranker stage ran. True if it contributed to ordering; false if it ran and fell back."},"rerankMs":{"type":"number","description":"Wall-time of the reranker call in ms. Absent when the reranker didn't run."}},"required":["total","timeMs","methods","appliedFilters"]},"GitHubSearchAppliedFilters":{"type":"object","properties":{"categories":{"type":"object","properties":{"mode":{"type":"string","enum":["default","explicit","all"],"description":"default = omitted categories used the production default allowlist; explicit = caller supplied one or more categories; all = caller supplied categories: [] to disable category filtering."},"values":{"type":"array","items":{"type":"string","enum":["library","framework","tool","application","infrastructure","ai-ml","agent","frontend","data","starter","curated-list","educational","plugin"]},"description":"Effective category values for default/explicit modes; empty for all mode."},"includeUncategorized":{"type":"boolean","description":"Whether repositories without classified category metadata are included by the effective category filter."}},"required":["mode","values","includeUncategorized"]},"excludeArchived":{"type":"boolean"},"minStars":{"type":["number","null"]},"maxStars":{"type":["number","null"]},"minForks":{"type":["number","null"]},"maxForks":{"type":["number","null"]},"language":{"type":["string","null"]},"excludeRepos":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"staleAfterMonths":{"type":["number","null"]}},"required":["categories","excludeArchived","minStars","maxStars","minForks","maxForks","language","excludeRepos","topics","staleAfterMonths"],"description":"Effective filter values applied to this search after request defaults and route defaults."},"ErrorResponseBody":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"]},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"number"},"details":{"type":"array","items":{}}},"required":["code","message","status"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["Health"],"operationId":"getHealth","summary":"Health check","description":"Returns the health status of the API and its backing services (database, Redis).","security":[],"responses":{"200":{"description":"Service is healthy or degraded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Service is unhealthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/github/search":{"post":{"tags":["GitHub Search"],"operationId":"searchGitHubRepositories","summary":"Search GitHub repositories","description":"Semantic search across indexed GitHub repositories. Returns ranked results with relevance scores and evidence snippets. Educational and curated-list repos are excluded by default. Use filters for hard constraints such as language, categories, topics, stars, forks, archived status, freshness, and repositories already reviewed.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500,"description":"Natural-language description of the implementation pattern, architecture, library capability, or repository type to discover."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Number of ranked repositories to return. Defaults to 10; use 5-10 for focused searches and more when comparing alternatives."},"includeTree":{"type":"boolean","default":false,"description":"When true, include a compact repository file tree for each result. Use this before cloning or deeper inspection."},"filters":{"type":"object","properties":{"minStars":{"type":"integer","minimum":0,"description":"Only return repositories with at least this many GitHub stars."},"maxStars":{"type":"integer","minimum":0,"description":"Only return repositories with at most this many GitHub stars. Combine with minStars for a maturity band."},"minForks":{"type":"integer","minimum":0,"description":"Only return repositories with at least this many forks."},"maxForks":{"type":"integer","minimum":0,"description":"Only return repositories with at most this many forks."},"language":{"type":"string","minLength":1,"maxLength":100,"description":"Exact GitHub primary language match, case-insensitive."},"excludeRepos":{"type":"array","items":{"type":"string","pattern":"^[^/\\s]+\\/[^/\\s]+$"},"maxItems":50,"description":"Repositories to omit from results, formatted as owner/repo. Use after reviewing candidates."},"categories":{"type":"array","items":{"type":"string","enum":["library","framework","tool","application","infrastructure","ai-ml","agent","frontend","data","starter","curated-list","educational","plugin"]},"description":"Repository category allow-list. Omit for the default implementation-focused allow-list, pass [] to disable category filtering, or pass explicit categories such as library, framework, tool, agent, or infrastructure."},"topics":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"GitHub topics that must match at least one repository topic."},"excludeArchived":{"type":"boolean","default":true,"description":"When true (the default) archived GitHub repos are excluded from results. Pass false to include them."},"staleAfterMonths":{"type":"integer","exclusiveMinimum":0,"maximum":600,"description":"Exclude repos not pushed within the last N months. Choose per query intent: 18 for production-ready libraries, 6-12 for fast-moving tools, 36-60 for legacy or historical surveys. Omit for no freshness cutoff."}},"default":{"excludeArchived":true}}},"required":["query"],"additionalProperties":false},"examples":{"agentHarness":{"summary":"Find coding agent harnesses","value":{"query":"minimal terminal coding agent harness","limit":10,"filters":{"language":"typescript","categories":["agent"],"minStars":5000,"excludeArchived":true,"staleAfterMonths":12}}}}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubSearchResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"403":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}}}}}},"webhooks":{}}