# Causality Engine Developer Portal

> Causality Engine is a causal attribution API for e-commerce. It uses five peer-reviewed statistical models (Markov Chains, Shapley Values, Dominance Analysis, Relative Weight Analysis, PRAV) to calculate the true incremental impact of every marketing touchpoint. Not correlation. Causation.

## API Overview

Base URL: https://api.causalityengine.ai/v1
Sandbox URL: https://sandbox.causalityengine.ai/v1
Authentication: Bearer token (API key in Authorization header)
Key format: ce_live_sk_* (production), ce_test_sk_* (sandbox)

## Endpoints

### Attribution
- POST /v1/attribution - Run causal attribution analysis
- GET /v1/attribution/{id} - Get attribution result by ID
- GET /v1/attribution - List all attribution analyses

### Channel Performance
- GET /v1/channels/performance - Get channel performance metrics
- GET /v1/channels/amplification - Get cross-channel amplification effects
- GET /v1/channels/velocity - Get conversion velocity by channel

### Customer Journeys
- GET /v1/journeys/flow - Get customer journey flow analysis
- GET /v1/journeys/patterns - Get journey pattern intelligence
- GET /v1/journeys/value-matrix - Get journey value matrix

### Campaigns
- GET /v1/campaigns/overview - Get campaign overview metrics
- GET /v1/campaigns/contribution - Get revenue contribution by campaign
- GET /v1/campaigns/velocity - Get campaign velocity metrics

### Health Scores
- GET /v1/health/score - Get marketing health score
- GET /v1/health/diagnostics - Get health diagnostics breakdown

### Brand Awareness
- GET /v1/brand/decompose - Decompose direct traffic into brand vs non-brand
- GET /v1/brand/maturity - Get brand maturity score
- GET /v1/brand/links - Get structural link analysis

### Forecasting
- POST /v1/forecast - Generate revenue forecast
- GET /v1/forecast/{id} - Get forecast result

## SDKs

### Python
Install: pip install causality-engine
Usage:
```python
from causality_engine import Client
client = Client("ce_test_sk_...")
analysis = client.attribution.create(
    data_source_id="ds_8f3k2j",
    date_range=["2026-01-01", "2026-01-31"],
    model="causal"
)
```

### Node.js
Install: npm install @causalityengine/sdk
Usage:
```javascript
import CausalityEngine from '@causalityengine/sdk';
const ce = new CausalityEngine('ce_test_sk_...');
const analysis = await ce.attribution.create({
  dataSourceId: 'ds_8f3k2j',
  dateRange: ['2026-01-01', '2026-01-31'],
  model: 'causal'
});
```

## Authentication

All requests require a Bearer token in the Authorization header:
Authorization: Bearer ce_live_sk_...

Test keys (ce_test_sk_*) route to the sandbox and return synthetic data.
Live keys (ce_live_sk_*) route to production and require a connected data source.

## Rate Limits

- Standard: 100 requests/minute
- Pro: 500 requests/minute
- Enterprise: Custom

## Error Codes

All errors include a doc_url field linking to documentation:
- invalid_api_key: The API key is not valid
- expired_api_key: The API key has expired
- rate_limit_exceeded: Too many requests
- missing_nonce: State-changing requests require X-Nonce header
- insufficient_permissions: Key lacks required scope
- resource_not_found: The requested resource does not exist
- validation_error: Request body failed validation
- internal_error: Unexpected server error

## Links

- Documentation: https://developers.causalityengine.ai
- API Reference: https://developers.causalityengine.ai/api-reference
- Quickstart: https://developers.causalityengine.ai/quickstart
- SDKs: https://developers.causalityengine.ai/sdks
- Main Website: https://causalityengine.ai
- Status Page: https://status.causalityengine.ai
- GitHub: https://github.com/marketingupgrade/causalityengine