{"openapi":"3.1.0","info":{"title":"OpenGain API","version":"1.0.0","description":"Workspace-scoped, free-form SEO questions with evidence-grounded reports and resumable events."},"servers":[{"url":"/","description":"Current OpenGain deployment"}],"security":[{"bearerAuth":[]},{"sessionCookie":[]}],"paths":{"/v1/analyses":{"post":{"operationId":"startAnalysis","summary":"Ask an SEO question","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAnalysis"}}}},"responses":{"200":{"description":"Idempotent replay or a non-billable clarification draft","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Analysis"},{"$ref":"#/components/schemas/AnalysisDraft"}]}}}},"202":{"description":"Analysis accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"4XX":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listAnalyses","summary":"List workspace analyses","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Analysis history"},"4XX":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analysis-drafts":{"post":{"operationId":"previewAnalysisQuestion","summary":"Parse an SEO question without reserving credits","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAnalysis"}}}},"responses":{"200":{"description":"Parsed analysis draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisDraft"}}}},"4XX":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analyses/{id}":{"get":{"operationId":"getAnalysis","summary":"Get an analysis and validated result","parameters":[{"$ref":"#/components/parameters/AnalysisId"}],"responses":{"200":{"description":"Current analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analyses/{id}/events":{"get":{"operationId":"streamAnalysisEvents","summary":"Resume an analysis event stream","parameters":[{"$ref":"#/components/parameters/AnalysisId"},{"in":"header","name":"Last-Event-ID","schema":{"type":"integer","minimum":0}},{"in":"query","name":"after","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Server-sent events","content":{"text/event-stream":{}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analyses/{id}/followups":{"post":{"operationId":"askFollowup","summary":"Run a follow-up in the same evidence-aware session","parameters":[{"$ref":"#/components/parameters/AnalysisId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Followup"}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"202":{"description":"Follow-up accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"4XX":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reports/{id}/shares":{"post":{"operationId":"createReportShare","summary":"Create an unlisted report link","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"expires_in_days":{"type":"integer","minimum":1,"maximum":30,"default":30},"include_connected_metrics":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Share link created"},"4XX":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reports/{id}/shares/{shareId}":{"delete":{"operationId":"revokeReportShare","summary":"Revoke a report link","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"shareId","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Share revoked"},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Workspace API key"},"sessionCookie":{"type":"apiKey","in":"cookie","name":"better-auth.session_token"}},"parameters":{"IdempotencyKey":{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}},"AnalysisId":{"in":"path","name":"id","required":true,"schema":{"type":"string"}}},"schemas":{"SearchContext":{"type":"object","additionalProperties":false,"required":["engine","country","language","device"],"properties":{"engine":{"const":"google"},"country":{"type":"string","minLength":2,"maxLength":2,"default":"US"},"language":{"type":"string","default":"en"},"device":{"type":"string","enum":["desktop","mobile"],"default":"desktop"}}},"Target":{"type":"object","additionalProperties":false,"required":["role","url","scope"],"properties":{"role":{"type":"string","enum":["subject","competitor","benchmark"]},"url":{"type":"string","format":"uri"},"scope":{"type":"string","enum":["page","subdomain","domain"]},"label":{"type":"string"}}},"CreateAnalysis":{"type":"object","additionalProperties":false,"required":["question","max_credits"],"properties":{"question":{"type":"string","minLength":2,"maxLength":2000},"search_context":{"$ref":"#/components/schemas/SearchContext"},"include_gsc":{"type":"boolean","default":false,"description":"Request owned Search Console evidence. Ranking-drop questions imply this automatically and require a covering active property."},"project_id":{"type":"string"},"max_credits":{"type":"integer","minimum":1,"maximum":10000},"runs":{"type":"integer","enum":[1,3,5],"default":1,"description":"Samples per AI engine. Accepted only for AI-visibility questions; one run supports presence and absence claims, mention rates require at least three."}}},"NormalizedAnalysisRequest":{"type":"object","additionalProperties":false,"required":["question_kind","question","targets","search_context","include_gsc","max_credits"],"properties":{"draft_id":{"type":"string"},"question_kind":{"type":"string","enum":["low_ranking","outranked","ranking_drop","technical_issues","content_opportunities","backlink_weakness","ai_visibility","ai_outranked"]},"question":{"type":"string"},"targets":{"type":"array","minItems":1,"maxItems":6,"items":{"$ref":"#/components/schemas/Target"}},"keyword":{"type":"string"},"topic":{"type":"string"},"search_context":{"$ref":"#/components/schemas/SearchContext"},"include_gsc":{"type":"boolean"},"project_id":{"type":"string"},"max_credits":{"type":"integer"},"runs":{"type":"integer","enum":[1,3,5],"default":1,"description":"Samples per AI engine, present only for AI-visibility questions."}}},"AnalysisDraft":{"type":"object","additionalProperties":false,"required":["object","draft_id","question","targets","search_context","include_gsc","max_credits","missing_fields","ambiguities","can_run","parser"],"properties":{"object":{"const":"analysis_draft"},"draft_id":{"type":"string"},"question":{"type":"string"},"question_kind":{"type":"string","enum":["low_ranking","outranked","ranking_drop","technical_issues","content_opportunities","backlink_weakness","ai_visibility","ai_outranked"]},"targets":{"type":"array","items":{"$ref":"#/components/schemas/Target"}},"keyword":{"type":"string"},"topic":{"type":"string"},"search_context":{"$ref":"#/components/schemas/SearchContext"},"include_gsc":{"type":"boolean"},"project_id":{"type":"string"},"max_credits":{"type":"integer"},"runs":{"type":"integer","enum":[1,3,5],"default":1,"description":"Samples per AI engine, echoed back when the request carried it."},"missing_fields":{"type":"array","items":{"type":"string"}},"ambiguities":{"type":"array","items":{"type":"object"}},"can_run":{"type":"boolean"},"estimate":{"type":"object"},"parser":{"type":"object"}}},"Followup":{"type":"object","additionalProperties":false,"required":["question","max_credits"],"properties":{"question":{"type":"string","minLength":2,"maxLength":2000},"max_credits":{"type":"integer","minimum":1,"maximum":10000}}},"Analysis":{"type":"object","required":["id","session_id","status","stage","progress","costs","trace_id"],"properties":{"id":{"type":"string"},"session_id":{"type":"string"},"parent_analysis_id":{"type":["string","null"]},"request":{"oneOf":[{"$ref":"#/components/schemas/NormalizedAnalysisRequest"},{"$ref":"#/components/schemas/Followup"}]},"status":{"type":"string","enum":["queued","reserving","collecting","synthesizing","validating","completed","failed","cancelled"]},"stage":{"type":"string"},"progress":{"type":"integer","minimum":0,"maximum":100},"estimate":{"type":"integer"},"reservation":{"type":"object"},"costs":{"type":"object"},"report_id":{"type":"string"},"result":{"type":"object"},"error":{"type":"object"},"trace_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"replayed":{"type":"boolean"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","trace_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"trace_id":{"type":"string"}}}}}}}}