Skip to main content

Web Report Integration Guide

This guide explains how to integrate the Deep Research API’s Web Report feature into your Next.js frontend.

Authentication

The Deep Research API requires an API key for all analysis endpoints.

Required Header

Environment Variable

Add to your .env.local:

Overview

The Deep Research API generates two report formats:

API Endpoint

Note: The API endpoint is synchronous but long-running (can take 2-5 minutes).
Recommended Pattern: Start the analysis via API, then track progress via Supabase Realtime.

Start Analysis

POST https://research.cfosilvia.com/api/analysis

Request Body

Tip: Generate session_id on the client to subscribe to updates immediately.

Response (Success)

Returned after analysis completes (2-5 mins).

Integration Flow

  1. Client generates a unique session_id.
  2. Client subscribes to Supabase research_sessions table for this ID.
  3. Client calls POST /api/analysis with the session_id.
  4. API creates the session record and starts processing.
  5. Client receives live progress updates via Supabase (Phases: Planner → Executor → Web Report → PDF).
  6. API updates s3_key in Supabase when the Web Report is ready (approx. 75% progress).
  7. Client fetches and renders the markdown report.

Frontend Implementation (Next.js)

1. Start Analysis & Track Progress

2. Fetch Report Content

Once Supabase shows s3_key is present (see Supabase Session Tracking), fetch the markdown content. Note: You should create a secure API route in your Next.js app to proxy S3 requests, rather than exposing AWS credentials on the client.

3. Render Markdown

Use react-markdown to render the report. The API automatically converts image paths to accessible S3 URLs.

Image URLs

The Web Report Agent transforms the raw analysis to include full S3 URLs for charts. Example Transformation:
  • Original: ![Chart](charts/portfolio.png)
  • Web Report: ![Chart](https://prod-deep-research.s3.us-east-1.amazonaws.com/prod/user_123/.../charts/portfolio.png)
This ensures images render correctly without any extra client-side logic.