Skip to main content
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.
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

Request Body

Response

Code Examples

Response Example


Polling for Results

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

Endpoint

Status Flow

Polling Example


Understanding Results

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

Response Fields

Completed Response Example

Failed Response Example


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

Treatment Guidelines

Drug Interactions

Symptom Evaluation

Pediatric Considerations


Rate Limits

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

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 status code:
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

Best Practices

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

Be Specific in Your Queries

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

Verify Results

Always:
  1. Cross-reference with current clinical guidelines
  2. Consider patient-specific factors not in the query
  3. Apply clinical judgment to all recommendations
  4. 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