{"openapi":"3.1.0","paths":{"/api/v1/ai/agents":{"get":{"summary":"List AI agents available in the current context","tags":["aiAgent"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["id","name","description"],"additionalProperties":false}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/ai/conversations":{"get":{"summary":"List the caller's AI conversations for the current context","tags":["aiAgent"],"parameters":[{"name":"agentId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agentId":{"type":"string"},"title":{"type":"string"},"pinned":{"type":"boolean"},"contextType":{"type":"string"},"contextId":{"type":"string"},"userId":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"model":{"type":["string","null"]},"effort":{"anyOf":[{"type":"string","enum":["low","medium","high","xhigh","max"]},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","agentId","title","pinned","contextType","contextId","userId","inputTokens","outputTokens","model","effort","createdAt","updatedAt"],"additionalProperties":false}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}},"post":{"summary":"Create a new AI conversation","tags":["aiAgent"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"title":{"type":"string"}},"required":["agentId"]}}}},"responses":{"201":{"description":"201","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agentId":{"type":"string"},"title":{"type":"string"},"pinned":{"type":"boolean"},"contextType":{"type":"string"},"contextId":{"type":"string"},"userId":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"model":{"type":["string","null"]},"effort":{"anyOf":[{"type":"string","enum":["low","medium","high","xhigh","max"]},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","agentId","title","pinned","contextType","contextId","userId","inputTokens","outputTokens","model","effort","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/ai/conversations/{conversationId}/model":{"patch":{"summary":"Override the model and reasoning effort for one conversation","tags":["aiAgent"],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"model":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"effort":{"anyOf":[{"type":"string","enum":["low","medium","high","xhigh","max"]},{"type":"null"}]}},"required":["model","effort"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agentId":{"type":"string"},"title":{"type":"string"},"pinned":{"type":"boolean"},"contextType":{"type":"string"},"contextId":{"type":"string"},"userId":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"model":{"type":["string","null"]},"effort":{"anyOf":[{"type":"string","enum":["low","medium","high","xhigh","max"]},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","agentId","title","pinned","contextType","contextId","userId","inputTokens","outputTokens","model","effort","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/ai/conversations/{conversationId}":{"get":{"summary":"Get a conversation with its messages","tags":["aiAgent"],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"conversation":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agentId":{"type":"string"},"title":{"type":"string"},"pinned":{"type":"boolean"},"contextType":{"type":"string"},"contextId":{"type":"string"},"userId":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"model":{"type":["string","null"]},"effort":{"anyOf":[{"type":"string","enum":["low","medium","high","xhigh","max"]},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","agentId","title","pinned","contextType","contextId","userId","inputTokens","outputTokens","model","effort","createdAt","updatedAt"],"additionalProperties":false},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"conversationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"role":{"type":"string","enum":["user","assistant"]},"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"markdown"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"chart"},"spec":{"type":"object","properties":{"chartType":{"type":"string","enum":["timeseries","bar","pie","counter"]},"title":{"type":"string"},"data":{"maxItems":500,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"xField":{"type":"string"},"series":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"}},"required":["field"],"additionalProperties":false}},"labelField":{"type":"string"},"valueField":{"type":"string"},"unit":{"type":"string"}},"required":["chartType","title","data"],"additionalProperties":false}},"required":["type","spec"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"table"},"spec":{"type":"object","properties":{"title":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"format":{"type":"string","enum":["text","number","amount","datetime"]}},"required":["key","label"],"additionalProperties":false}},"rows":{"maxItems":500,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["columns","rows"],"additionalProperties":false}},"required":["type","spec"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"widget_spec"},"spec":{"type":"object","properties":{"widgetType":{"type":"string","enum":["counter","piechart","table","timeseries","note"]},"title":{"type":"string"},"description":{"type":"string"},"dataset":{"type":"string"},"query":{"type":"string"},"width":{"type":"integer","minimum":1,"maximum":12},"height":{"type":"integer","minimum":1,"maximum":9007199254740991},"config":{"anyOf":[{"type":"object","properties":{"legend":{"type":"boolean"},"tooltip":{"type":"boolean"},"colors":{"type":"array","items":{"type":"string"}},"borderStyle":{"type":"string","enum":["none","solid","dashed","dotted"]},"customCss":{"type":"string"},"aiConversationId":{"type":"string"},"chartType":{"type":"string","enum":["line","area","bar"]},"xAxis":{"type":"object","properties":{"dataKey":{"type":"string"},"label":{"type":"string"}},"required":["dataKey"],"additionalProperties":false},"yAxis":{"type":"object","properties":{"label":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false}},"required":["chartType","xAxis","yAxis"],"additionalProperties":false},{"type":"object","properties":{"legend":{"type":"boolean"},"tooltip":{"type":"boolean"},"colors":{"type":"array","items":{"type":"string"}},"borderStyle":{"type":"string","enum":["none","solid","dashed","dotted"]},"customCss":{"type":"string"},"aiConversationId":{"type":"string"},"format":{"type":"string","enum":["number","currency","percentage"]},"prefix":{"type":"string"},"suffix":{"type":"string"},"decimals":{"type":"number"},"size":{"type":"string","enum":["small","medium","large","xlarge"]},"currency":{"type":"string"},"locale":{"type":"string"},"accentColor":{"type":"string"},"icon":{"type":"string"},"comparison":{"type":"object","properties":{"enabled":{"type":"boolean"},"type":{"type":"string","enum":["percentage","absolute"]},"period":{"type":"string","enum":["previous","year_ago"]},"invertColors":{"type":"boolean"}},"required":["enabled","type","period"],"additionalProperties":false}},"required":["format"],"additionalProperties":false},{"type":"object","properties":{"legend":{"type":"boolean"},"tooltip":{"type":"boolean"},"colors":{"type":"array","items":{"type":"string"}},"borderStyle":{"type":"string","enum":["none","solid","dashed","dotted"]},"customCss":{"type":"string"},"aiConversationId":{"type":"string"},"donut":{"type":"boolean"},"labelKey":{"type":"string"},"valueKey":{"type":"string"},"showPercentage":{"type":"boolean"},"legendPosition":{"type":"string","enum":["top","bottom","left","right"]},"legendValues":{"type":"string","enum":["none","value","percentage","both"]},"maxSize":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["labelKey","valueKey"],"additionalProperties":false},{"type":"object","properties":{"legend":{"type":"boolean"},"tooltip":{"type":"boolean"},"colors":{"type":"array","items":{"type":"string"}},"borderStyle":{"type":"string","enum":["none","solid","dashed","dotted"]},"customCss":{"type":"string"},"aiConversationId":{"type":"string"},"content":{"default":"","type":"string"}},"required":["content"],"additionalProperties":false},{"type":"object","properties":{"legend":{"type":"boolean"},"tooltip":{"type":"boolean"},"colors":{"type":"array","items":{"type":"string"}},"borderStyle":{"type":"string","enum":["none","solid","dashed","dotted"]},"customCss":{"type":"string"},"aiConversationId":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"header":{"type":"string"},"width":{"type":"number"},"format":{"type":"string","enum":["text","number","currency","date","boolean"]}},"required":["key","header"],"additionalProperties":false}},"pagination":{"type":"boolean"},"pageSize":{"type":"number"}},"required":["columns"],"additionalProperties":false},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}]},"filterMapping":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"enabled":{"type":"boolean"},"mapTo":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["enabled"],"additionalProperties":false}}},"required":["widgetType","title","dataset","query","width","height","config"],"additionalProperties":false}},"required":["type","spec"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"tool_activity"},"toolName":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string","enum":["running","ok","error"]},"durationMs":{"type":"number"}},"required":["type","toolName","status"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"proposal"},"proposalId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"kind":{"type":"string","enum":["decision_table_rules","email_send","dashboard_widgets"]},"targetId":{"type":"string"},"targetName":{"type":"string"},"summary":{"type":"string"},"preview":{"type":"string"},"email":{"type":"object","properties":{"subject":{"type":"string"},"body":{"type":"string"}},"required":["subject","body"],"additionalProperties":false}},"required":["type","proposalId","kind","targetId","targetName","summary","preview"],"additionalProperties":false}]}},"createdAt":{"type":"string"}},"required":["id","conversationId","role","blocks","createdAt"],"additionalProperties":false}}},"required":["conversation","messages"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}},"put":{"summary":"Update a conversation (rename and/or pin)","tags":["aiAgent"],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"pinned":{"type":"boolean"}}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agentId":{"type":"string"},"title":{"type":"string"},"pinned":{"type":"boolean"},"contextType":{"type":"string"},"contextId":{"type":"string"},"userId":{"type":"string"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"model":{"type":["string","null"]},"effort":{"anyOf":[{"type":"string","enum":["low","medium","high","xhigh","max"]},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","agentId","title","pinned","contextType","contextId","userId","inputTokens","outputTokens","model","effort","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a conversation and its messages","tags":["aiAgent"],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/ai/conversations/{conversationId}/proposals":{"get":{"summary":"List change proposals of a conversation with their statuses","tags":["aiAgent"],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"conversationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"kind":{"type":"string","enum":["decision_table_rules","email_send","dashboard_widgets"]},"targetId":{"type":"string"},"targetName":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string","enum":["pending","applied","rejected","failed"]},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","conversationId","kind","targetId","targetName","summary","status","error","createdAt","updatedAt"],"additionalProperties":false}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/ai/proposals/{proposalId}/approve":{"post":{"summary":"Approve a pending proposal and apply the change","tags":["aiAgent"],"parameters":[{"name":"proposalId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"conversationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"kind":{"type":"string","enum":["decision_table_rules","email_send","dashboard_widgets"]},"targetId":{"type":"string"},"targetName":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string","enum":["pending","applied","rejected","failed"]},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","conversationId","kind","targetId","targetName","summary","status","error","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/ai/proposals/{proposalId}/reject":{"post":{"summary":"Reject a pending proposal","tags":["aiAgent"],"parameters":[{"name":"proposalId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"conversationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"kind":{"type":"string","enum":["decision_table_rules","email_send","dashboard_widgets"]},"targetId":{"type":"string"},"targetName":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string","enum":["pending","applied","rejected","failed"]},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","conversationId","kind","targetId","targetName","summary","status","error","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/ai/conversations/{conversationId}/messages":{"post":{"description":"Responds with a text/event-stream of AiAgentStreamEvent JSON events, not the declared JSON body.","summary":"Send a user message and stream the agent's response (SSE)","tags":["aiAgent"],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":8000}},"required":["message"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}}},"info":{"title":"API – General","version":"1.0.0"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"BearerAuth":[]}],"servers":[{"url":"https://api-sandbox.babelpay.io","description":"Current environment"}],"webhooks":{"paymentCallback":{"post":{"summary":"Payment webhook callback","description":"**Note: Never trust the callback data without signature verification!** The callback is sent to the callbackUrl provided in the payment request when the transaction reaches a final state. Delivered with up to 3 retries.\n\n## Signature verification\n\nEvery webhook request includes two headers for signature verification:\n\n| Header | Description |\n| --- | --- |\n| `X-Webhook-Signature` | `sha256=<hex-encoded HMAC-SHA256>` |\n| `X-Webhook-Timestamp` | Unix epoch seconds when the request was signed |\n\nThe HMAC is computed over `{timestamp}.{raw JSON body}` using the `webhookSecret` (`whsec_…`) returned when the API key was created.\n\n### Verification steps\n\n1. Read `X-Webhook-Timestamp` and `X-Webhook-Signature` from the request headers.\n2. Reject the request if the timestamp is more than 5 minutes old (replay protection).\n3. Concatenate `{timestamp}.{raw request body}` (UTF-8).\n4. Compute `HMAC-SHA256(webhookSecret, concatenated string)` and hex-encode the result.\n5. Compare with the signature value after the `sha256=` prefix using a constant-time comparison.\n\n### Quick test — TypeScript Playground\n\nPaste the snippet below into [TypeScript Playground](https://www.typescriptlang.org/play), fill in the three values from an actual webhook request, and check the **Logs** tab.\n\n```typescript\n// ---- paste your values here ----\nconst webhookSecret    = \"whsec_...\";           // from API key creation\nconst signatureHeader  = \"sha256=...\";          // X-Webhook-Signature header\nconst timestampHeader  = \"1717344000\";          // X-Webhook-Timestamp header\nconst rawBody          = '{\"id\":\"...\"}';       // raw JSON body\n\n// ---- verify ----\n(async () => {\n  const enc = new TextEncoder();\n  const key = await crypto.subtle.importKey(\n    \"raw\", enc.encode(webhookSecret),\n    { name: \"HMAC\", hash: \"SHA-256\" }, false, [\"sign\"],\n  );\n  const sig = await crypto.subtle.sign(\n    \"HMAC\", key, enc.encode(`${timestampHeader}.${rawBody}`),\n  );\n  const expected = Array.from(new Uint8Array(sig))\n    .map(b => b.toString(16).padStart(2, \"0\")).join(\"\");\n  const received = signatureHeader.replace(/^sha256=/, \"\");\n\n  console.log(\"Expected:\", expected);\n  console.log(\"Received:\", received);\n  console.log(\"Valid:\", expected === received);\n})();\n```\n","requestBody":{"description":"The webhook callback payload containing the payment result.","required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","blocked","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"},"paymentOption":{"type":"string","enum":["card","ideal","bancontact","paypal","klarna","pay-by-bank","apple-pay","google-pay","crypto-onramp","crypto-accept"]}},"required":["id"],"additionalProperties":false,"description":"Webhook callback payload sent to the customer callbackUrl","example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":24.42,"cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"parameters":[{"name":"X-Webhook-Signature","in":"header","required":false,"description":"HMAC-SHA256 signature: `sha256=<hex>`","schema":{"type":"string","example":"sha256=a1b2c3d4..."}},{"name":"X-Webhook-Timestamp","in":"header","required":false,"description":"Unix epoch seconds when the signature was computed","schema":{"type":"string","example":"1717344000"}}],"responses":{"200":{"description":"Callback received successfully. Any 2xx response is treated as success."}}}}}}