Authentication (Alpha)

Overview

The Sully.ai Alpha API uses the same authentication system as our stable API. All requests must include a valid API key in the Authorization header.

Alpha API Notice: This is an experimental version of our API. Features may change without notice and should not be used in production environments without careful consideration.

API Key Authentication

All Alpha API requests require authentication using your API key:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

Sign up for a Sully.ai account at dashboard.api.sully.ai
Navigate to the API Keys section in your dashboard
Generate a new API key or use an existing one
Copy the key and store it securely

Keep your API key secure: Never expose your API key in client-side code or public repositories. Store it as an environment variable or in a secure configuration file.

Base URL

The Alpha API uses the same base URL as our stable API:

https://api.sully.ai

Alpha endpoints are prefixed with /alpha/ to distinguish them from stable endpoints.

Example Request

Here’s how to make an authenticated request to the Alpha API:

cURL

curl -X POST "https://api.sully.ai/alpha/consensus" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the treatment options for Type 2 diabetes?"
  }'

JavaScript

const response = await fetch('https://api.sully.ai/alpha/consensus', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "What are the treatment options for Type 2 diabetes?"
  })
});

const data = await response.json();

Python

import requests
import os

url = "https://api.sully.ai/alpha/consensus"
headers = {
    "Authorization": f"Bearer {os.getenv('SULLY_API_KEY')}",
    "Content-Type": "application/json"
}
data = {
    "query": "What are the treatment options for Type 2 diabetes?"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

Error Responses

401 Unauthorized

If your API key is missing or invalid, you’ll receive a 401 error:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

If your account doesn’t have access to alpha features:

{
  "error": "Forbidden",
  "message": "Alpha API access not enabled for this account"
}

Rate Limiting

Alpha API endpoints may have different rate limits than stable endpoints:

Medical Consensus: Limited per day based on your plan
Note Templates: Limited per request based on complexity
Rate limit headers: Check response headers for current limits
Exceeded limits: Results in 429 Too Many Requests

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Best Practices

Environment Variables

Store your API key as an environment variable:

export SULLY_API_KEY="your_api_key_here"

Error Handling

Always handle authentication errors gracefully:

async function makeAuthenticatedRequest(endpoint, data) {
  try {
    const response = await fetch(`https://api.sully.ai${endpoint}`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SULLY_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    if (response.status === 401) {
      throw new Error('Invalid API key');
    }

    if (response.status === 403) {
      throw new Error('Alpha API access not enabled');
    }

    return await response.json();
  } catch (error) {
    console.error('Authentication error:', error.message);
    throw error;
  }
}

Testing

Test your authentication with a simple request:

curl -X GET "https://api.sully.ai/alpha/consensus" \
  -H "Authorization: Bearer YOUR_API_KEY"

Alpha API Features

Current alpha features include:

Medical Consensus: Get expert medical opinions on clinical queries
Note Templates: Generate note templates from provider notes
Advanced Analytics: Enhanced insights and reporting (coming soon)
AI-Powered Recommendations: Intelligent suggestions for clinical workflows (coming soon)

Support

For alpha API issues:

Email: support@sully.ai
Include “Alpha API” in your subject line
Provide your account ID and request details

Migration to Stable

When alpha features graduate to stable:

We’ll announce the migration timeline
Endpoints will be available at both /alpha/ and stable paths
You’ll have time to update your integration
Alpha endpoints will eventually be deprecated

Stay updated on our blog for alpha feature announcements and migration guides.

Overview

Alpha Guides

Alpha API Reference

Authentication (Alpha)

Overview

API Key Authentication

Getting Your API Key

Base URL

Example Request

Error Responses

401 Unauthorized

403 Forbidden

Rate Limiting

Best Practices

Environment Variables

Error Handling

Testing

Alpha API Features

Support

Migration to Stable

​Overview

​API Key Authentication

​Getting Your API Key

​Base URL

​Example Request

​Error Responses

​401 Unauthorized

​403 Forbidden

​Rate Limiting

​Best Practices

​Environment Variables

​Error Handling

​Testing

​Alpha API Features

​Support

​Migration to Stable

Overview

API Key Authentication

Getting Your API Key

Base URL

Example Request

Error Responses

401 Unauthorized

403 Forbidden

Rate Limiting

Best Practices

Environment Variables

Error Handling

Testing

Alpha API Features

Support

Migration to Stable