Generate medical reports from consultation transcripts using customizable templates and writing styles.

Overview

The Report Generation API transforms consultation transcripts into professional medical reports. It supports:

• Multiple report templates
• Customizable writing style via style guidance parameters
• Multi-language support (German, French, Italian, English, Spanish)
• Streaming and non-streaming response modes
• Review modes for quality control
• Custom user instructions

Authentication

All requests require Bearer token authentication:

Authorization: Bearer <YOUR_TOKEN>

Example (JavaScript):

const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer ${token}`,
};

Endpoints

Generate Report

Create a medical report from a consultation transcript.

Endpoint

Method: POST
URL: https://api.44ai.ch/v2/generate/report

Request Parameters

Required:

• template_name (string): Backend name of the report template to use

Optional:

• transcript (object): Consultation transcript with bubbles array
  • bubbles (array): Array of transcript segments with text, start, end
• streaming (boolean): Enable streaming response. Default: false
• final_review (boolean): Enable final review mode. Default: false
• style_guidance (object): Style parameters (all values 0.0-1.0):
  • technical_level (number): 0.0 = layperson friendly, 1.0 = expert terminology. Default: 0.5
  • detail_level (number): 0.0 = brief/concise, 1.0 = comprehensive/detailed. Default: 0.5
  • formality (number): 0.0 = conversational, 1.0 = formal clinical style. Default: 0.5
  • confidence_expression (number): 0.0 = hedge language, 1.0 = definitive statements. Default: 0.5
• report_generation_config (object): Generation configuration
  • review_mode (string): no_review or with_review
• user_instructions (string): Custom instructions for report generation
• date_of_report (string): ISO 8601 datetime string for report date (defaults to today)
• consultation_id (string): ID of the associated consultation

Request Body Example

{
  "template_name": "de-internal-medicine",
  "transcript": {
    "bubbles": [
      {
        "text": "Patient presents with headache for 3 days",
        "start": 0.0,
        "end": 3.5
      },
      {
        "text": "No fever, no nausea, no visual disturbances",
        "start": 3.5,
        "end": 7.2
      }
    ]
  },
  "streaming": false,
  "final_review": false,
  "style_guidance": {
    "technical_level": 0.7,
    "detail_level": 0.6,
    "formality": 0.8,
    "confidence_expression": 0.5
  },
  "report_generation_config": {
    "review_mode": "with_review"
  },
  "user_instructions": "Focus on differential diagnosis"
}

Response

Success (200 OK):

{
  "report": "string (generated report text)",
  "final_yjs_document": "string (YJS document format, optional)"
}

Complete Example

const axios = require("axios");

async function generateReport(templateName, transcript, token, options = {}) {
  const url = "https://api.44ai.ch/v2/generate/report";

  const requestBody = {
    template_name: templateName,
    transcript: transcript,
    streaming: options.streaming || false,
    final_review: options.finalReview || false,
    style_guidance: options.styleGuidance || {
      technical_level: 0.5,
      detail_level: 0.5,
      formality: 0.5,
      confidence_expression: 0.5,
    },
    report_generation_config: options.generationConfig || {
      review_mode: "no_review",
    },
    user_instructions: options.userInstructions,
    date_of_report: options.dateOfReport,
    consultation_id: options.consultationId,
  };

  try {
    const response = await axios.post(url, requestBody, {
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${token}`,
      },
    });

    console.log("Report generated successfully");
    console.log("Report:", response.data.report);

    return response.data;
  } catch (error) {
    console.error(
      "Error generating report:",
      error.response?.data || error.message
    );
    throw error;
  }
}

// Example usage
const transcript = {
  bubbles: [
    {
      text: "Patient is a 45-year-old male presenting with persistent headaches",
      start: 0.0,
      end: 4.2,
    },
    {
      text: "Headaches started 3 days ago, located in frontal region",
      start: 4.2,
      end: 8.1,
    },
    {
      text: "Pain is moderate, 6 out of 10, worsens with movement",
      start: 8.1,
      end: 12.3,
    },
  ],
};

const options = {
  streaming: false,
  finalReview: true,
  styleGuidance: {
    technical_level: 0.7, // More medical terminology
    detail_level: 0.6, // Moderately detailed
    formality: 0.8, // Formal clinical style
    confidence_expression: 0.5, // Balanced confidence
  },
  generationConfig: {
    review_mode: "with_review",
  },
  userInstructions:
    "Please focus on differential diagnosis and include red flag symptoms",
};

generateReport("de-internal-medicine", transcript, "your-api-token", options)
  .then((result) => console.log("Generated report:", result.report))
  .catch((err) => console.error("Failed:", err));

Adjust Report Style

Modify the writing style of an existing report without regenerating from transcript.

Endpoint

Method: POST
URL: https://api.44ai.ch/v2/generate/report/adjust-style

Request Parameters

Required:

• consultation_id (string): ID of the consultation with the report to adjust
• style_guidance_new (object): New style parameters to apply
  • technical_level (number): 0.0-1.0
  • detail_level (number): 0.0-1.0
  • formality (number): 0.0-1.0
  • confidence_expression (number): 0.0-1.0

Optional:

• streaming (boolean): Enable streaming response. Default: true

Request Body Example

{
  "consultation_id": "abc123def456",
  "style_guidance_new": {
    "technical_level": 0.3,
    "detail_level": 0.4,
    "formality": 0.5,
    "confidence_expression": 0.4
  },
  "streaming": false
}

Response

Success (200 OK):

{
  "report": "string (adjusted report text)",
  "final_yjs_document": "string (YJS document format, optional)"
}

Complete Example

const axios = require("axios");

async function adjustReportStyle(
  consultationId,
  newStyleGuidance,
  token,
  streaming = false
) {
  const url = "https://api.44ai.ch/v2/generate/report/adjust-style";

  const requestBody = {
    consultation_id: consultationId,
    style_guidance_new: newStyleGuidance,
    streaming: streaming,
  };

  try {
    const response = await axios.post(url, requestBody, {
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${token}`,
      },
    });

    console.log("Report style adjusted successfully");
    console.log("Adjusted report:", response.data.report);

    return response.data;
  } catch (error) {
    console.error(
      "Error adjusting report style:",
      error.response?.data || error.message
    );
    throw error;
  }
}

// Example: Make report more patient-friendly
const patientFriendlyStyle = {
  technical_level: 0.2, // Less medical jargon
  detail_level: 0.4, // Concise
  formality: 0.3, // More conversational
  confidence_expression: 0.6, // Clear statements
};

adjustReportStyle("consultation-123", patientFriendlyStyle, "your-api-token")
  .then((result) => console.log("Adjusted report:", result.report))
  .catch((err) => console.error("Failed:", err));

// Example: Make report more formal/technical
const clinicalStyle = {
  technical_level: 0.9, // Medical terminology
  detail_level: 0.8, // Comprehensive
  formality: 0.9, // Formal clinical
  confidence_expression: 0.7, // Definitive statements
};

adjustReportStyle("consultation-123", clinicalStyle, "your-api-token", false)
  .then((result) => console.log("Clinical report:", result.report))
  .catch((err) => console.error("Failed:", err));

Style Guidance Parameters

All style guidance parameters range from 0.0 to 1.0:

Technical Level

• 0.0-0.3: Layperson friendly, minimal medical terminology
• 0.4-0.6: Balanced, some medical terms with explanations
• 0.7-1.0: Expert level, full medical terminology

Detail Level

• 0.0-0.3: Brief summary, key points only
• 0.4-0.6: Moderate detail, balanced coverage
• 0.7-1.0: Comprehensive, detailed narrative

Formality

• 0.0-0.3: Conversational, informal tone
• 0.4-0.6: Professional but approachable
• 0.7-1.0: Formal clinical documentation style

Confidence Expression

• 0.0-0.3: Cautious, uses hedging language ("may", "possibly")
• 0.4-0.6: Balanced, appropriate qualifiers
• 0.7-1.0: Definitive statements, clear conclusions

Review Modes

The report_generation_config.review_mode parameter controls quality review:

• no_review: Generate report without review step (faster)
• with_review: Include review step for quality assurance (recommended)

Streaming vs Non-Streaming

Non-Streaming (Default)

• Set streaming: false
• Returns complete report in single response
• Easier to handle programmatically
• Recommended for most use cases

Streaming

• Set streaming: true
• Returns report incrementally as it's generated
• Better user experience for long reports
• Requires stream handling in client code

Error Handling

Common error responses:

400 Bad Request:

{
  "detail": "Invalid request parameters"
}

401 Unauthorized:

{
  "detail": "Invalid or missing authentication token"
}

422 Validation Error:

{
  "detail": [
    {
      "loc": ["body", "template_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

500 Internal Server Error:

{
  "detail": "Internal server error occurred during report generation"
}

Best Practices

Template Selection

1. Use appropriate template for the clinical context
2. Verify template availability for your organization
3. Use template backend names (e.g., "de-internal-medicine")

Style Guidance

1. Start with default values (0.5) and adjust based on audience
2. For patient-facing reports: lower technical_level and formality
3. For clinical documentation: higher technical_level and formality
4. Test different combinations to find optimal settings

Performance

1. Use non-streaming mode for automated workflows
2. Use streaming mode for interactive user interfaces
3. Enable final_review for critical documents
4. Use no_review for draft generation

Quality Control

1. Always set final_review: true for production reports
2. Provide clear user_instructions for specific requirements
3. Review generated reports before finalizing
4. Use adjust-style to refine without full regeneration

Frequently Asked Questions

How do I get available templates?

Query the /v2/templates/report endpoint to get templates available to your account.

Can I customize report sections?

Report sections are defined by the template. Contact support for custom templates.

What languages are supported?

The API supports German (de, de-CH), French (fr), Italian (it), English (en), and Spanish (es).

How long does report generation take?

• Without review: typically 5-15 seconds
• With review: typically 10-30 seconds
• Streaming provides incremental updates

Can I adjust style after generation?

Yes, use the /v2/generate/report/adjust-style endpoint to modify style without regenerating from transcript.

What is the YJS document format?

YJS is a CRDT document format used internally. The final_yjs_document field is optional and used for collaborative editing features.