Medical Consensus

The Medical Consensus API enables you to submit clinical queries and receive comprehensive medical opinions synthesized from multiple expert sources. This feature is useful for validating diagnoses, exploring treatment options, and getting second opinions on complex cases.

Alpha Feature: Medical Consensus is an experimental feature. It may change without notice, has different rate limits than stable endpoints, and does not include SLA guarantees. Do not use in production without careful consideration.

Overview

Medical Consensus helps clinicians with:

Second Opinions: Get AI-synthesized expert perspectives on clinical cases
Diagnosis Validation: Confirm or explore differential diagnoses
Treatment Options: Review current guidelines and treatment approaches
Drug Interactions: Understand potential medication interactions

The API is asynchronous. You submit a query, receive a request ID, then poll for results when processing completes.

Authentication

Alpha endpoints use Bearer token authentication, which differs from the header-based authentication used by stable API endpoints.

Authorization: Bearer YOUR_API_KEY

You use the same API key for both stable and alpha endpoints. Only the authentication header format differs. Get your API key from dashboard.api.sully.ai.

Creating a Request

Submit a clinical query to the consensus endpoint. The API returns immediately with a request ID while processing happens asynchronously.

Endpoint

POST /alpha/consensus

Request Body

Field	Type	Required	Description
`query`	string	Yes	Your clinical question or scenario

Response

Field	Type	Description
`data.id`	string	Unique identifier for the consensus request
`data.status`	string	Initial status (always `pending`)
`data.created_at`	string	Timestamp when the request was created (ISO 8601)

Code Examples

const response = await fetch('https://api.sully.ai/alpha/consensus', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SULLY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "What are the differential diagnoses for a 45-year-old patient presenting with chest pain, shortness of breath, and elevated troponin levels?"
  })
});

const { data } = await response.json();
console.log('Consensus ID:', data.id);
console.log('Status:', data.status); // "pending"

Response Example

{
  "data": {
    "id": "consensus_abc123def456",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Polling for Results

After creating a request, poll the GET endpoint to check status and retrieve results when processing completes.

Endpoint

GET /alpha/consensus/{id}

Status Flow

Status	Description
`pending`	Request received, queued for processing
`processing`	Actively analyzing your clinical query
`completed`	Analysis complete, results available in `result.consensus_response`
`failed`	Processing failed, error details in `result.error`

Polling Example

async function waitForConsensus(consensusId: string): Promise<string> {
  const headers = {
    'Authorization': `Bearer ${process.env.SULLY_API_KEY}`
  };

  while (true) {
    const response = await fetch(
      `https://api.sully.ai/alpha/consensus/${consensusId}`,
      { headers }
    );
    const { data } = await response.json();

    if (data.status === 'completed') {
      return data.result.consensus_response;
    }

    if (data.status === 'failed') {
      throw new Error(data.result?.error || 'Consensus processing failed');
    }

    // Wait 5 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

// Usage
const consensusId = 'consensus_abc123def456';
const result = await waitForConsensus(consensusId);
console.log('Medical Consensus:', result);

Understanding Results

When a consensus request completes, the response includes the full request details and result.

Response Fields

Field	Type	Description
`data.id`	string	Unique identifier for the request
`data.status`	string	Current status: `pending`, `processing`, `completed`, or `failed`
`data.created_at`	string	Timestamp when request was created
`data.updated_at`	string	Timestamp when request was last updated
`data.result.consensus_response`	string	The medical consensus text (when `completed`)
`data.result.error`	string	Error message (when `failed`)

Completed Response Example

{
  "data": {
    "id": "consensus_abc123def456",
    "status": "completed",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z",
    "result": {
      "consensus_response": "Based on the clinical presentation of chest pain, shortness of breath, and elevated troponin levels in a 45-year-old patient, the most likely diagnosis is acute myocardial infarction (AMI). However, several differential diagnoses should be considered including pulmonary embolism, aortic dissection, and myocarditis. Immediate ECG and chest X-ray are recommended, along with serial troponin measurements. Consider CT pulmonary angiogram if PE is suspected, and cardiology consultation is recommended."
    }
  }
}

Failed Response Example

{
  "data": {
    "id": "consensus_abc123def456",
    "status": "failed",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z",
    "result": {
      "error": "Request was rejected due to insufficient clinical context"
    }
  }
}

Example Queries

The quality of the consensus response depends on the specificity and clinical relevance of your query. Here are examples of effective clinical queries:

Differential Diagnosis

What are the differential diagnoses for a 45-year-old patient presenting with
chest pain, shortness of breath, and elevated troponin levels?

Treatment Guidelines

What are the current treatment guidelines for newly diagnosed Type 2 diabetes
in a patient with BMI of 32 and no cardiovascular disease history?

Drug Interactions

What are the potential drug interactions between warfarin and commonly
prescribed antibiotics, and how should anticoagulation be managed?

Symptom Evaluation

A 60-year-old female presents with progressive fatigue, unintentional weight
loss of 15 pounds over 3 months, and intermittent low-grade fever. What
workup is recommended?

Pediatric Considerations

What are the recommended diagnostic criteria and initial management for
suspected Kawasaki disease in a 3-year-old with 5 days of fever?

Rate Limits

The Medical Consensus endpoint is rate limited to ensure fair usage across all users.

Aspect	Details
Limit	Configurable requests per day (based on your plan)
Window	24 hours
Exceeded	Returns `429 Too Many Requests`

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 status code:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later."
}

What to do:

Wait 24 hours for your limit to reset
Contact support@sully.ai to discuss higher limits
Review your usage to optimize query frequency

async function createConsensusWithRetry(query: string): Promise<string> {
  const response = await fetch('https://api.sully.ai/alpha/consensus', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SULLY_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query })
  });

  if (response.status === 429) {
    throw new Error('Rate limit exceeded. Please wait 24 hours or contact support.');
  }

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  const { data } = await response.json();
  return data.id;
}

Best Practices

Follow these guidelines to get the best results from Medical Consensus.

Be Specific in Your Queries

Less Effective	More Effective
”Patient has chest pain"	"55-year-old male with substernal chest pain radiating to left arm, onset 2 hours ago, associated with diaphoresis"
"What about diabetes?"	"What are first-line treatment options for newly diagnosed Type 2 diabetes with HbA1c of 8.5%?”

Include Relevant Patient Details

When appropriate, include:

Age and sex
Relevant medical history
Current medications
Symptom duration and characteristics
Relevant lab values or vital signs

Use for Clinical Decision Support

Medical Consensus is a clinical decision support tool. It does not replace clinical judgment, patient evaluation, or consultation with specialists. Always verify recommendations against current guidelines and apply your professional judgment.

Appropriate Use Cases

Appropriate	Not Appropriate
Exploring differential diagnoses	Making definitive diagnoses
Reviewing treatment guidelines	Prescribing without clinical evaluation
Getting second opinions on complex cases	Emergency medical decisions
Understanding drug interactions	Replacing specialist consultation

Verify Results

Always:

Cross-reference with current clinical guidelines
Consider patient-specific factors not in the query
Apply clinical judgment to all recommendations
Document the use of AI-assisted decision support appropriately

Next Steps

Alpha API Overview

Learn about alpha features and stability expectations

Alpha Authentication

Detailed authentication guide for alpha endpoints

Create Consensus API

Full API reference for creating consensus requests

Get Consensus API

Full API reference for retrieving consensus results

Overview

Alpha Guides

Alpha API Reference

Medical Consensus

Overview

Authentication

Creating a Request

Endpoint

Request Body

Response

Code Examples

Response Example

Polling for Results

Endpoint

Status Flow

Polling Example

Understanding Results

Response Fields

Completed Response Example

Failed Response Example

Example Queries

Differential Diagnosis

Treatment Guidelines

Drug Interactions

Symptom Evaluation

Pediatric Considerations

Rate Limits

Handling Rate Limits

Best Practices

Be Specific in Your Queries

Include Relevant Patient Details

Use for Clinical Decision Support

Appropriate Use Cases

Verify Results

Next Steps

Alpha API Overview

Alpha Authentication

Create Consensus API

Get Consensus API

Overview

Alpha Guides

Alpha API Reference

Documentation Index

​Overview

​Authentication

​Creating a Request

​Endpoint

​Request Body

​Response

​Code Examples

​Response Example

​Polling for Results

​Endpoint

​Status Flow

​Polling Example

​Understanding Results

​Response Fields

​Completed Response Example

​Failed Response Example

​Example Queries

​Differential Diagnosis

​Treatment Guidelines

​Drug Interactions

​Symptom Evaluation

​Pediatric Considerations

​Rate Limits

​Handling Rate Limits

​Best Practices

​Be Specific in Your Queries

​Include Relevant Patient Details

​Use for Clinical Decision Support

​Appropriate Use Cases

​Verify Results

​Next Steps

Alpha API Overview

Alpha Authentication

Create Consensus API

Get Consensus API

Overview

Authentication

Creating a Request

Endpoint

Request Body

Response

Code Examples

Response Example

Polling for Results

Endpoint

Status Flow

Polling Example

Understanding Results

Response Fields

Completed Response Example

Failed Response Example

Example Queries

Differential Diagnosis

Treatment Guidelines

Drug Interactions

Symptom Evaluation

Pediatric Considerations

Rate Limits

Handling Rate Limits

Best Practices

Be Specific in Your Queries

Include Relevant Patient Details

Use for Clinical Decision Support

Appropriate Use Cases

Verify Results

Next Steps