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>

​
How it works

  1. Foundry fetches your tenant’s full table catalog (IOMETE + QuestDB + Postgres)
  2. GPT-4o-mini translates your question into a SQL or Cypher query targeting the right backend
  3. The query executes with tenant isolation enforced
  4. A second LLM call synthesises a 1-3 sentence business narrative from the results
Queries are always read-only — no INSERT, UPDATE, DELETE, or DDL is ever generated.

​
Request body

FieldRequiredDefaultDescription
questionYes—Natural language question
contextNo[]Prior conversation turns [{role, content}] — up to 4 turns used
sourcesNo[]Hint preferred backends: ["iomete", "questdb", "falkordb"]. Auto-detected if empty
curl -X POST https://api.ivory.finance/v1/foundry/query \
  -H "Authorization: Bearer $IVORY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What were Apple'\''s top 3 revenue segments by growth in FY2024?"
  }'

{
  "question": "What were Apple's top 3 revenue segments by growth in FY2024?",
  "plan": {
    "target": "iomete",
    "sql": "SELECT segment_name, revenue_usd_millions, yoy_growth_pct FROM ivory_tenant_acme.revenue_breakdowns WHERE ticker='AAPL' AND fiscal_year=2024 ORDER BY yoy_growth_pct DESC LIMIT 3",
    "explanation": "Returns the top 3 Apple revenue segments ranked by year-over-year growth in FY2024"
  },
  "columns": ["segment_name", "revenue_usd_millions", "yoy_growth_pct"],
  "result": [
    ["Services",   85200, 14.2],
    ["Mac",        29800,  7.1],
    ["Wearables",  39800,  3.8]
  ],
  "row_count": 3,
  "narrative": "Apple's Services segment led growth at 14.2% YoY in FY2024, driven by App Store and iCloud subscriptions. Mac returned to growth at 7.1% after a weak FY2023. Wearables grew modestly at 3.8%.",
  "duration_ms": 1240.5,
  "error": null
}

​
Multi-turn conversation

Pass prior turns in context to enable follow-up questions: 
# Turn 1
result1 = client.post("/v1/foundry/query", json={
    "question": "Which semiconductor companies have the highest R&D spend?",
})

# Turn 2 — follow-up with context
result2 = client.post("/v1/foundry/query", json={
    "question": "Now filter to only those with positive free cash flow",
    "context": [
        {"role": "user",      "content": "Which semiconductor companies have the highest R&D spend?"},
        {"role": "assistant", "content": result1.json()["narrative"]},
    ],
})

​
Schema endpoint

Before querying, you can inspect what tables are available: 
GET /v1/foundry/schema
Returns your full table catalog across IOMETE, QuestDB, and Postgres read-models.