{ "openapi": "3.1.0", "info": { "title": "Git Atlas Unified BFF \u2014 PROPOSED", "version": "1.0.0-design", "description": "Design contract only, not implemented. Preserved upstream APIs remain on original hosts and schemas. No server URL is claimed to exist." }, "servers": [ { "url": "http://localhost:3000", "description": "Illustrative future local implementation, not started by this package" } ], "x-status": "PROPOSED_NOT_IMPLEMENTED", "paths": { "/api/v1/repositories": { "get": { "operationId": "catalog_list", "summary": "Filter repository summary read model", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "catalog" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RepositorySummary" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque cursor bound to snapshot and filters." }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tier", "in": "query", "required": false, "schema": { "enum": [ "reviewed", "snapshot", "warehouse" ] } } ] } }, "/api/v1/repositories/{owner}/{repo}": { "get": { "operationId": "catalog_detail", "summary": "Unified detail with per-field provenance", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "catalog" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/RepositoryDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$" } } ] } }, "/api/v1/repositories/{owner}/{repo}/readme": { "get": { "operationId": "catalog_readme", "summary": "Readme service on the new product; not TopGit action wire protocol", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "catalog" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Readme" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$" } } ] } }, "/api/v1/repositories/{owner}/{repo}/history": { "get": { "operationId": "history_snapshot", "summary": "Complete validated cached history; never synchronous full live ingestion", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "history" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/History" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Live mode only: missing snapshot queued; poll same GET with backoff. Snapshot-only mode returns 404, never a fake job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedHistoryJob" } } } } }, "security": [], "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$" } } ] } }, "/api/v1/trending": { "get": { "operationId": "discovery_trending", "summary": "Source snapshot trending, not current-stars sorting", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "discovery" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrendingEntry" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque cursor bound to snapshot and filters." }, { "name": "period", "in": "query", "required": false, "schema": { "enum": [ "daily", "weekly", "monthly" ], "default": "daily" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/v1/rankings/{kind}": { "get": { "operationId": "analytics_rankings", "summary": "Pinned source cohort ranking", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "analytics" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RankingEntry" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "enum": [ "repository", "user", "organization" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque cursor bound to snapshot and filters." } ] } }, "/api/v1/search": { "get": { "operationId": "discovery_search", "summary": "Unified paginated search; distinct from legacy suggest", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "discovery" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RepositorySummary" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque cursor bound to snapshot and filters." } ] } }, "/api/v1/bookmarks/resolve": { "post": { "operationId": "collections_resolve", "summary": "Read-only batch projection, returns only requested items", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "collections" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BookmarkResolution" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "repoKeys" ], "additionalProperties": false, "properties": { "repoKeys": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^[^/\\s]+/[^/\\s]+$" } } } } } } } } }, "/api/v1/comparisons": { "get": { "operationId": "compare_list", "summary": "Curated groups", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "compare" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ComparisonGroup" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/api/v1/comparisons/{slug}": { "get": { "operationId": "compare_detail", "summary": "Category details and metrics with provenance", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "compare" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ComparisonDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/datasets/{key}": { "get": { "operationId": "analytics_dataset", "summary": "Allowlisted published feature dataset", "x-status": "PROPOSED_NOT_IMPLEMENTED", "tags": [ "analytics" ], "responses": { "200": { "description": "Successful proposed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Dataset" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown entity or dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Snapshot/cursor mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "enum": [ "top-ai-coding", "top-committers", "star-race", "star-shapes", "starmap" ] } }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 2024 }, "description": "Only for top-committers. Published years only; absent means current published year, unsupported year returns 404." } ] } }, "/api/v1/capabilities": { "get": { "operationId": "plugin_capabilities", "summary": "Public skill registry (domain skills, intents, API refs, route patterns)", "responses": { "200": { "description": "Capability manifest" } } } }, "/api/v1/entities/resolve": { "post": { "operationId": "plugin_resolve", "summary": "Resolve repositories, accounts, topics and curated comparisons in free text", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Resolved entities" }, "400": { "description": "Invalid query" } } } }, "/api/v1/ask": { "post": { "operationId": "plugin_ask", "summary": "Natural-language gateway: returns an evidence pack (interpretation, evidence with provenance and canonical URLs, warnings)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Evidence pack" }, "400": { "description": "Invalid query" }, "429": { "description": "Rate limited" } } } }, "/api/v1/topics": { "get": { "operationId": "topics_list", "summary": "Topics with repository counts", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/topics/{topic}": { "get": { "operationId": "topic_detail", "summary": "Repositories in a topic", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/users/{login}": { "get": { "operationId": "user_profile", "summary": "User profile", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/organizations/{login}": { "get": { "operationId": "org_profile", "summary": "Organization profile", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/insights/ai-coding": { "get": { "operationId": "insight_ai", "summary": "AI coding activity", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/insights/committers": { "get": { "operationId": "insight_committers", "summary": "Top committers (?year)", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/insights/star-race": { "get": { "operationId": "insight_race", "summary": "Star race (?tier)", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/insights/star-map": { "get": { "operationId": "insight_map", "summary": "Ecosystem star map", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/editorial/blog": { "get": { "operationId": "editorial_blog", "summary": "Blog articles", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/editorial/blog/{slug}": { "get": { "operationId": "editorial_article", "summary": "Blog article", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/editorial/articles": { "get": { "operationId": "editorial_reviews", "summary": "Reviews (availability)", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/editorial/authors/{slug}": { "get": { "operationId": "editorial_author", "summary": "Author profile", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/resources/{key}": { "get": { "operationId": "resource", "summary": "Methodology/policy text", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/recommendations": { "get": { "operationId": "recommendations", "summary": "Similar repositories (?repo, ?maintained)", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found / unavailable" } } } }, "/api/v1/semantic/search": { "post": { "operationId": "semantic_search", "summary": "Vector search over repository descriptions", "responses": { "200": { "description": "OK" } } } }, "/api/v1/collections": { "get": { "operationId": "collections_list", "summary": "List my collections (collections:read)", "responses": { "200": { "description": "OK" }, "401": { "description": "Session cookie or Authorization: Bearer gat_\u2026 (scopes collections:read / collections:write)" } } }, "post": { "operationId": "collections_create", "summary": "Create a collection (collections:write)", "responses": { "201": { "description": "Created" }, "401": { "description": "Session cookie or Authorization: Bearer gat_\u2026 (scopes collections:read / collections:write)" }, "403": { "description": "insufficient_scope" } } } }, "/api/v1/collections/{id}": { "get": { "operationId": "collection_get", "summary": "GET a collection", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found" } } }, "patch": { "operationId": "collection_patch", "summary": "PATCH a collection", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found" } } }, "delete": { "operationId": "collection_delete", "summary": "DELETE a collection", "responses": { "200": { "description": "OK" }, "404": { "description": "Not found" } } } }, "/api/v1/collections/{id}/items": { "post": { "operationId": "collection_add", "summary": "Add a repository (must exist in Git Atlas)", "responses": { "200": { "description": "OK" }, "422": { "description": "unknown_repo" } } } }, "/api/v1/collections/{id}/items/{owner}/{repo}": { "delete": { "operationId": "collection_remove", "summary": "Remove a repository", "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "SourceRef": { "type": "object", "required": [ "source", "asOf" ], "properties": { "source": { "type": "string" }, "asOf": { "type": [ "string", "null" ], "format": "date-time" }, "generationId": { "type": [ "string", "null" ] }, "artifactSha256": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "Meta": { "type": "object", "required": [ "requestId", "snapshotId", "source", "asOf", "completeness", "nextCursor" ], "properties": { "requestId": { "type": "string" }, "snapshotId": { "type": [ "string", "null" ] }, "source": { "type": "array", "items": { "$ref": "#/components/schemas/SourceRef" } }, "asOf": { "type": [ "string", "null" ], "format": "date-time" }, "completeness": { "enum": [ "complete", "partial", "unknown" ] }, "nextCursor": { "type": [ "string", "null" ] } } }, "RepositorySummary": { "type": "object", "required": [ "repoKey", "identityStatus", "availability" ], "properties": { "repoKey": { "type": "string" }, "githubId": { "type": [ "integer", "null" ] }, "displayName": { "type": "string" }, "identityStatus": { "enum": [ "verified", "provisional" ] }, "availability": { "type": "object", "additionalProperties": { "type": "boolean" } }, "stars": { "type": [ "integer", "null" ], "minimum": 0 }, "starsSource": { "$ref": "#/components/schemas/SourceRef" }, "editorialStatus": { "enum": [ "unavailable", "snapshot", "draft", "published", "retracted" ] } } }, "Metric": { "type": "object", "required": [ "key", "value", "unit", "source" ], "properties": { "key": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string" }, "source": { "$ref": "#/components/schemas/SourceRef" }, "windowStart": { "type": [ "string", "null" ] }, "windowEnd": { "type": [ "string", "null" ] }, "cohort": { "type": [ "string", "null" ] }, "quality": { "enum": [ "known", "unknown", "partial", "source_zero_unverified" ] } } }, "RepositoryDetail": { "allOf": [ { "$ref": "#/components/schemas/RepositorySummary" }, { "type": "object", "properties": { "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } }, "review": { "type": [ "object", "null" ], "description": "Only published content if authorized/available; omitted body never fabricated." }, "related": { "type": "array", "items": { "$ref": "#/components/schemas/RepositorySummary" } } } } ] }, "Error": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } } }, "requestId": { "type": "string" } } }, "AcceptedHistoryJob": { "type": "object", "required": [ "jobId", "state", "pollAfterSeconds" ], "properties": { "jobId": { "type": "string" }, "state": { "enum": [ "queued", "running" ] }, "pollAfterSeconds": { "type": "integer", "minimum": 1 } } }, "History": { "type": "object", "required": [ "repository", "complete", "coverage", "records" ], "properties": { "repository": { "type": "string" }, "complete": { "const": true }, "coverage": { "type": "object", "required": [ "from", "to", "snapshotId", "validatorVersion" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "snapshotId": { "type": "string" }, "validatorVersion": { "type": "string" } } }, "records": { "type": "array", "items": { "type": "object", "required": [ "date", "count" ], "properties": { "date": { "type": "string", "format": "date" }, "count": { "type": "integer", "minimum": 0 } } } } } }, "Readme": { "type": "object", "required": [ "markdown", "branch" ], "properties": { "markdown": { "type": "string" }, "branch": { "type": [ "string", "null" ] } } }, "RankingEntry": { "type": "object", "required": [ "entityKey", "rank", "source" ], "properties": { "entityKey": { "type": "string" }, "rank": { "type": "integer", "minimum": 1 }, "starsAtCapture": { "type": [ "integer", "null" ] }, "source": { "$ref": "#/components/schemas/SourceRef" }, "cohort": { "type": "string" } } }, "TrendingEntry": { "type": "object", "required": [ "repoKey", "rank", "period", "source" ], "properties": { "repoKey": { "type": "string" }, "rank": { "type": "integer", "minimum": 1 }, "period": { "enum": [ "daily", "weekly", "monthly" ] }, "language": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/SourceRef" } } }, "ComparisonGroup": { "type": "object", "required": [ "slug", "name", "repositories" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/RepositorySummary" } } } }, "ComparisonDetail": { "type": "object", "required": [ "group", "rows" ], "properties": { "group": { "$ref": "#/components/schemas/ComparisonGroup" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "repoKey", "metrics" ], "properties": { "repoKey": { "type": "string" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } } } } } }, "BookmarkResolution": { "type": "object", "required": [ "items", "missing" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RepositorySummary" } }, "missing": { "type": "array", "items": { "type": "string" } } } }, "Dataset": { "type": "object", "required": [ "key", "generationId", "payload" ], "properties": { "key": { "type": "string" }, "generationId": { "type": "string" }, "payload": { "description": "Versioned factual dataset preserving source shape, not an invented upstream API response." } } } } }, "security": [] }