🚀 Getting Started

Python Quick Start

import requests

# Your API credentials
API_KEY = "your_api_key_here"
BASE_URL = "https://api.proteinclassifier.com/v1"

# Classify a sequence
response = requests.post(
    f"{BASE_URL}/classify",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "sequences": [
            {"id": "my_protein", "sequence": "MKVLWAASLLLLASAARA"}
        ]
    }
)

# Parse result
result = response.json()["results"][0]
print(f"Classification: {result['classification']}")
print(f"Confidence: {result['confidence']:.2f}")
print(f"Conditions met: {result['conditions_met']}/7")

Batch Processing Example

import requests
from typing import List, Dict

def classify_batch(sequences: List[Dict[str, str]], api_key: str) -> List[Dict]:
    """
    Classify multiple sequences efficiently using batch processing.
    
    Args:
        sequences: List of dicts with 'id' and 'sequence' keys
        api_key: Your API key
        
    Returns:
        List of classification results
    """
    # Process in batches of 50 (free tier max)
    batch_size = 50
    all_results = []
    
    for i in range(0, len(sequences), batch_size):
        batch = sequences[i:i + batch_size]
        
        response = requests.post(
            "https://api.proteinclassifier.com/v1/classify",
            headers={
                "X-API-Key": api_key,
                "Content-Type": "application/json"
            },
            json={"sequences": batch}
        )
        
        response.raise_for_status()
        results = response.json()["results"]
        all_results.extend(results)
        
        print(f"Processed {i + len(batch)}/{len(sequences)} sequences")
    
    return all_results

# Example usage
sequences = [
    {"id": f"protein_{i}", "sequence": seq}
    for i, seq in enumerate(my_sequence_list)
]

results = classify_batch(sequences, "your_api_key")

# Analyze results
disordered = [r for r in results if r["classification"] == "disordered"]
structured = [r for r in results if r["classification"] == "structured"]

print(f"Disordered: {len(disordered)}, Structured: {len(structured)}")

Error Handling Example

import requests
import time

def classify_with_retry(sequences, api_key, max_retries=3):
    """
    Classify sequences with exponential backoff retry logic.
    """
    url = "https://api.proteinclassifier.com/v1/classify"
    headers = {
        "X-API-Key": api_key,
        "Content-Type": "application/json"
    }
    
    for attempt in range(max_retries):
        try:
            response = requests.post(
                url,
                headers=headers,
                json={"sequences": sequences},
                timeout=30
            )
            
            # Handle rate limiting
            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 60))
                print(f"Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                continue
            
            # Raise for other errors
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            
            # Exponential backoff
            wait_time = 2 ** attempt
            print(f"Error: {e}. Retrying in {wait_time}s...")
            time.sleep(wait_time)
    
    raise Exception("Max retries exceeded")

# Usage
try:
    results = classify_with_retry(sequences, "your_api_key")
    print(f"Successfully classified {len(results['results'])} sequences")
except Exception as e:
    print(f"Failed to classify: {e}")

🔒 API Key Security

• Never commit API keys to version control - Use environment variables or secure vaults
• Rotate keys regularly - Every 90 days recommended for production keys
• Use different keys for development and production - Create separate keys with labels
• Revoke keys immediately if compromised - Use the revoke endpoint
• Monitor key usage - Check the list endpoint for unexpected activity
• Store refresh tokens securely - They have a 30-day lifetime

1. Validate Sequences Before Sending

def is_valid_sequence(seq: str) -> bool:
    """Check if sequence contains only valid amino acids."""
    valid_aa = set("ACDEFGHIKLMNPQRSTVWY")
    return all(c in valid_aa for c in seq.upper())

# Filter invalid sequences
valid_sequences = [
    s for s in sequences 
    if is_valid_sequence(s["sequence"])
]

2. Use Batch Processing

• Group sequences into batches of 50 (free tier) or 100 (premium)
• Reduces API calls and improves throughput
• Faster overall processing time

3. Implement Caching

import hashlib
from functools import lru_cache

@lru_cache(maxsize=10000)
def get_classification(sequence: str) -> dict:
    """Cache results for identical sequences."""
    # Implementation here
    pass

4. Monitor Your Usage

# Check usage stats periodically
response = requests.get(
    "https://api.proteinclassifier.com/v1/stats",
    headers={"X-API-Key": api_key}
)

stats = response.json()
remaining = stats["remaining"]["sequences_today"]
print(f"Sequences remaining today: {remaining}")

5. Handle Rate Limits Gracefully

• Implement exponential backoff for 429 responses
• Respect Retry-After header
• Spread requests over time for large datasets
• Consider upgrading to premium for higher limits

How do I get an API key?

Use our self-service magic link authentication system:

1. Request a magic link with your email at POST /api/v1/auth/login
2. Verify the token from your email at POST /api/v1/auth/verify
3. Use your access token to create an API key at POST /api/v1/api-keys/register

See the Authentication section for detailed examples.

How do I rotate or revoke my API keys?

Use the API key management endpoints with your JWT access token:

• Rotate: POST /api/v1/api-keys/rotate - Creates new key and revokes old one
• Revoke: POST /api/v1/api-keys/revoke - Permanently deactivates a key
• List: GET /api/v1/api-keys/list - View all your keys and their status

See the API Key Management section for examples.

What's the difference between access tokens and API keys?

Access tokens (JWT): Used for managing your API keys. Short-lived (1 hour), obtained via magic link authentication.

API keys: Used for classification requests. Long-lived, created and managed through the API key management endpoints.

Refresh tokens: Used to get new access tokens without re-authentication. Valid for 30 days.

What amino acid codes are supported?

We support the 20 standard amino acids using single-letter codes: A, C, D, E, F, G, H, I, K, L, M, N, P, Q, R, S, T, V, W, Y. Sequences with other characters will be rejected.

Can I use this for commercial purposes?

Yes, with a premium or enterprise plan. The free tier is intended for academic research and testing only. Contact us for commercial licensing.

How accurate is the classifier?

Our classifier achieves 84.52% accuracy on PDB/DisProt test sets, >75% on homology-aware cross-validation, and >70% on independent MobiDB validation. See our methodology page for details.

What's the maximum sequence length?

We support sequences up to 10,000 amino acids. Most proteins are well below this limit. Very long sequences may have slightly longer processing times.

Do you offer per-residue predictions?

Not currently. Our API provides whole-protein binary classification (disordered vs. structured). Per-residue predictions are planned for a future release.

Can I run this locally/offline?

The API requires an internet connection. For offline use or on-premise deployment, contact us about our Enterprise plan which includes self-hosted options.

How is this different from AlphaFold?

AlphaFold predicts 3D structures (slow, GPU-intensive). We predict disorder (fast, CPU-only). Use our API for quick screening, then AlphaFold for detailed structure on structured proteins. See our comparison page.