{"openapi":"3.1.0","info":{"title":"ShadowTrace v1 API","version":"0.1.0","description":"Programmatic access to ShadowTrace investigations.","x-methodology":"public-source-only"},"servers":[{"url":"http://localhost:3000/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"opaque"}},"schemas":{"Scan":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["email","phone","username","identity","image","social"]},"target":{"type":"string"},"state":{"type":"string","enum":["queued","running","awaiting_payment","unlocked"]},"paid":{"type":"boolean"},"durationMs":{"type":"integer"},"elapsedMs":{"type":"integer"},"progress":{"type":"integer","minimum":0,"maximum":100},"exposure":{"type":"object","properties":{"score":{"type":"integer","minimum":0,"maximum":100},"label":{"type":"string"}}}}},"Dossier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"target":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"summary":{"type":"string"},"behavioralAnalysis":{"type":"string"},"exposureAssessment":{"type":"string"},"recommendedFollowups":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"source":{"type":"string"},"severity":{"type":"string","enum":["info","notable","elevated","high"]},"confidence":{"type":"number","minimum":0,"maximum":1},"finding":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}}},"methodology":{"type":"string"}}}}},"security":[{"bearer":[]}],"paths":{"/scans":{"post":{"summary":"Begin an investigation","security":[{"bearer":["scan:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","target"],"properties":{"kind":{"type":"string","enum":["email","phone","username","identity","image","social"]},"target":{"type":"string"},"webhookUrl":{"type":"string","format":"uri"}}}}}},"responses":{"202":{"description":"Scan accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scan"}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthenticated"}}}},"/scans/{id}":{"get":{"summary":"Poll scan progress","security":[{"bearer":["scan:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scan state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scan"}}}},"404":{"description":"Not found"}}}},"/dossiers/{id}":{"get":{"summary":"Fetch a completed, paid dossier","security":[{"bearer":["dossier:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full dossier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dossier"}}}},"402":{"description":"Payment required"},"404":{"description":"Not found"}}}}}}