API Documentation

Enterprise

Build with MacroCade data. Programmatic access to scenarios, impacts, and opportunities via a clean REST API. An active Enterprise plan is required for all API access.

Getting Started

Authentication

Pass your API key in every request using the Authorization header.

Authorization: Bearer YOUR_API_KEY

Base URL

All API requests are made to the following base URL. Always use HTTPS.

https://api.macrocade.com

Rate Limits

Standard Enterprise: 1,000 req/min. Remaining quota is returned in every response header.

X-RateLimit-Remaining: 982
X-RateLimit-Reset: 1711186800

Endpoints

GET/api/v1/scenarios

Returns a paginated list of public scenarios. Supports filtering by category, market impact, and sort order.

Parameters

Name	Type	Required	Description
`category`	`string`	optional	Filter by category slug (e.g. geopolitical, energy, tech)
`market_impact`	`string`	optional	Filter by impact direction: bullish \| bearish \| neutral
`sort`	`string`	optional	Sort order: trending \| newest \| stars (default: trending)
`page`	`integer`	optional	Page number (default: 1)
`limit`	`integer`	optional	Results per page, max 100 (default: 20)

Example Response

{
  "data": [
    {
      "id": "scn_01hx9k3z2m",
      "slug": "fed-rate-hike-500bps",
      "title": "Fed raises rates to 5% — global liquidity shock",
      "category": "macro",
      "market_impact": "bearish",
      "stars": 1842,
      "created_at": "2026-03-01T12:00:00Z",
      "summary": "A 500bps rate hike triggers a global liquidity crunch..."
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 847,
    "pages": 43
  }
}

GET/api/v1/scenarios/trending

Returns the top 20 trending scenarios, ranked by a composite score of recent stars, views, and velocity.

Parameters

Name	Type	Required	Description
`limit`	`integer`	optional	Number of results to return, max 50 (default: 20)

Example Response

{
  "data": [
    {
      "id": "scn_01hx9k3z2m",
      "slug": "fed-rate-hike-500bps",
      "title": "Fed raises rates to 5% — global liquidity shock",
      "trend_score": 98.4,
      "stars": 1842,
      "views_24h": 14320
    }
  ],
  "meta": {
    "generated_at": "2026-03-23T08:00:00Z"
  }
}

GET/api/v1/scenarios/{slug}

Returns the full detail of a single scenario, including all impacts, opportunities, and related scenarios.

Parameters

Name	Type	Required	Description
`slug`	`string`	required	The unique scenario slug (path parameter)

Example Response

{
  "data": {
    "id": "scn_01hx9k3z2m",
    "slug": "fed-rate-hike-500bps",
    "title": "Fed raises rates to 5% — global liquidity shock",
    "category": "macro",
    "market_impact": "bearish",
    "stars": 1842,
    "summary": "A 500bps rate hike...",
    "key_insights": ["Liquidity crunch in EM debt...", "..."],
    "impacts": [
      {
        "id": "imp_001",
        "order": 1,
        "title": "US Treasury yields spike",
        "direction": "bearish",
        "asset_class": "fixed_income",
        "opportunities": [
          {
            "ticker": "TBT",
            "name": "ProShares UltraShort 20+ Year Treasury",
            "action": "buy",
            "rationale": "Inverse ETF benefits from rising long-duration yields"
          }
        ]
      }
    ],
    "related": ["japan-boj-yield-curve", "em-debt-crisis-2026"]
  },
  "meta": {}
}

POST/api/v1/scenarios

Submit a new scenario for AI analysis. Subject to daily rate limits (10/day default for Enterprise). A dedup check is performed automatically before processing.

Parameters

Name	Type	Required	Description
`title`	`string`	required	Short title for the scenario (max 160 chars)
`description`	`string`	required	Detailed description of the scenario trigger event (max 2000 chars)
`is_private`	`boolean`	optional	If true, scenario is only visible to your account (default: false)
`category`	`string`	optional	Optional category hint for the AI coordinator

Example Response

{
  "data": {
    "id": "scn_01hz3m7p9q",
    "status": "processing",
    "is_private": false,
    "estimated_completion_seconds": 45,
    "webhook_url": null
  },
  "meta": {
    "daily_remaining": 9
  }
}

POST/api/v1/scenarios/dedup-check

Check if a scenario is substantially similar to an existing one before submission. Returns the most similar scenario if similarity score exceeds 0.85.

Parameters

Name	Type	Required	Description
`title`	`string`	required	Proposed scenario title
`description`	`string`	required	Proposed scenario description

Example Response

{
  "data": {
    "is_duplicate": true,
    "similarity_score": 0.91,
    "existing_scenario": {
      "id": "scn_01hx9k3z2m",
      "slug": "fed-rate-hike-500bps",
      "title": "Fed raises rates to 5% — global liquidity shock",
      "url": "https://macrocade.com/scenario/fed-rate-hike-500bps"
    }
  },
  "meta": {}
}

GET/api/v1/scenarios/{id}/impacts

Returns the full list of impacts for a scenario, with optional filtering by asset class, direction, and order.

Parameters

Name	Type	Required	Description
`id`	`string`	required	Scenario ID (path parameter)
`asset_class`	`string`	optional	Filter by asset class: equities \| fixed_income \| commodities \| crypto \| fx \| real_estate
`direction`	`string`	optional	Filter by direction: bullish \| bearish \| neutral
`order`	`integer`	optional	Filter by cascade order: 1 \| 2 \| 3

Example Response

{
  "data": [
    {
      "id": "imp_001",
      "order": 1,
      "title": "US Treasury yields spike",
      "direction": "bearish",
      "asset_class": "fixed_income",
      "rationale": "...",
      "opportunities": [...]
    },
    {
      "id": "imp_002",
      "order": 2,
      "title": "EM currency depreciation",
      "direction": "bearish",
      "asset_class": "fx",
      "rationale": "...",
      "opportunities": [...]
    }
  ],
  "meta": {
    "total": 18,
    "visible": 18
  }
}

Response Format

All API responses follow a consistent envelope structure. The data field contains the requested resource or array of resources. The meta field contains pagination info, timestamps, and other contextual metadata.

// Single resource
{
  "data": { ... },
  "meta": {}
}

// Collection
{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 847,
    "pages": 43
  }
}

// Error
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after": 12
  }
}

Rate Limits

Plan	Requests / min	Scenario submissions / day	Notes
Enterprise Standard	1,000	10	Default plan
Enterprise Premium	Custom	Custom	Negotiated per contract

Ready to build?

API access requires an active Enterprise plan. Contact our team to get your API key and discuss custom rate limits.

View Enterprise pricing Contact sales