Skip to main content

Reports API

The Reports API allows you to manage the asynchronous generation of narrative reports.

Start a Report Generation​

Initiates a new report generation request. This is an asynchronous operation.

POST /api/reports

Request Body​

{
  "caseId": "case-abc-123",
  "reportType": "smokingHistory"
}
  • reportType can be one of:
    • smokingHistory
    • medicationHistory
    • allergyHistory
    • medicalHistory
    • pulmonologyDisabilityHistory

Response​

Returns a reportRequestId which you can use to check the status of the generation.

{
  "success": true,
  "reportRequestId": "req-xyz789",
  "message": "Report generation started"
}

Check Report Status​

Poll this endpoint to check the status of an ongoing report generation.

GET /api/reports?reportRequestId={reportRequestId}

Parameters​

  • reportRequestId (string, required): The ID returned from the POST request.

Response​

Returns the current status of the report request. The status field will be completed when the process is finished, and the reportId will be available.

{
  "reportRequestId": "req-xyz789",
  "status": "completed", // or 'pending', 'processing', 'awaiting_review', 'failed'
  "progress": "complete",
  "error": null,
  "reportId": "report-def456", // Available when status is 'completed'
  "createdAt": "...",
  "completedAt": "...",
  "stats": {
    "findingCount": 42
  }
}

Approve Findings for Report Generation​

After the initial AI analysis, the report status will become awaiting_review. After a user has reviewed and approved the findings, you must call this endpoint to proceed with the final report synthesis.

POST /api/reports

Request Body​

{
  "reportRequestId": "req-xyz789",
  "action": "approve_review"
}

Response​

A confirmation that the final report generation step has been initiated.

{
  "success": true,
  "message": "Review approved, report generation will continue"
}