API Reference¶

CalcBridge provides a comprehensive REST API for programmatic access to all platform features. This reference documents all available endpoints, authentication methods, and data models.

Base URL¶

All API endpoints are relative to the base URL:

Production:  https://api.calcbridge.io/api/v1
Staging:     https://api-staging.calcbridge.io/api/v1
Development: http://localhost:8000/api/v1

API Versioning¶

The API version is included in the URL path (/api/v1). When breaking changes are introduced, a new version will be released while maintaining backward compatibility for existing versions.

Authentication¶

CalcBridge supports two authentication methods:

JWT Bearer Token¶

For user-facing applications. Obtain tokens via the /auth/login endpoint.

curl -X GET https://api.calcbridge.io/api/v1/workbooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

API Key¶

For service-to-service integrations. Create API keys in the dashboard or via the Admin API.

curl -X GET https://api.calcbridge.io/api/v1/workbooks \
  -H "X-API-Key: cb_live_a1b2c3d4e5f6..."

See Authentication API for complete details.

Rate Limiting¶

Rate limits vary by subscription tier and are applied per-tenant or per-API-key.

Rate Limit Headers¶

Every response includes rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1706200800

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "retry_after": 32
}

Error Response Format¶

All errors follow a consistent format:

{
  "detail": "Human-readable error message",
  "error_code": "SPECIFIC_ERROR_CODE",
  "request_id": "req_abc123xyz"
}

HTTP Status Codes¶

Common Error Codes¶

Pagination¶

List endpoints support cursor-based pagination:

GET /api/v1/workbooks?page=1&page_size=20

Request Parameters¶

Response Format¶

{
  "items": [...],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

Request Headers¶

*One of Authorization or X-API-Key is required.

Quick Links¶

Core APIs¶

Supporting APIs¶

Data Models¶

SDK Support¶

Official SDKs are available for common languages:

pip install calcbridge

from calcbridge import CalcBridgeClient

client = CalcBridgeClient(api_key="cb_live_...")
workbooks = client.workbooks.list()

npm install @calcbridge/sdk

import { CalcBridge } from '@calcbridge/sdk';

const client = new CalcBridge({ apiKey: 'cb_live_...' });
const workbooks = await client.workbooks.list();

curl -X GET https://api.calcbridge.io/api/v1/workbooks \
  -H "X-API-Key: cb_live_..."

OpenAPI Specification¶

The complete OpenAPI 3.0 specification is available at:

• Interactive Docs: https://api.calcbridge.io/docs
• ReDoc: https://api.calcbridge.io/redoc
• OpenAPI JSON: https://api.calcbridge.io/openapi.json

Changelog¶

v1.0.0 (Current)¶

• Initial stable release
• Authentication (JWT + API Key)
• Workbook management
• Formula evaluation
• What-if scenarios
• Compliance testing
• Report generation
• Alert management

Support¶

For API support, contact:

• Documentation Issues: GitHub Issues
• Technical Support: support@calcbridge.io
• Enterprise Support: enterprise@calcbridge.io