Authentication

You'll need to authenticate your requests to access protected endpoints in the Schedule Intelligence APIs. In this guide, we'll look at how authentication works using API keys.

API key authentication

To authenticate with the Schedule Intelligence APIs, pass your API key via the x-api-key header. All requests require authentication for rate limiting and usage tracking.

curl -X POST "https://api.bellatorsi.com/api/v1/health/score" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"tasks": [{"id": "1", "duration_days": 5, "predecessors": []}]}'

Don't have an API key yet? Use the Playground to get a free ephemeral key that's valid for 24 hours or 100 requests.

Tier-based access

API keys are associated with access tiers that control limits:

Playground/Ephemeral Tier:
- Task limit: 100 tasks per request
- Rate limit: 100 requests per ephemeral key
- Async processing: ❌ Synchronous only
- Payload size: 5MB max
- API key: Get an ephemeral key from Playground (auto-expires after 24h or 100 uses)
- Best for: Instant testing, no signup required
Free Tier:
- Task limit: 1,000 tasks per request
- Rate limit: 100 requests per month
- Async processing: ❌ Synchronous only (1,000 tasks = sync limit)
- Payload size: 5MB max
- Best for: Development and small projects
Starter Tier:
- Task limit: 2,000 tasks per request
- Rate limit: 500 requests per month
- Async processing: ✅ Required for tasks 1,001-2,000
- Payload size: 5MB max
- Best for: Small teams and early-stage products
Professional Tier:
- Task limit: 5,000 tasks per request
- Rate limit: 2,000 requests per month
- Async processing: ✅ Async + Sync
- Payload size: 25MB max
- Best for: Production applications
Enterprise Tier:
- Task limit: 50,000 tasks per request
- Rate limit: Unlimited
- Async processing: ✅ Priority async queue
- Payload size: 100MB max
- Best for: Large organizations
Government Tier:
- Task limit: 100,000+ tasks per request
- Rate limit: Unlimited
- Async processing: ✅ Priority async queue
- Payload size: 500MB max
- Best for: Government contracts (DCMA compliance)

Querying your tier at runtime

Use GET /api/v1/account/tier to get the exact limits and capability flags for the authenticated key. This endpoint is quota-neutral — it does not count against your monthly call limit and is safe to call at startup or cache for 30–120 seconds.

curl "https://api.bellatorsi.com/api/v1/account/tier" \
  -H "x-api-key: YOUR_API_KEY"

import httpx

r = httpx.get(
    "https://api.bellatorsi.com/api/v1/account/tier",
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = r.json()

print(data["tier"])                             # "starter"
print(data["limits"]["max_task_limit"])         # 2000
print(data["capabilities"]["forensics"])        # True
print(data["limits"]["monthly_calls_remaining"]) # 347

const res = await fetch("https://api.bellatorsi.com/api/v1/account/tier", {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const { tier, limits, capabilities } = await res.json();

console.log(tier);                            // "starter"
console.log(limits.max_task_limit);           // 2000
console.log(capabilities.forensics);          // true
console.log(limits.monthly_calls_remaining);  // 347

The response includes a capabilities object with boolean flags for each feature group, and a limits object with numeric task and quota limits. Use these to gate features or decide whether to route large payloads to async endpoints.

{
  "tier": "starter",
  "display_name": "API Starter",
  "limits": {
    "sync_task_limit": 1000,
    "max_task_limit": 2000,
    "payload_limit_mb": 5,
    "api_calls_per_month": 500,
    "monthly_calls_remaining": 347
  },
  "capabilities": {
    "tier1": true,
    "forensics": true,
    "import": true,
    "risk": false,
    "async": true,
    "webhooks": true,
    "sandbox_fixture_requests": true
  },
  "recommended_routes": {
    "health_score": "/api/v1/health/score",
    "dcma_14_point": "/api/v1/health/dcma-14-point",
    "async_jobs": "/api/v1/jobs/{job_id}"
  },
  "metadata": {
    "resolved_at": "2026-04-07T14:22:31Z",
    "api_version": "0.2.0"
  }
}

Rate limiting

When you exceed your tier's rate limit, you'll receive a 429 Too Many Requests response:

{
  "detail": "Rate limit exceeded: 100 requests per 60 seconds. Retry after 45 seconds.",
  "retry_after": 45
}

The response includes a Retry-After header indicating when you can retry.

Rate limit headers

All responses include rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1738195200

Task limits

Requests exceeding your tier's task limit will be rejected:

{
  "detail": "Task count 3000 exceeds tier limit of 2000. Upgrade to Professional tier or use async processing."
}

For schedules exceeding your sync processing limit, use the async endpoints with webhooks.

Security best practices

Never commit API keys: Use environment variables or secret managers
Rotate keys regularly: Especially if compromised
Use HTTPS: Always use encrypted connections in production
Tier appropriately: Choose the right tier for your workload
Monitor usage: Track API usage to prevent unexpected rate limits

Getting an API key

API keys are provisioned through self-service signup:

Free tier — Sign up at bellatorsi.com/signup. No credit card required. Keys are issued immediately after account creation.
Starter tier ($29/mo) — Subscribe at bellatorsi.com/signup?plan=starter. Stripe checkout, key provisioned automatically on payment confirmation.
Professional, Enterprise, Government — Contact us for provisioning.

Once you have a key, store it securely:

# Set as environment variable — never hardcode in source
export BELLATOR_API_KEY="bsi_live_..."

import os
api_key = os.environ["BELLATOR_API_KEY"]