{"openapi":"3.1.0","info":{"title":"SignalPack API","version":"0.1.0","description":"Read-only, source-aware investment research artifacts for agents. This API has no broker, account, or execution access."},"servers":[{"url":"/","description":"Current SignalPack deployment"}],"tags":[{"name":"System"},{"name":"Packs"},{"name":"Research"},{"name":"Guardrails"}],"paths":{"/api/v1/health":{"get":{"operationId":"getHealth","tags":["System"],"summary":"Get artifact freshness and release health","x-mcp-tool":"get_health","responses":{"200":{"description":"The current artifact release is consumable.","headers":{"ETag":{"schema":{"type":"string"},"description":"Strong validator for conditional GET requests."},"X-SignalPack-API-Version":{"schema":{"type":"string","const":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"304":{"description":"The cached representation is current."},"503":{"description":"No consumable artifact release is available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApiDocument","tags":["System"],"summary":"Get this OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"The cached representation is current."}}}},"/api/v1/packs":{"get":{"operationId":"listPacks","tags":["Packs"],"summary":"List available and planned packs","x-mcp-tool":"list_packs","responses":{"200":{"description":"Pack catalog.","headers":{"ETag":{"schema":{"type":"string"},"description":"Strong validator for conditional GET requests."},"X-SignalPack-API-Version":{"schema":{"type":"string","const":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"304":{"description":"The cached representation is current."}}}},"/api/v1/packs/{packId}/latest":{"get":{"operationId":"getLatestPack","tags":["Packs"],"summary":"Get the latest pack artifact","x-mcp-tool":"get_latest_pack","parameters":[{"name":"packId","in":"path","required":true,"schema":{"type":"string"},"description":"A SignalPack pack identifier."},{"name":"managers","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeat or comma-separate 13F manager IDs. Defaults to all managers."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["any","overlap","exclusive","disagreement"],"default":"any"},"description":"The derived 13F view mode."}],"responses":{"200":{"description":"Latest artifact and agent payload.","headers":{"ETag":{"schema":{"type":"string"},"description":"Strong validator for conditional GET requests."},"X-SignalPack-API-Version":{"schema":{"type":"string","const":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"304":{"description":"The cached representation is current."},"400":{"description":"Invalid view parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Pack or artifact not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Artifact unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/packs/{packId}/versions":{"get":{"operationId":"listPackVersions","tags":["Packs"],"summary":"List available artifact versions","x-mcp-tool":"list_pack_versions","parameters":[{"name":"packId","in":"path","required":true,"schema":{"type":"string"},"description":"A SignalPack pack identifier."}],"responses":{"200":{"description":"Version catalog.","headers":{"ETag":{"schema":{"type":"string"},"description":"Strong validator for conditional GET requests."},"X-SignalPack-API-Version":{"schema":{"type":"string","const":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"304":{"description":"The cached representation is current."},"404":{"description":"Pack or artifact not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/packs/{packId}/versions/diff":{"get":{"operationId":"compareVersions","tags":["Packs"],"summary":"Compare two artifact versions","x-mcp-tool":"compare_versions","parameters":[{"name":"packId","in":"path","required":true,"schema":{"type":"string"},"description":"A SignalPack pack identifier."},{"name":"from","in":"query","required":true,"schema":{"type":"string"}},{"name":"to","in":"query","required":true,"schema":{"type":"string"}},{"name":"managers","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeat or comma-separate 13F manager IDs. Defaults to all managers."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["any","overlap","exclusive","disagreement"],"default":"any"},"description":"The derived 13F view mode."}],"responses":{"200":{"description":"Semantic artifact diff.","headers":{"ETag":{"schema":{"type":"string"},"description":"Strong validator for conditional GET requests."},"X-SignalPack-API-Version":{"schema":{"type":"string","const":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"304":{"description":"The cached representation is current."},"400":{"description":"Invalid or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Pack or version not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Pack does not support version comparison.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/packs/{packId}/positions/{ticker}/explanation":{"get":{"operationId":"explainPosition","tags":["Research"],"summary":"Explain a position with source-backed evidence","x-mcp-tool":"explain_position","parameters":[{"name":"packId","in":"path","required":true,"schema":{"type":"string"},"description":"A SignalPack pack identifier."},{"name":"ticker","in":"path","required":true,"schema":{"type":"string"}},{"name":"managers","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeat or comma-separate 13F manager IDs. Defaults to all managers."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["any","overlap","exclusive","disagreement"],"default":"any"},"description":"The derived 13F view mode."}],"responses":{"200":{"description":"Position explanation.","headers":{"ETag":{"schema":{"type":"string"},"description":"Strong validator for conditional GET requests."},"X-SignalPack-API-Version":{"schema":{"type":"string","const":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"304":{"description":"The cached representation is current."},"400":{"description":"Invalid ticker or view parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Pack or position not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Pack does not support structured explanations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/ethos":{"get":{"operationId":"listEthos","tags":["Research"],"summary":"List supported investing methodologies","x-mcp-tool":"list_ethos","responses":{"200":{"description":"Ethos definitions.","headers":{"ETag":{"schema":{"type":"string"},"description":"Strong validator for conditional GET requests."},"X-SignalPack-API-Version":{"schema":{"type":"string","const":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"304":{"description":"The cached representation is current."}}}},"/api/v1/ethos/compare":{"post":{"operationId":"compareEthos","tags":["Research"],"summary":"Compare methodology scores for a selected 13F view","x-mcp-tool":"compare_ethos","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchRequest"}}}},"responses":{"200":{"description":"Scores and cross-methodology overlap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Requested position not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Pack does not support ethos comparison.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/policy/validate":{"post":{"operationId":"validatePolicy","tags":["Guardrails"],"summary":"Recalculate research policy checks","x-mcp-tool":"validate_policy","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ViewRequest"}}}},"responses":{"200":{"description":"Policy result. Execution remains disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Pack does not support policy recalculation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/packs/{packId}/audit":{"get":{"operationId":"exportAuditTrail","tags":["Guardrails"],"summary":"Export artifact provenance and policy evidence","x-mcp-tool":"export_audit_trail","parameters":[{"name":"packId","in":"path","required":true,"schema":{"type":"string"},"description":"A SignalPack pack identifier."},{"name":"managers","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeat or comma-separate 13F manager IDs. Defaults to all managers."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["any","overlap","exclusive","disagreement"],"default":"any"},"description":"The derived 13F view mode."}],"responses":{"200":{"description":"Audit export.","headers":{"ETag":{"schema":{"type":"string"},"description":"Strong validator for conditional GET requests."},"X-SignalPack-API-Version":{"schema":{"type":"string","const":"v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"304":{"description":"The cached representation is current."},"400":{"description":"Invalid view parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Pack or artifact not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"schemas":{"ApiMeta":{"type":"object","required":["apiVersion","contractVersion","capability","deprecated"],"properties":{"apiVersion":{"type":"string","const":"v1"},"contractVersion":{"type":"string","const":"0.1.0"},"capability":{"type":"string"},"deprecated":{"type":"boolean","const":false}}},"SuccessEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ErrorEnvelope":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ResearchRequest":{"type":"object","properties":{"packId":{"type":"string","default":"13f-copycat"},"managerIds":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["any","overlap","exclusive","disagreement"]},"ethosIds":{"type":"array","minItems":1,"items":{"type":"string"}},"tickers":{"type":"array","items":{"type":"string"}}}},"ViewRequest":{"type":"object","properties":{"packId":{"type":"string","default":"13f-copycat"},"managerIds":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["any","overlap","exclusive","disagreement"]}}}}}}