API Documentation

Complete reference for the Marlowe Macro Binder REST API

Quick Start

1Get API Key

Create an API key from the API Keys page

2Add Header

Include X-API-Key header in requests

3Make Requests

Call any endpoint below to get macro data

Example Request

curl -H "X-API-Key: YOUR_API_KEY" https://your-domain.com/api/v1/regime

Authentication

All API requests require authentication using an API key. Include your key in one of these ways:

Header (Recommended)

X-API-Key: mk_live_xxxxx...

Query Parameter

?api_key=mk_live_xxxxx...

Endpoints

Charts

Economic Indicators

Regime Analysis

Market Data

Batch Endpoints

API Info

GET/api/v1/charts

List all available charts

Response

{
  "success": true,
  "data": [
    {
      "id": "gdp",
      "title": "Real GDP Growth",
      "category": "growth",
      "source": "FRED",
      "frequency": "quarterly"
    },
    ...
  ],
  "meta": {
    "timestamp": "2024-01-10T12:00:00Z",
    "count": 45
  }
}

Code Examples

curl -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://your-domain.com/api/v1/charts"

Rate Limits

1,000

Default requests/hour

10,000

Maximum requests/hour

60 min

Rate limit window

Rate limits are applied per API key. Check the /api/v1/info endpoint for your current usage.

Webhook Signature Verification

Verify that webhook payloads are authentic and haven't been tampered with

All webhook deliveries include a signature in the X-Webhook-Signature header. This signature is an HMAC-SHA256 hash of the request body using your webhook secret.

Signature Header Format

X-Webhook-Signature: sha256=abc123...

Security Note: Always verify webhook signatures before processing payloads to prevent spoofing attacks.

Verification Examples

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  // Extract the signature from the header
  const expectedSignature = signature.replace('sha256=', '');
  
  // Compute the HMAC-SHA256 hash
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );
}

// Express.js middleware example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const payload = JSON.parse(req.body);
  // Process the webhook...
  res.json({ received: true });
});

Webhook Payload Structure

{
  "id": "whd_abc123",
  "event": "regime.changed",
  "timestamp": "2024-01-10T12:00:00Z",
  "data": {
    "previousRegime": "expansion",
    "currentRegime": "slowdown",
    "confidence": 0.85,
    "indicators": {
      "gdp": 1.2,
      "unemployment": 4.1,
      "inflation": 3.2
    }
  }
}

Supported Events

Event	Description
`regime.changed`	Triggered when the economic regime transitions
`indicator.threshold`	Triggered when an indicator crosses a configured threshold
`market.alert`	Triggered for significant market events (VIX spike, yield curve inversion)

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong