{"openapi":"3.1.0","info":{"title":"AtlasRepo Scout REST API","version":"2026-06-24","description":"Scout REST API streams the ranked, activity-scored open-source catalog and published workflow stories into agents, dashboards and CI."},"servers":[{"url":"https://atlasrepo.com","description":"Production"},{"url":"http://localhost:8787","description":"Local development"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"},"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"CatalogRepo":{"type":"object","additionalProperties":true},"Category":{"type":"object","required":["name","description","activeRepoCount"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"activeRepoCount":{"type":"integer","minimum":0}}},"Story":{"type":"object","additionalProperties":true},"Tool":{"type":"object","additionalProperties":true},"AgentSkill":{"type":"object","additionalProperties":true},"AiCompanyConfig":{"type":"object","additionalProperties":true},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"tags":[{"name":"Catalog","description":"Ranked open-source repository catalog"},{"name":"Stories","description":"Published use-case stories and workflows"},{"name":"Tools","description":"Normalized tools referenced by stories"},{"name":"Skills","description":"Curated AI-agent skills with source, license, compatibility and risk metadata"},{"name":"Account","description":"Authenticated account and API key management"}],"paths":{"/api/scout-feed":{"get":{"tags":["Catalog"],"summary":"Public hourly Scout feed preview","description":"Returns the full enriched feed by default. Pass `view=light` for the trimmed landing variant (card + localized descriptions only, without the verbose enrichment fields). Both variants are gzip/Brotli-compressed and support ETag/If-None-Match conditional GET.","security":[],"parameters":[{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["full","light"],"default":"full"},"description":"Feed shape. `light` omits enrichment fields for a smaller payload."}],"responses":{"200":{"description":"Scout feed snapshot"}}}},"/api/categories":{"get":{"tags":["Catalog"],"summary":"List Scout categories","description":"Anonymous endpoint returning AtlasRepo category descriptions and active repository counts.","security":[],"responses":{"200":{"description":"Categories with active repository counts","content":{"application/json":{"schema":{"type":"object","required":["items","totalActiveRepos","source"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"totalActiveRepos":{"type":"integer","minimum":0},"source":{"type":"string","enum":["postgres","file"]}}}}}}}}},"/api/catalog/top":{"get":{"tags":["Catalog"],"summary":"Public top catalog preview","security":[],"parameters":[{"name":"niche","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":100}}],"responses":{"200":{"description":"Top catalog repositories"}}}},"/api/catalog/search":{"get":{"tags":["Catalog"],"summary":"Search the full Scout catalog","description":"Requires a paid API key or active paid session. Free accounts do not receive API access.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Keyword query"},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"minScore","in":"query","schema":{"type":"number"}},{"name":"minStars","in":"query","schema":{"type":"integer"}},{"name":"dateFrom","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","stars","refreshed_at","discovered_at","updated_at"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Catalog search results"},"402":{"description":"Paid API key required"}}}},"/api/catalog/solve":{"post":{"tags":["Catalog"],"summary":"Solve a task against the Scout catalog","description":"Requires a paid API key or active paid session. Uses semantic embeddings when an embedding provider is configured, then falls back to Postgres full-text keyword ranking when keys or local embedding providers are unavailable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"string","description":"Natural-language task or problem statement"},"limit":{"type":"integer","default":10,"maximum":100},"filters":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string"},"language":{"type":"string"},"minScore":{"type":"number"},"minStars":{"type":"integer"},"source":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Catalog matches with whyItFits reasons. Response includes matchMode=semantic or matchMode=keyword."},"402":{"description":"Paid API key required"},"503":{"description":"Database is not configured"}}}},"/api/stories":{"get":{"tags":["Stories"],"summary":"Search published stories","description":"Anonymous/free access returns public stories. Paid keys may request paid/private visibility.","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"dateFrom","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Story search results"}}}},"/api/stories/{slug}":{"get":{"tags":["Stories"],"summary":"Get one story by slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Story detail"},"404":{"description":"Not found"}}}},"/api/repos/{owner}/{name}":{"get":{"tags":["Catalog"],"summary":"Get one repository with linked stories","parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Repository detail"},"404":{"description":"Not found"}}}},"/api/tools":{"get":{"tags":["Tools"],"summary":"Search normalized tools","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"type":"string"}},{"name":"minQuality","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Tools"}}}},"/api/skills":{"get":{"tags":["Skills"],"summary":"Public curated AI-agent skills catalog","description":"Curated-first allowlisted catalog for agent skills. Items include source attribution, license, compatibility, install steps, risk level, score, last verification date and update cadence. Public callers receive the curated catalog; paid API keys can access the persisted full catalog.","security":[],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"agent","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"risk","in":"query","schema":{"type":"string","enum":["low","medium","high"]}},{"name":"minScore","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Skills catalog"}}}},"/api/skills/{slug}":{"get":{"tags":["Skills"],"summary":"Public curated AI-agent skill detail","description":"Returns one published/curated skill card by slug. Public callers can access curated details; paid API keys can access published persisted catalog details.","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill detail"},"404":{"description":"Skill not found"}}}},"/api/ai-companies":{"get":{"tags":["AI Companies"],"summary":"Public curated ready-made AI-company/team configs catalog","description":"Curated templates for AI-company/team configurations. Items include roles, agents, skills, runtime assumptions, env requirements, safety notes, setup steps and manual import/export instructions. No template contains secrets or performs unsafe auto-import.","security":[],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"skill","in":"query","schema":{"type":"string"}},{"name":"agent","in":"query","schema":{"type":"string"}},{"name":"risk","in":"query","schema":{"type":"string","enum":["low","medium","high"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"AI companies catalog"}}}},"/api/tags":{"get":{"tags":["Stories"],"summary":"List public story tags","security":[],"responses":{"200":{"description":"Tags"}}}},"/api/recommendations":{"post":{"tags":["Stories"],"summary":"Recommend stories for a problem statement","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"integer"}}}}}},"responses":{"200":{"description":"Recommended stories"}}}},"/api/account/submissions":{"get":{"tags":["Account"],"summary":"List current user's repo/story submissions","responses":{"200":{"description":"Submissions"},"401":{"description":"Auth required"}}},"post":{"tags":["Account"],"summary":"Submit a repo or story for admin review","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","title","summary"],"properties":{"kind":{"type":"string","enum":["repo","story"]},"title":{"type":"string"},"url":{"type":"string"},"summary":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Submission created"}}}},"/api/account/api-key":{"get":{"tags":["Account"],"summary":"List API keys","description":"Free accounts can view this endpoint but cannot create API keys."},"post":{"tags":["Account"],"summary":"Create a paid API key","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"expiresInDays":{"type":["integer","null"],"description":"30, 90, 365, or null for no expiry"},"expiresAt":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"201":{"description":"API key created"},"402":{"description":"Paid subscription required"}}}},"/api/account/api-key/{id}":{"delete":{"tags":["Account"],"summary":"Revoke one API key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key revoked"},"404":{"description":"Key not found"}}}},"/api/account/api-key/{id}/reissue":{"post":{"tags":["Account"],"summary":"Reissue one API key","description":"Revokes the old key and returns a new one-time token.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"New API key created"},"404":{"description":"Key not found"}}}}}}