Skip to content
Alpine DataWorks
Agent Access

Intelligence, native.

Alpine DataWorks is built for the agent era. Our API is MCP-native, returning the answer and its reasoning in a single, typed call. No scraping, no parsing—just structured intelligence.

The Answer + Reasoning

One call returns the full Intelligence Object Model (IOM). Your agent gets the score, the drivers, the confidence, and the metadata—ready for consumption.

GET /v1/intelligence/adw-002
{
  "product_id": "ADW-002",
  "entity": "US",
  "score": 68,
  "trend": "stable",
  "confidence": 0.92,
  "top_drivers": [
    {
      "factor": "GDP Growth",
      "contribution": 0.4
    },
    {
      "factor": "Unemployment Rate",
      "contribution": 0.35
    }
  ],
  "prediction_horizon": "3m",
  "recommended_use": "Macro asset allocation",
  "methodology_version": "v3.0",
  "freshness": "2026-06-01T06:00:00Z",
  "coverage": "National",
  "health_score": 68,
  "inflation_pressure": "moderate",
  "labor_market_status": "tight",
  "growth_momentum": "positive",
  "data_lag_days": 2,
  "source_lineage": [
    "FRED",
    "BLS",
    "BEA"
  ],
  "allowed_use": "evaluation, commercial"
}

MCP & OpenAPI

We provide standard tool definitions for Model Context Protocol (MCP) and a clean OpenAPI spec. Agents can discover and invoke ADW objects without custom adapters.

MCP Tool Definition

json
{
  "name": "adw.adw_002",
  "description": "Retrieve the latest macro intelligence score for a specific entity (e.g., US, EU, JP). Returns the score, trend, drivers, and confidence interval.",
  "parameters": {
    "type": "object",
    "properties": {
      "entity": {
        "type": "string",
        "description": "ISO 3166-1 alpha-3 country code"
      },
      "product_id": {
        "type": "string",
        "default": "ADW-002"
      }
    },
    "required": [
      "entity"
    ]
  },
  "returns": {
    "type": "object",
    "description": "The full IOM object including score, drivers, and metadata."
  }
}

OpenAPI Sketch

yaml
paths:
  /v1/intelligence/{product_id}:
    get:
      summary: "Get intelligence score"
      parameters:
        - name: product_id
          in: path
          required: true
          schema: { type: string }
        - name: entity
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: "The Intelligence Object Model (IOM)"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntelligenceObject'

The Intelligence Object Model (IOM)

The IOM is a strict, typed schema. Every response contains these 13 fields, ensuring your agent always knows what to expect.

product_id
Identifier for the intelligence product.
entity
The ISO code of the entity (e.g., US, EU).
score
The primary intelligence score (0-100).
trend
Directional trend: stable, rising, falling.
confidence
Confidence interval (0-1) of the score.
top_drivers
Key factors driving the score.
prediction_horizon
Time horizon for the prediction.
recommended_use
Suggested use case for the score.
methodology_version
Version of the methodology used.
freshness
Timestamp of the last data update.
coverage
Geographic or sector coverage.
source_lineage
Upstream data sources contributing to this object.
allowed_use
Permitted use cases and redistribution rules.
json
[
  "product_id",
  "entity",
  "score",
  "trend",
  "confidence",
  "top_drivers",
  "prediction_horizon",
  "recommended_use",
  "methodology_version",
  "freshness",
  "coverage",
  "source_lineage",
  "allowed_use"
]

Agent Discovery

Agents can discover available products via our standard discovery endpoints. Use /llms.txt for a human-readable list, or /catalog.json for machine-readable discovery.

Discover via Catalog

bash
curl -s https://api.alpinedataworks.ai/v1/catalog.json | jq '.products[] | select(.id == "ADW-002")'

Authentication

We support two distinct authentication flows: Human (OAuth2/SSO) and Agent (Service Tokens).

Human Access

  • OAuth2 / SSO via dashboard
  • Full UI access
  • Requires email verification

Agent Access

  • Service Tokens (Bearer)
  • Self-register via API
  • Scoped to API endpoints
  • No credit card required for Free tier

Note: Platinum tier requires a human sponsor to approve a machine identity.

Error Codes

Standard HTTP error codes with actionable messages.

Code Meaning What to do
429 Rate limit exceeded Respect Retry-After header. Upgrade tier for higher limits.
404 Entity not found Check /catalog.json for valid entity codes.
500 Internal server error Retry after 60s. If persistent, contact support.
503 Source data unavailable Request cached data (older but available).

SDK Examples

Quick start examples for Python and JavaScript.

Python (LangChain)

python
import requests

def get_adw_score(entity: str, token: str) -> dict:
    headers = {"Authorization": f"Bearer {token}"}
    resp = requests.get(
        "https://api.alpinedataworks.ai/v1/intelligence/ADW-002",
        params={"entity": entity},
        headers=headers
    )
    resp.raise_for_status()
    return resp.json()

# Usage in LangChain tool
from langchain.tools import tool

@tool
def get_macro_score(entity: str) -> str:
    """Get the latest macro score for a country."""
    data = get_adw_score(entity, "YOUR_TOKEN")
    return f"Score: {data['score']}, Trend: {data['trend']}"

Python (LlamaIndex FunctionTool)

python
import requests
from llama_index.core.tools import FunctionTool

def adw_get_iom(entity: str, token: str = "YOUR_TOKEN") -> dict:
    """Retrieve the ADW Intelligence Object Model for a given entity code (e.g. US, EU, JP)."""
    resp = requests.get(
        "https://api.alpinedataworks.ai/v1/intelligence/ADW-002",
        params={"entity": entity},
        headers={"Authorization": f"Bearer {token}"},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()  # full IOM: score, trend, top_drivers, confidence, etc.

adw_tool = FunctionTool.from_defaults(fn=adw_get_iom)

# Pass to any LlamaIndex agent
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

agent = ReActAgent.from_tools([adw_tool], llm=OpenAI(model="gpt-4o"), verbose=True)
response = agent.chat("What is the macro outlook for the EU?")

JavaScript (Fetch)

javascript
const getAdwScore = async (entity, token) => {
  const res = await fetch(
    `https://api.alpinedataworks.ai/v1/intelligence/ADW-002?entity=${entity}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  if (!res.ok) throw new Error(res.statusText);
  return res.json();
};

// Usage
const score = await getAdwScore("US", "YOUR_TOKEN");
console.log(`Score: ${score.score}`);

Ready to integrate?