> For the complete documentation index, see [llms.txt](https://docs.scaleconnect.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleconnect.com.au/api/rest-api/scaleai-rest-api/review.md). # Review ## Portfolio Review Stream Endpoint > AI Portfolio Review with static traversal logic (streaming).\ > \ > This endpoint provides comprehensive portfolio analysis by:\ > \- Following a FIXED, SEQUENTIAL traversal of API endpoints\ > \- Collecting data across all portfolio aspects systematically\ > \- Streaming progress updates and review content\ > \ > Chunk Types:\ > \- status: Progress updates during data collection\ > \- text: Review report text chunks\ > \- content: Structured content chunks\ > \- done: Review complete (includes conversation\_history)\ > \- usage: Token usage statistics\ > \- error: Error messages ```json {"openapi":"3.1.0","info":{"title":"ScaleAI r16 API","version":"2.0.0"},"servers":[{"url":"https://agent-backend.r16.app"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ReviewRequest":{"properties":{"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Custom review request message"},"conversation_history":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Conversation History","description":"Previous conversation messages"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"LLM model to use","default":"claude-opus-4-5-20251101"},"jwt_token":{"type":"string","minLength":1,"description":"Downstream user JWT, separate from the service bearer token."},"strategy_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strategy Id","description":"Strategy/sub-control-centre ID"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID for admin access"},"environment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Environment","description":"Environment: 'local', 'dev', or 'prod'","default":"dev"},"template_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Mode","description":"Review template: 'comprehensive', 'quick_insights', 'goal_focused', 'risk_analysis'","default":"comprehensive"},"client_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Type","description":"Client type: 'individual', 'couple', 'business'","default":"individual"},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Frequency","description":"Review frequency: 'monthly', 'quarterly', 'annual'","default":"quarterly"},"review_tier":{"anyOf":[{"type":"string","enum":["check_in","rate_review","strategy_review"]},{"type":"null"}],"title":"Review Tier","description":"Review sophistication tier: 'check_in' (short update, no headings), 'rate_review' (one to two pages on what moved), 'strategy_review' (the full pack). None = legacy behaviour."},"output_sections":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Output Sections","description":"Section names to write, in order; the sophistication dial. None = the fixed default structure."}},"type":"object","title":"ReviewRequest","description":"Request model for portfolio review endpoints.","required":["jwt_token"]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/review/stream":{"post":{"tags":["Review"],"summary":"Portfolio Review Stream Endpoint","description":"AI Portfolio Review with static traversal logic (streaming).\n\nThis endpoint provides comprehensive portfolio analysis by:\n- Following a FIXED, SEQUENTIAL traversal of API endpoints\n- Collecting data across all portfolio aspects systematically\n- Streaming progress updates and review content\n\nChunk Types:\n- status: Progress updates during data collection\n- text: Review report text chunks\n- content: Structured content chunks\n- done: Review complete (includes conversation_history)\n- usage: Token usage statistics\n- error: Error messages","operationId":"portfolio_review_stream_endpoint_review_stream_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"text/event-stream":{"schema":{"type":"string","description":"SSE chunk. See the operation description for chunk types."}}}},"401":{"description":"Missing or invalid service bearer token, or missing downstream jwt_token in the request body.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Handler failed","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"503":{"description":"AI features temporarily disabled","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}}}}}}} ``` ## Portfolio Review Chat Endpoint > AI Portfolio Review (non-streaming) run by the AI\_REVIEWS\_AGENT sub-agent.\ > \ > The turn goes through ChatService with the client's user\_id + strategy\_id as\ > context: the agent fetches the strategy through its allow-listed tools\ > (the phase walk, notes, GraphQL) and writes the review from what came back.\ > This replaced the fixed pre-fetch traversal (still used by /review/stream\ > and /review/json) whose failures were swallowed into apology text.\ > \ > Response (contract unchanged for scale-backend's client-review\.service.ts):\ > \- response: The complete review report text\ > \- conversation\_history: Updated conversation history\ > \- phases\_analyzed: Number of tool calls that returned data (0 = no data)\ > \- ok: False when no tool call returned data — the caller must not save it ```json {"openapi":"3.1.0","info":{"title":"ScaleAI r16 API","version":"2.0.0"},"servers":[{"url":"https://agent-backend.r16.app"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ReviewRequest":{"properties":{"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Custom review request message"},"conversation_history":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Conversation History","description":"Previous conversation messages"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"LLM model to use","default":"claude-opus-4-5-20251101"},"jwt_token":{"type":"string","minLength":1,"description":"Downstream user JWT, separate from the service bearer token."},"strategy_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strategy Id","description":"Strategy/sub-control-centre ID"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID for admin access"},"environment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Environment","description":"Environment: 'local', 'dev', or 'prod'","default":"dev"},"template_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Mode","description":"Review template: 'comprehensive', 'quick_insights', 'goal_focused', 'risk_analysis'","default":"comprehensive"},"client_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Type","description":"Client type: 'individual', 'couple', 'business'","default":"individual"},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Frequency","description":"Review frequency: 'monthly', 'quarterly', 'annual'","default":"quarterly"},"review_tier":{"anyOf":[{"type":"string","enum":["check_in","rate_review","strategy_review"]},{"type":"null"}],"title":"Review Tier","description":"Review sophistication tier: 'check_in' (short update, no headings), 'rate_review' (one to two pages on what moved), 'strategy_review' (the full pack). None = legacy behaviour."},"output_sections":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Output Sections","description":"Section names to write, in order; the sophistication dial. None = the fixed default structure."}},"type":"object","title":"ReviewRequest","description":"Request model for portfolio review endpoints.","required":["jwt_token"]},"ReviewResponse":{"properties":{"response":{"type":"string","title":"Response","description":"Review report text"},"conversation_history":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","description":"Updated conversation history"},"phases_analyzed":{"type":"integer","title":"Phases Analyzed","description":"Number of tool calls that returned data (0 = the review has no data behind it)","default":0},"ok":{"type":"boolean","title":"Ok","description":"False when no tool call returned data; the caller must not save or notify on the text","default":true},"usage":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Usage","description":"Token usage statistics"}},"type":"object","required":["response","conversation_history"],"title":"ReviewResponse","description":"Response model for non-streaming review."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/review/chat":{"post":{"tags":["Review"],"summary":"Portfolio Review Chat Endpoint","description":"AI Portfolio Review (non-streaming) run by the AI_REVIEWS_AGENT sub-agent.\n\nThe turn goes through ChatService with the client's user_id + strategy_id as\ncontext: the agent fetches the strategy through its allow-listed tools\n(the phase walk, notes, GraphQL) and writes the review from what came back.\nThis replaced the fixed pre-fetch traversal (still used by /review/stream\nand /review/json) whose failures were swallowed into apology text.\n\nResponse (contract unchanged for scale-backend's client-review.service.ts):\n- response: The complete review report text\n- conversation_history: Updated conversation history\n- phases_analyzed: Number of tool calls that returned data (0 = no data)\n- ok: False when no tool call returned data — the caller must not save it","operationId":"portfolio_review_chat_endpoint_review_chat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewResponse"}}}},"401":{"description":"Missing or invalid service bearer token, or missing downstream jwt_token in the request body.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Handler failed","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"503":{"description":"AI features temporarily disabled","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}}}}}}} ``` ## Portfolio Review Json Endpoint > AI Portfolio Review with structured JSON response.\ > \ > This endpoint generates a portfolio review with clearly separated sections\ > returned as a JSON object. Unlike the streaming endpoint, this returns\ > all content in a single structured response.\ > \ > \*\*Fixed System Sections (8):\*\*\ > \- Portfolio Composition\ > \- Summary\ > \- Portfolio Snapshot\ > \- Property Overview\ > \- Observations\ > \- Key Drivers\ > \- Goal Progress\ > \- Next Steps & AI Summary\ > \ > \*\*User-Selectable Sections:\*\*\ > \- Tax Optimisation\ > \- Loan Structure & Comprehensiveness\ > \- Wealth Trajectory\ > \- Cashflow Position\ > \- Borrowing Power\ > \- Market Update & Property Analysis\ > \- Goals & Lifestyle Alignment\ > \- Action Items & SLAs Summary\ > \ > Returns:\ > JSONReviewResponse with all sections as separate JSON fields ```json {"openapi":"3.1.0","info":{"title":"ScaleAI r16 API","version":"2.0.0"},"servers":[{"url":"https://agent-backend.r16.app"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"JSONReviewRequest":{"properties":{"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Custom review request message or additional context"},"review_type":{"type":"string","title":"Review Type","description":"Review type: 'comprehensive', 'quick', 'detailed', 'focused'","default":"comprehensive"},"template_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Mode","description":"Template mode for generation","default":"Start from scratch"},"client_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Type","description":"Client type: 'First Home Buyer', 'Existing Home Owner', 'Investor', 'Downsizer'","default":"First Home Buyer"},"template_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Name","description":"Template name for the review"},"frequency":{"type":"string","title":"Frequency","description":"Review frequency: 'monthly', 'quarterly', 'yearly'","default":"monthly"},"output_sections":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Output Sections","description":"Additional user-selected sections to include in the review"},"addition_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Addition Context","description":"Additional context for the review"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"LLM model to use","default":"claude-opus-4-5-20251101"},"jwt_token":{"type":"string","minLength":1,"description":"Downstream user JWT, separate from the service bearer token."},"strategy_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strategy Id","description":"Strategy/sub-control-centre ID"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID for admin access"},"environment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Environment","description":"Environment: 'local', 'development', or 'production'","default":"development"}},"type":"object","title":"JSONReviewRequest","description":"Request model for structured JSON review endpoint.","required":["jwt_token"]},"JSONReviewResponse":{"properties":{"portfolio_composition":{"type":"string","title":"Portfolio Composition","description":"Brief factual bullets about users, properties, and loans"},"summary":{"type":"string","title":"Summary","description":"Current month facts (3-5 bullets)"},"portfolio_snapshot":{"type":"string","title":"Portfolio Snapshot","description":"4-8 bullets with portfolio performance overview"},"property_overview":{"type":"string","title":"Property Overview","description":"Property details with values, loans, equity, and LVR"},"observations":{"type":"string","title":"Observations","description":"Factual observations about performance, loans, cashflow, etc."},"key_drivers":{"type":"string","title":"Key Drivers","description":"Upcoming milestones and recent updates"},"goal_progress":{"type":"string","title":"Goal Progress","description":"Progress toward goals (max 6 bullets)"},"next_steps_ai_summary":{"type":"string","title":"Next Steps Ai Summary","description":"Broker-facing operational next steps"},"output_sections":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Output Sections","description":"User-selected additional sections with AI-generated content"},"phases_analyzed":{"type":"integer","title":"Phases Analyzed","description":"Number of data collection phases completed","default":0},"data_collection_success_rate":{"type":"number","title":"Data Collection Success Rate","description":"Percentage of successful data tool executions","default":0},"validation_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Validation Quality Score","description":"Quality score from review validation (0-100%)"},"validation_passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Validation Passed","description":"Whether the review passed validation checks"},"validation_issues_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Validation Issues Count","description":"Number of validation issues found"}},"type":"object","required":["portfolio_composition","summary","portfolio_snapshot","property_overview","observations","key_drivers","goal_progress","next_steps_ai_summary"],"title":"JSONReviewResponse","description":"Response model for structured JSON review.\n\nContains 8 fixed system sections plus any user-selected output_sections."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/review/json":{"post":{"tags":["Review"],"summary":"Portfolio Review Json Endpoint","description":"AI Portfolio Review with structured JSON response.\n\nThis endpoint generates a portfolio review with clearly separated sections\nreturned as a JSON object. Unlike the streaming endpoint, this returns\nall content in a single structured response.\n\n**Fixed System Sections (8):**\n- Portfolio Composition\n- Summary\n- Portfolio Snapshot\n- Property Overview\n- Observations\n- Key Drivers\n- Goal Progress\n- Next Steps & AI Summary\n\n**User-Selectable Sections:**\n- Tax Optimisation\n- Loan Structure & Comprehensiveness\n- Wealth Trajectory\n- Cashflow Position\n- Borrowing Power\n- Market Update & Property Analysis\n- Goals & Lifestyle Alignment\n- Action Items & SLAs Summary\n\nReturns:\n JSONReviewResponse with all sections as separate JSON fields","operationId":"portfolio_review_json_endpoint_review_json_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JSONReviewRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JSONReviewResponse"}}}},"401":{"description":"Missing or invalid service bearer token, or missing downstream jwt_token in the request body.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Handler failed","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"503":{"description":"AI features temporarily disabled","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.scaleconnect.com.au/api/rest-api/scaleai-rest-api/review.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.