Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

Authorization: Bearer <access_token>

​
Dataset lifecycle

POST /datasets        → status: "draft"
POST /datasets/{id}/build  → status: "building" → "ready" (or "error")
GET  /datasets/{id}/preview  → first 100 rows from IOMETE
GET  /datasets/{id}/lineage  → source tables + transforms applied

​
Create dataset spec

Define what tables to pull from, how to join them, and what filters to apply. This does not execute immediately — call /build to trigger the Spark job.

​
Request body

FieldTypeDescription
namestringDataset name (used as Iceberg table name)
descriptionstringOptional description
source_tablesarrayIOMETE Iceberg tables [{table, alias, columns}]
filtersarrayRow filters [{column, op, value}]
joinsarrayTable joins [{left_table, right_table, left_col, right_col}]
graph_featuresarrayFalkorDB features [{label, cypher_fragment, output_column}]
realtime_colsarrayQuestDB aggregations [{questdb_table, column, agg, window}]
curl -X POST https://api.ivory.finance/v1/foundry/datasets \
  -H "Authorization: Bearer $IVORY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "semiconductor_signals",
    "description": "Semiconductor companies with revenue, ESG, and insider trading signals",
    "source_tables": [
      { "table": "company_snapshots",     "alias": "c" },
      { "table": "financial_statements",  "alias": "f" }
    ],
    "joins": [
      {
        "left_table":  "company_snapshots",
        "right_table": "financial_statements",
        "left_col":    "cik",
        "right_col":   "cik"
      }
    ],
    "filters": [
      { "column": "c.sector_slug", "op": "=", "value": "semiconductors" },
      { "column": "f.fiscal_year", "op": ">=", "value": "2022" }
    ]
  }'

{
  "id": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "output_table": "foundry_semiconductor_signals",
  "status": "draft"
}

​
Build dataset

Triggers a Spark SQL job on IOMETE that materialises the spec as an Iceberg table in your tenant namespace. Returns immediately — the job runs asynchronously. Poll GET /datasets to check status. 
curl -X POST https://api.ivory.finance/v1/foundry/datasets/3f7a1b2c-.../build \
  -H "Authorization: Bearer $IVORY_JWT"

{
  "id": "3f7a1b2c-...",
  "status": "ready",
  "output_table": "foundry_semiconductor_signals",
  "sql": "CREATE TABLE IF NOT EXISTS ivory_tenant_acme.foundry_semiconductor_signals USING iceberg AS SELECT * FROM ivory_tenant_acme.company_snapshots AS c LEFT JOIN ivory_tenant_acme.financial_statements f ON c.cik = f.cik WHERE c.sector_slug = 'semiconductors'"
}

​
List datasets

curl https://api.ivory.finance/v1/foundry/datasets \
  -H "Authorization: Bearer $IVORY_JWT"

{
  "datasets": [
    {
      "id": "3f7a1b2c-...",
      "name": "semiconductor_signals",
      "description": "Semiconductor companies with financials",
      "output_table": "foundry_semiconductor_signals",
      "row_count": 8412,
      "status": "ready",
      "created_at": "2026-03-25T10:00:00Z",
      "last_built_at": "2026-03-25T10:03:42Z"
    }
  ]
}

​
Preview dataset

Returns the first 100 rows from the materialised Iceberg table. 
curl https://api.ivory.finance/v1/foundry/datasets/3f7a1b2c-.../preview \
  -H "Authorization: Bearer $IVORY_JWT"

​
Dataset lineage

Shows exactly what source tables and transformations produced this dataset. 
curl https://api.ivory.finance/v1/foundry/datasets/3f7a1b2c-.../lineage \
  -H "Authorization: Bearer $IVORY_JWT"

{
  "dataset": "semiconductor_signals",
  "output": "foundry_semiconductor_signals",
  "sources": {
    "iomete_tables": [
      { "table": "company_snapshots",    "alias": "c" },
      { "table": "financial_statements", "alias": "f" }
    ],
    "graph_features": [],
    "realtime_cols": []
  },
  "transforms": {
    "filters": [
      { "column": "c.sector_slug", "op": "=", "value": "semiconductors" }
    ],
    "joins": [
      {
        "left_table": "company_snapshots",
        "right_table": "financial_statements",
        "left_col": "cik",
        "right_col": "cik"
      }
    ]
  }
}