{"openapi":"3.1.0","info":{"title":"Cairn agent API","version":"1","description":"Agent-first consolidation observatory. Verdict-free: responses state facts as events, never a resolution verdict."},"paths":{"/api/v1/{org}/{repo}/lookup":{"get":{"summary":"Resolve an exact cluster by issue/PR number or URL","parameters":[{"name":"org","in":"path","required":true,"schema":{"type":"string"}},{"name":"repo","in":"path","required":true,"schema":{"type":"string"}},{"name":"issue","in":"query","schema":{"type":"integer"}},{"name":"pr","in":"query","schema":{"type":"integer"}},{"name":"url","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Exact cluster or novel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/search_envelope"}}}},"404":{"description":"unknown repo (not in the served allow-list)","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/{org}/{repo}/search":{"get":{"summary":"Free-text search for related clusters","parameters":[{"name":"org","in":"path","required":true,"schema":{"type":"string"}},{"name":"repo","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Ranked cluster references","content":{"application/json":{"schema":{"$ref":"#/components/schemas/search_envelope"}}}},"404":{"description":"unknown repo (not in the served allow-list)","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/{org}/{repo}/match":{"post":{"summary":"Match a pasted error / stack trace / diff to clusters","parameters":[{"name":"org","in":"path","required":true,"schema":{"type":"string"}},{"name":"repo","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Ranked cluster references + content hash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/match_envelope"}}}},"404":{"description":"unknown repo (not in the served allow-list)","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/{org}/{repo}/cluster/{public_id}.json":{"get":{"summary":"Machine trust contract for one cluster","parameters":[{"name":"org","in":"path","required":true,"schema":{"type":"string"}},{"name":"repo","in":"path","required":true,"schema":{"type":"string"}},{"name":"public_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"set to 'suggested' to include suggested-tier fix detail"}],"responses":{"200":{"description":"The cluster machine trust contract","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cluster_contract"}}}}}}}},"components":{"schemas":{"search_envelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://cairn/schema/search_envelope.json","title":"SearchEnvelope","type":"object","additionalProperties":false,"required":["query","repo","kind","verdict","results"],"properties":{"query":{"type":"string"},"repo":{"type":"string"},"kind":{"enum":["identifier","text"]},"verdict":{"enum":["exact","match","near_miss","novel"]},"results":{"type":"array","items":{"$ref":"#/$defs/cluster_ref"}}},"$defs":{"cluster_ref":{"type":"object","additionalProperties":false,"required":["repo","public_id","display_label","summary","score","member_hits","best_fts","best_wsim","has_fts","best_cov","covers_all","evidence","member_count","open_issue_count","has_merged_fix","merged_fix_pr_number","attempt_pr_count","subsystem","freshness","cluster_url","json_url","md_url"],"properties":{"repo":{"type":"string"},"public_id":{"type":"string"},"display_label":{"type":["string","null"]},"summary":{"type":["string","null"]},"score":{"type":"number"},"member_hits":{"type":"integer"},"best_fts":{"type":"number"},"best_wsim":{"type":"number"},"has_fts":{"type":"boolean"},"best_cov":{"type":"integer"},"covers_all":{"type":"boolean"},"evidence":{"type":"object","additionalProperties":false,"required":["matched_lexemes","matched_member"],"properties":{"matched_lexemes":{"type":"array","items":{"type":"string"}},"matched_member":{"type":["object","null"],"additionalProperties":false,"required":["kind","number","title","url"],"properties":{"kind":{"enum":["issue","pr"]},"number":{"type":"integer"},"title":{"type":["string","null"]},"url":{"type":["string","null"]}}}}},"member_count":{"type":"integer"},"open_issue_count":{"type":"integer"},"has_merged_fix":{"type":"boolean"},"merged_fix_pr_number":{"type":["integer","null"]},"attempt_pr_count":{"type":"integer"},"subsystem":{"type":["string","null"]},"freshness":{"type":"object","additionalProperties":false,"required":["state","last_verified_at","is_stale"],"properties":{"state":{"type":"string","enum":["verified","stale","never_verified"]},"last_verified_at":{"type":["string","null"]},"is_stale":{"type":"boolean"}}},"cluster_url":{"type":"string"},"json_url":{"type":"string"},"md_url":{"type":"string"}}}}},"match_envelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://cairn/schema/match_envelope.json","title":"MatchEnvelope","type":"object","additionalProperties":false,"required":["query","repo","kind","verdict","results","content_hash","cached"],"properties":{"query":{"type":"string"},"repo":{"type":"string"},"kind":{"enum":["identifier","text"]},"verdict":{"enum":["exact","match","near_miss","novel"]},"results":{"type":"array","items":{"$ref":"#/$defs/cluster_ref"}},"content_hash":{"type":"string"},"cached":{"type":"boolean"}},"$defs":{"cluster_ref":{"type":"object","additionalProperties":false,"required":["repo","public_id","display_label","summary","score","member_hits","best_fts","best_wsim","has_fts","best_cov","covers_all","evidence","member_count","open_issue_count","has_merged_fix","merged_fix_pr_number","attempt_pr_count","subsystem","freshness","cluster_url","json_url","md_url"],"properties":{"repo":{"type":"string"},"public_id":{"type":"string"},"display_label":{"type":["string","null"]},"summary":{"type":["string","null"]},"score":{"type":"number"},"member_hits":{"type":"integer"},"best_fts":{"type":"number"},"best_wsim":{"type":"number"},"has_fts":{"type":"boolean"},"best_cov":{"type":"integer"},"covers_all":{"type":"boolean"},"evidence":{"type":"object","additionalProperties":false,"required":["matched_lexemes","matched_member"],"properties":{"matched_lexemes":{"type":"array","items":{"type":"string"}},"matched_member":{"type":["object","null"],"additionalProperties":false,"required":["kind","number","title","url"],"properties":{"kind":{"enum":["issue","pr"]},"number":{"type":"integer"},"title":{"type":["string","null"]},"url":{"type":["string","null"]}}}}},"member_count":{"type":"integer"},"open_issue_count":{"type":"integer"},"has_merged_fix":{"type":"boolean"},"merged_fix_pr_number":{"type":["integer","null"]},"attempt_pr_count":{"type":"integer"},"subsystem":{"type":["string","null"]},"freshness":{"type":"object","additionalProperties":false,"required":["state","last_verified_at","is_stale"],"properties":{"state":{"type":"string","enum":["verified","stale","never_verified"]},"last_verified_at":{"type":["string","null"]},"is_stale":{"type":"boolean"}}},"cluster_url":{"type":"string"},"json_url":{"type":"string"},"md_url":{"type":"string"}}}}},"cluster_contract":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://cairn/schema/cluster_contract.json","title":"ClusterContract","type":"object","additionalProperties":false,"required":["repo","public_id","display_label","summary","subsystem","counts","landed_fix","resolution","freshness","grouping","fix_edges","members","trust"],"properties":{"repo":{"type":"string"},"public_id":{"type":"string"},"display_label":{"type":["string","null"]},"summary":{"type":["string","null"]},"subsystem":{"type":["string","null"]},"counts":{"type":"object","additionalProperties":false,"required":["members","open_issues","closed_issues","merged_prs","attempt_prs"],"properties":{"members":{"type":"integer"},"open_issues":{"type":"integer"},"closed_issues":{"type":"integer"},"merged_prs":{"type":"integer"},"attempt_prs":{"type":"integer"}}},"landed_fix":{"type":["object","null"],"additionalProperties":false,"required":["status","basis"],"properties":{"status":{"const":"merged_to_main"},"basis":{"type":"string"},"pr":{"type":"integer"}}},"resolution":{"type":"object","additionalProperties":false,"required":["state","by"],"properties":{"state":{"type":["string","null"],"enum":["resolved","partially_resolved","unresolved",null]},"by":{"type":["string","null"]}}},"freshness":{"type":"object","additionalProperties":false,"required":["state","last_verified_at","is_stale"],"properties":{"state":{"type":"string","enum":["verified","stale","never_verified"]},"last_verified_at":{"type":["string","null"]},"is_stale":{"type":"boolean"}}},"grouping":{"type":"object","additionalProperties":false,"required":["backbone","link_density"],"properties":{"backbone":{"type":["string","null"],"enum":["STRUCTURAL_SPANNING","STRUCTURAL_PARTIAL","LLM_ONLY",null]},"link_density":{"type":["number","null"],"minimum":0,"maximum":1}}},"fix_edges":{"type":"array","items":{"$ref":"#/$defs/fix_edge"}},"members":{"type":"array","items":{"$ref":"#/$defs/member"}},"trust":{"type":"object","additionalProperties":false,"required":["default_tier","includes_suggested"],"properties":{"default_tier":{"const":"verified"},"includes_suggested":{"type":"boolean"}}}},"$defs":{"fix_edge":{"type":"object","additionalProperties":false,"required":["issue_number","pr_number","tier","basis","confidence","recoverable_from_timeline"],"properties":{"issue_number":{"type":"integer"},"pr_number":{"type":"integer"},"tier":{"enum":["verified","suggested"]},"basis":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"recoverable_from_timeline":{"type":"boolean"}}},"member":{"type":"object","additionalProperties":false,"required":["kind","number","title","url","state"],"properties":{"kind":{"enum":["issue","pr"]},"number":{"type":"integer"},"title":{"type":["string","null"]},"url":{"type":["string","null"]},"state":{"type":["string","null"]},"close_reason":{"type":"object"},"merged":{"type":"boolean"},"is_fix_pr":{"type":"boolean"},"fix_tier":{"type":["string","null"],"enum":["verified","suggested",null]},"files_changed":{"type":"array","items":{"type":"string"}},"fix_diff_url":{"type":"string"},"fix_hunks":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["file","hunks"],"properties":{"file":{"type":"string"},"hunks":{"type":"array","items":{"type":"string"}}}}},"fix_detail_withheld":{"type":"boolean"}}}}}}}}