tellingCubetellingCube

API Documentation

Access your generated business data programmatically via our REST API. Perfect for testing, training, Power BI integration, Python scripts, or custom dashboards.

Raw Event DataCSV ExportJSON API

Base URL

$https://tellingcube.com/api/export

All endpoints return JSON. CORS is enabled for cross-origin requests.

🔓 Authentication

Current (PoC): No authentication required. Access is open.

Future versions will support API keys for secure access.

Endpoints

GET/api/export/{scenarioId}/finance.json

Returns aggregated finance data including P&L summary, monthly cash flow, cost breakdown, and margin analysis. Visualizations are inspired by IBCS© with AC, PY, PL, and FC comparisons.

Example Request

cURL
bash
curl https://tellingcube.com/api/export/abc12345-1234-5678-9abc-def012345678/finance.json

Response Structure

Response
json
{
  "plSummary": {
    "revenue": { "actual": 1234567, "previousYear": 1100000, "plan": 1300000, ... },
    "cogs": { "actual": 456789, ... },
    "payroll": { "actual": 234567, ... },
    "profit": { "actual": 543211, ... }
  },
  "monthlyCashFlow": [
    { "month": "2024-01-01", "cashIn": 123456, "cashOut": 98765, "netCash": 24691 },
    ...
  ],
  "costBreakdown": { "payroll": 234567, "payrollPercent": 19.0, ... },
  "marginAnalysis": { "grossMargin": 63.0, "netMargin": 44.0, ... }
}
GET/api/export/{scenarioId}/sales.json

Returns aggregated sales data including monthly revenue, product performance, top customers, and trend analysis. Includes variance data inspired by IBCS©.

Parameters

NameTypeDescription
topNintegerNumber of top customers to return (default: 10)

Example Request

cURL
bash
curl "https://tellingcube.com/api/export/abc12345-1234-5678-9abc-def012345678/sales.json?topN=5"

Response Structure

Response
json
{
  "revenueByMonth": [
    { "month": "2024-01-01", "revenue": 98765, "previousYear": 87654, "plan": 100000, ... },
    ...
  ],
  "revenueByProduct": [
    { "productId": "PROD-001", "revenue": 234567, "unitsSold": 1234, ... },
    ...
  ],
  "topCustomers": [
    { "counterpartyId": "CUST-001", "totalRevenue": 45678, "transactionCount": 23 },
    ...
  ],
  "trendAnalysis": { "avgGrowthRate": 5.2, "maxMonth": "2024-08", "minMonth": "2024-02" }
}
GET/api/export/{scenarioId}/hr.jsonWORKFORCE

Returns workforce analytics including headcount, tenure, turnover rates, salary distribution, and employee roster. All employee data is synthetically generated - no real individuals. Optional anonymization replaces names with Employee_001, etc.

Parameters

NameTypeDescription
anonymizebooleanReplace names with Employee_001, Employee_002, etc. (default: false)

Example Request

cURL
bash
curl "https://tellingcube.com/api/export/abc12345-1234-5678-9abc-def012345678/hr.json?anonymize=true"

Response Structure

Response
json
{
  "scenarioId": "abc12345-...",
  "exportedAt": "2024-03-15T10:30:00.000Z",
  "synthetic": true,
  "summary": {
    "headcount": 45,
    "avgTenure": 24,
    "turnoverRate": 12.5,
    "avgSalary": 4500,
    "totalPayroll": 202500,
    "genderDistribution": { "male": 25, "female": 18, "diverse": 2 }
  },
  "headcountByDepartment": [
    { "department": "Engineering", "count": 15, "percentage": 33.3 },
    ...
  ],
  "headcountByMonth": [
    { "month": "2024-01", "headcount": 42, "hires": 3, "terminations": 1, "netChange": 2 },
    ...
  ],
  "salaryByDepartment": [
    { "department": "Engineering", "avgSalary": 5200, "minSalary": 4000, "maxSalary": 7500, "headcount": 15, "totalPayroll": 78000 },
    ...
  ],
  "turnoverByMonth": [
    { "month": "2024-01", "turnoverRate": 2.4, "hires": 3, "terminations": 1 },
    ...
  ],
  "employees": [
    { "id": "emp-001", "name": "Employee_001", "department": "Engineering", "role": "Developer", "salary": 5000, ... },
    ...
  ]
}
GET/api/export/{scenarioId}/hr.csvDOWNLOAD

Download employee roster as CSV file. Opens directly in Excel or any spreadsheet tool. Includes synthetic employee data (names, departments, roles, salaries, tenure). All data is AI-generated - no real individuals.

Parameters

NameTypeDescription
anonymizebooleanReplace names with Employee_001, Employee_002, etc.

Example Request

cURL
bash
curl -O "https://tellingcube.com/api/export/abc12345-1234-5678-9abc-def012345678/hr.csv?anonymize=true"

CSV Columns

Employee IDNameDepartmentRoleLevelMonthly Salary (EUR)Hire DateGenderBirth YearTenure (Months)
GET/api/export/{scenarioId}/events.jsonRAW DATA

Returns all raw business events - the foundation of tellingCube data. Perfect for testing, training ML models, or building custom analytics. Each event represents an atomic business transaction (sale, payment, hire, etc.).

Parameters

NameTypeDescription
eventTypestringFilter by event type (e.g., "sale", "payroll_payment")
timePeriodstringFilter by period (e.g., "2024-01")

Example Request

cURL
bash
curl "https://tellingcube.com/api/export/abc12345-1234-5678-9abc-def012345678/events.json?eventType=sale"

Response Structure

Response
json
{
  "scenarioId": "abc12345-1234-5678-9abc-def012345678",
  "eventCount": 1234,
  "events": [
    {
      "id": "event-uuid",
      "eventType": "sale",
      "eventDate": "2024-03-15T00:00:00.000Z",
      "timePeriod": "2024-03",
      "productId": "PROD-001",
      "productGroup": "Electronics",
      "counterpartyId": "CUST-042",
      "region": "Vienna",
      "amountEur": 1234.56,
      "quantity": 10,
      "unitPrice": 123.46,
      "metadata": { ... }
    },
    ...
  ]
}
GET/api/export/{scenarioId}/events.csvDOWNLOAD

Download all raw events as CSV file. Opens directly in Excel, Google Sheets, or any data analysis tool. Same data as the JSON endpoint, in tabular format.

Parameters

NameTypeDescription
eventTypestringFilter by event type
timePeriodstringFilter by period

Example Request

cURL
bash
curl -O "https://tellingcube.com/api/export/abc12345-1234-5678-9abc-def012345678/events.csv"

CSV Columns

Event IDEvent TypeEvent DateTime PeriodOrganization UnitProduct IDProduct GroupCounterparty IDRegionCost CenterAsset IDAmount (EUR)QuantityUnit Price (EUR)Notable Event

Error Codes

CodeHTTP StatusDescription
INVALID_SCENARIO_ID400scenarioId is not a valid UUID
SCENARIO_NOT_FOUND404Scenario does not exist or has no data
QUERY_ERROR500Internal server error

Usage Examples

Python
python
import requests
import pandas as pd

SCENARIO_ID = "abc12345-1234-5678-9abc-def012345678"
BASE_URL = "https://tellingcube.com/api/export"

# Get raw events (best for ML/testing)
events = requests.get(f"{BASE_URL}/{SCENARIO_ID}/events.json").json()
print(f"Total Events: {events['eventCount']}")

# Or download as CSV for pandas
df = pd.read_csv(f"{BASE_URL}/{SCENARIO_ID}/events.csv")
print(df.groupby('Event Type')['Amount (EUR)'].sum())

# Get aggregated finance/sales data
finance = requests.get(f"{BASE_URL}/{SCENARIO_ID}/finance.json").json()
print(f"Total Revenue: EUR {finance['plSummary']['revenue']['actual']:,}")

# Get workforce/HR data (with anonymization)
hr = requests.get(f"{BASE_URL}/{SCENARIO_ID}/hr.json?anonymize=true").json()
print(f"Headcount: {hr['summary']['headcount']}, Turnover: {hr['summary']['turnoverRate']}%")
JavaScript
javascript
const SCENARIO_ID = "abc12345-1234-5678-9abc-def012345678";
const BASE_URL = "https://tellingcube.com/api/export";

// Get raw events (best for testing/training)
const events = await fetch(`${BASE_URL}/${SCENARIO_ID}/events.json`)
  .then(res => res.json());

console.log(`Total Events: ${events.eventCount}`);

// Filter by event type
const sales = events.events.filter(e => e.eventType === 'sale');
console.log(`Sale Events: ${sales.length}`);

// Get aggregated finance data
const finance = await fetch(`${BASE_URL}/${SCENARIO_ID}/finance.json`)
  .then(res => res.json());

console.log(`Total Revenue: EUR ${finance.plSummary.revenue.actual.toLocaleString()}`);

// Get workforce/HR data (with anonymization)
const hr = await fetch(`${BASE_URL}/${SCENARIO_ID}/hr.json?anonymize=true`)
  .then(res => res.json());

console.log(`Headcount: ${hr.summary.headcount}, Avg Salary: EUR ${hr.summary.avgSalary}`);

📊 Power BI Integration

Use Get Data - Web and enter the API URL. Power BI will automatically parse the JSON response. For refreshable reports, use Web.Contents with the API URL.

📐 About Scenario Notation (inspired by IBCS©)

Our data uses scenario notation inspired by IBCS© (International Business Communication Standards):

AC

Actual

Current year actual figures (2024)

PY

Previous Year

Last year actual figures (2023)

PL

Plan

Ambitious budget targets set before the period

FC

Forecast

Realistic expectations updated during the period

← Back to My Scenarios