{"openapi": "3.1.0", "info": {"title": "Statwonk agent tools", "version": "1.0.0", "description": "Free revenue assessments and workflow blueprints. Inputs/reports are not stored. See /agents/instructions.txt for limitations, quotas, and local runners."}, "servers": [{"url": "https://statwonk.com"}], "paths": {"/api/agent-tools/v1/revenue/": {"post": {"operationId": "assessRevenue", "summary": "Assess a revenue dataset", "description": "Free. Processes data in memory; records metadata only. Requires permission to transmit inputs. No tool execution, contact submission, or purchase.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RevenueRequest"}, "example": {"csv": "date,revenue,ads,sales_hours\n2025-01-06,18614.28,2475.87,88.08\n2025-01-13,15470.23,1498.24,79.76\n2025-01-20,9913.81,882.47,40.38\n2025-01-27,13542.45,941.46,59.08\n2025-02-03,11833.78,809.36,44.91\n2025-02-10,18252.87,2429.76,68.2\n2025-02-17,13733.0,847.52,74.7\n2025-02-24,14912.13,1722.1,65.99\n2025-03-03,14026.82,2089.25,48.87\n2025-03-10,17250.67,2457.61,56.76\n2025-03-17,15585.98,1442.41,89.95\n2025-03-24,18815.18,1145.64,89.74\n2025-03-31,14738.22,855.62,88.96\n2025-04-07,11469.94,1278.1,41.7\n2025-04-14,16035.69,1471.34,80.84\n2025-04-21,20147.13,2392.32,99.12\n2025-04-28,17937.27,2039.17,93.51\n2025-05-05,13651.86,982.26,80.73\n2025-05-12,16328.74,1339.03,98.63\n2025-05-19,16471.35,2034.86,67.59\n2025-05-26,15478.48,2375.7,44.43\n2025-06-02,15129.66,1519.22,53.72\n2025-06-09,12626.98,1108.73,50.89\n2025-06-16,13314.04,1546.39,44.23\n2025-06-23,12497.66,1185.77,56.46\n2025-06-30,17328.42,2479.48,62.43\n2025-07-07,15479.2,1736.96,86.16\n2025-07-14,17385.64,2346.72,73.63\n2025-07-21,13186.36,877.65,65.15\n2025-07-28,16867.75,1860.03,78.57\n2025-08-04,14921.75,1175.35,66.61\n2025-08-11,16659.29,1766.33,78.98\n2025-08-18,15483.08,2198.04,45.66\n2025-08-25,14087.07,975.04,56.98\n2025-09-01,12774.68,1099.97,46.81\n2025-09-08,15974.72,1459.07,85.7\n2025-09-15,19530.85,2491.66,94.41\n2025-09-22,17781.47,2078.33,52.43\n2025-09-29,13960.47,1508.08,56.59\n2025-10-06,16424.57,2477.13,56.59\n2025-10-13,14118.26,1862.29,47.3\n2025-10-20,11830.45,811.77,70.21\n2025-10-27,16881.31,1593.68,76.69\n2025-11-03,13870.95,1093.6,81.71\n2025-11-10,14287.02,909.53,89.04\n2025-11-17,16025.43,1889.49,44.79\n2025-11-24,19097.72,2168.09,70.91\n2025-12-01,12492.55,1000.04,42.91\n2025-12-08,19196.38,2315.67,95.55\n2025-12-15,17032.02,2457.29,68.23\n2025-12-22,18549.49,2334.06,92.45\n2025-12-29,17873.83,2289.21,69.54\n2026-01-05,17921.74,2486.34,60.62\n2026-01-12,12635.9,1131.29,49.15\n2026-01-19,13342.13,1163.34,65.83\n2026-01-26,16600.73,1639.99,87.51\n2026-02-02,16803.13,2169.13,44.68\n2026-02-09,16115.35,2361.96,52.62\n2026-02-16,15760.33,2228.72,50.34\n2026-02-23,13930.12,1013.42,96.89\n2026-03-02,14192.6,1460.14,44.56\n2026-03-09,15762.04,2052.01,71.67\n2026-03-16,14552.44,1674.39,50.59\n2026-03-23,13973.91,816.33,77.58\n2026-03-30,16723.0,1490.94,94.77\n2026-04-06,16973.04,1533.92,95.29\n2026-04-13,17497.17,2278.29,77.84\n2026-04-20,14885.53,1925.31,89.62\n2026-04-27,15329.81,2493.56,49.13\n2026-05-04,14076.84,1560.23,71.05\n2026-05-11,18279.61,2336.89,76.98\n2026-05-18,15968.42,1681.71,86.96\n", "date_column": "date", "revenue_column": "revenue", "driver_columns": ["ads", "sales_hours"], "consent": true, "client": "api"}}}}, "responses": {"200": {"description": "Result produced. Inspect status; this does not mean business suitability or execution approval.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RevenueResponse"}}}}, "400": {"description": "Malformed JSON", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}, "413": {"description": "Body too large", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}, "415": {"description": "Unsupported content type", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}, "422": {"description": "Invalid inputs or missing consent", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}, "429": {"description": "Rate limit; retry after 60 seconds", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}, "headers": {"Retry-After": {"schema": {"type": "string"}, "description": "Seconds before retry."}}}, "503": {"description": "Service busy", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}}}}, "/api/agent-tools/v1/workflow/": {"post": {"operationId": "planWorkflow", "summary": "Build a proposed workflow implementation blueprint", "description": "Free. Processes data in memory; records metadata only. Requires permission to transmit inputs. No tool execution, contact submission, or purchase.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WorkflowRequest"}, "example": {"goal": "Turn weekly sales and spend exports into a reviewed revenue memo for the finance team.", "trigger": "Every Monday after the previous week closes.", "inputs": ["Weekly revenue CSV", "Advertising spend export", "Last week\u2019s approved memo"], "tools": ["File storage", "RevenueMix assessment", "Email"], "approval_owner": "Finance lead", "approval_rules": ["Finance lead reviews estimates, caveats, and recipients before sending."], "success_criteria": ["All figures reconcile to the source exports.", "Every estimate includes uncertainty and model limitations.", "No memo is sent without finance approval."], "constraints": ["Keep raw financial data in the approved workspace.", "Pilot with three historical weeks before enabling email."], "steps": [{"id": "collect", "name": "Collect and validate exports", "task": "Check dates, required columns, missing values, and reconciliation totals.", "effect": "read", "tools": ["File storage"], "depends_on": [], "output": "validated_dataset", "acceptance_check": "No missing periods or unresolved reconciliation differences."}, {"id": "assess", "name": "Assess revenue relationships", "task": "Use the local RevenueMix runner to inspect associations, uncertainty, and diagnostics.", "effect": "prepare", "tools": ["RevenueMix assessment"], "depends_on": ["collect"], "output": "assessment_report"}, {"id": "draft", "name": "Draft the decision memo", "task": "Summarize evidence and unresolved questions without claiming causality.", "effect": "prepare", "depends_on": ["assess"], "output": "memo_draft"}, {"id": "send", "name": "Send the approved memo", "task": "Present the exact memo and recipient list for approval, then send the approved version once.", "effect": "send", "tools": ["Email"], "depends_on": ["draft"], "output": "delivery_receipt"}], "consent": true, "client": "api"}}}}, "responses": {"200": {"description": "Result produced. Inspect status; this does not mean business suitability or execution approval.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WorkflowResponse"}}}}, "400": {"description": "Malformed JSON", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}, "413": {"description": "Body too large", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}, "415": {"description": "Unsupported content type", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}, "422": {"description": "Invalid inputs or missing consent", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}, "429": {"description": "Rate limit; retry after 60 seconds", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}, "headers": {"Retry-After": {"schema": {"type": "string"}, "description": "Seconds before retry."}}}, "503": {"description": "Service busy", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}}}}}}}}}}, "components": {"schemas": {"RevenueResponse": {"type": "object", "required": ["schema_version", "tool", "status", "summary", "limitations", "report_markdown", "review"], "properties": {"schema_version": {"type": "string"}, "tool": {"const": "revenue_assessment"}, "status": {"type": "string", "enum": ["completed", "needs_revision", "insufficient_data"]}, "summary": {"type": "string"}, "report_markdown": {"type": "string"}, "limitations": {"type": "array", "items": {"type": "string"}}, "review": {"type": "object", "properties": {"url": {"type": "string", "format": "uri"}, "requires_user_decision": {"const": true}}}, "run_id": {"type": ["string", "null"], "format": "uuid"}, "data": {"type": "object"}, "diagnostics": {"type": "object"}, "coefficients": {"type": "array", "items": {"type": "object", "required": ["name", "estimate", "standard_error", "interval_95"], "properties": {"name": {"type": "string"}, "estimate": {"type": "number"}, "standard_error": {"type": "number"}, "interval_95": {"type": "array", "minItems": 2, "maxItems": 2, "items": {"type": "number"}}}}}, "warnings": {"type": "array", "items": {"type": "string"}}, "next_steps": {"type": "array", "items": {"type": "string"}}}}, "WorkflowResponse": {"type": "object", "required": ["schema_version", "tool", "status", "summary", "limitations", "report_markdown", "review"], "properties": {"schema_version": {"type": "string"}, "tool": {"const": "workflow_planner"}, "status": {"type": "string", "enum": ["draft_ready", "needs_clarification"]}, "summary": {"type": "string"}, "report_markdown": {"type": "string"}, "limitations": {"type": "array", "items": {"type": "string"}}, "review": {"type": "object", "properties": {"url": {"type": "string", "format": "uri"}, "requires_user_decision": {"const": true}}}, "run_id": {"type": ["string", "null"], "format": "uuid"}, "steps": {"type": "array", "items": {"type": "object"}}, "clarifying_questions": {"type": "array", "items": {"type": "string"}}, "implementation_phases": {"type": "array", "items": {"type": "object"}}, "acceptance_tests": {"type": "array", "items": {"type": "object"}}}}, "RevenueRequest": {"type": "object", "additionalProperties": false, "required": ["csv", "date_column", "revenue_column", "driver_columns", "consent"], "properties": {"consent": {"type": "boolean", "const": true, "description": "Permission to send these inputs to Statwonk."}, "client": {"type": "string", "enum": ["api", "browser"], "default": "api", "description": "Self-declared channel; not verified identity."}, "csv": {"type": "string", "maxLength": 200000, "description": "At most 200,000 UTF-8 bytes and 2,000 data rows."}, "date_column": {"type": "string"}, "revenue_column": {"type": "string"}, "driver_columns": {"type": "array", "minItems": 1, "maxItems": 8, "uniqueItems": true, "items": {"type": "string"}}}}, "WorkflowRequest": {"type": "object", "additionalProperties": false, "required": ["consent"], "properties": {"consent": {"type": "boolean", "const": true, "description": "Permission to send these inputs to Statwonk."}, "client": {"type": "string", "enum": ["api", "browser"], "default": "api", "description": "Self-declared channel; not verified identity."}, "goal": {"type": "string", "maxLength": 1500}, "trigger": {"type": "string", "maxLength": 500}, "inputs": {"type": "array", "maxItems": 12, "items": {"type": "string", "maxLength": 500, "minLength": 1}}, "tools": {"type": "array", "maxItems": 12, "items": {"type": "string", "maxLength": 500, "minLength": 1}}, "success_criteria": {"type": "array", "maxItems": 12, "items": {"type": "string", "maxLength": 500, "minLength": 1}}, "constraints": {"type": "array", "maxItems": 12, "items": {"type": "string", "maxLength": 500, "minLength": 1}}, "approval_owner": {"type": "string", "maxLength": 200}, "approval_rules": {"type": "array", "maxItems": 12, "items": {"type": "string", "maxLength": 500, "minLength": 1}}, "steps": {"type": "array", "maxItems": 12, "items": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"id": {"type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,39}$"}, "name": {"type": "string", "minLength": 1, "maxLength": 120}, "task": {"type": "string", "maxLength": 1500}, "effect": {"type": "string", "enum": ["read", "prepare", "write", "send", "delete", "purchase"], "default": "prepare"}, "tools": {"type": "array", "maxItems": 12, "items": {"type": "string", "maxLength": 500, "minLength": 1}}, "depends_on": {"type": "array", "maxItems": 12, "items": {"type": "string", "maxLength": 500, "minLength": 1}}, "output": {"type": "string", "maxLength": 200}, "acceptance_check": {"type": "string", "maxLength": 500}}}}}}}}}