API Reference

REST API for programmatic access to takeaways, research, and documents.

Getting Started

All API requests require an API key. Generate one on the API Keys page, then include it in every request:

Authorization: Bearer esak_<your-key>

Example

curl -H "Authorization: Bearer esak_<your-key>" \
     https://expert-system.starmode.dev/api/v1/takeaways/recent

A missing or invalid key returns 401 Unauthorized. Revoked keys are rejected immediately.

Machine-readable docs

A plain-text Markdown version of this documentation is available for AI agents — no authentication required. Point your agent at this URL to ingest the full API reference:

curl https://expert-system.starmode.dev/api/v1/docs

Endpoints

GET/api/v1/takeaways/recent

Recent Takeaways

Returns the most recent takeaways ordered by publication date (newest first).

Query parameters

Parameter	Type	Required	Description
limit	number	optional	Number of takeaways to return. Default: 10. Max: 100.

Response

{
  "items": [ TakeawayObject, ... ]
}

Takeaway object

Field	Type	Description
id	string	Takeaway unique identifier.
documentId	string	ID of the source document.
title	string	Short headline summarising the takeaway.
summary	string	Brief summary of the takeaway.

Example request

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/takeaways/recent?limit=5"

Example response

{
  "items": [
    {
      "id": "tak_abc123",
      "documentId": "doc_xyz789",
      "title": "Fed signals pause through Q2",
      "summary": "The Federal Reserve indicated it will hold rates..."
    }
  ]
}

GET/api/v1/takeaways

Takeaways by ID

Fetch up to 50 takeaways by ID with full details, document metadata, and inline references.

Query parameters

Parameter	Type	Required	Description
ids	string	required	Comma-separated list of takeaway IDs. Maximum 50 IDs per request.

Response

{
  "items": [ TakeawayObject, ... ]
}

Takeaway object

Field	Type	Description
id	string	Unique identifier.
title	string	Short headline summarising the takeaway.
takeaway	string	Full takeaway text — the actionable or notable finding.
url	string	Link to the takeaway on expert-system.
document	object	Source document metadata: id, title, source, link, publicationDate.
takeawayReferences	array	Ordered list of inline references. Each entry has referenceNumber (integer) and reference (string).

Example request

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/takeaways?ids=tak_abc123,tak_def456"

Example response

{
  "items": [
    {
      "id": "tak_abc123",
      "title": "Fed signals pause through Q2",
      "takeaway": "The Federal Reserve indicated it will hold rates...",
      "url": "https://expert-system.starmode.dev/takeaway/tak_abc123",
      "document": {
        "id": "doc_xyz789",
        "title": "Remarks on the Economic Outlook",
        "source": "Fed Speeches",
        "link": "https://www.federalreserve.gov/...",
        "publicationDate": "2026-03-01T00:00:00.000Z"
      },
      "takeawayReferences": [
        { "referenceNumber": 1, "reference": "Federal Reserve Press Release, Jan 2026" }
      ]
    }
  ]
}

GET/api/v1/takeaways/search

Takeaway Search

Semantic search across all takeaways using vector similarity, with optional time-weighted reranking.

Query parameters

Parameter	Type	Required	Description
query	string	required	Natural-language search query.
limit	number	optional	Number of results to return. Default: 10. Max: 100.
recent	string	optional	Set to "true" to apply time-weighted reranking that favours newer content.

Response

{
  "items": [ SearchResultObject, ... ]
}

Search result object

Field	Type	Description
id	string	Takeaway unique identifier.
documentId	string	ID of the source document.
title	string	Short headline summarising the takeaway.
summary	string	Brief summary of the takeaway.

Example request

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/takeaways/search?query=inflation+expectations&limit=5"

Example request — time-weighted

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/takeaways/search?query=inflation+expectations&recent=true"

Example response

{
  "items": [
    {
      "id": "tak_abc123",
      "documentId": "doc_xyz789",
      "title": "Inflation expectations remain anchored",
      "summary": "Long-term inflation expectations hold steady near 2%..."
    }
  ]
}

GET/api/v1/documents

Documents by ID

Fetch up to 50 source documents by ID, including full article text and metadata.

Query parameters

Parameter	Type	Required	Description
ids	string	required	Comma-separated list of document IDs. Maximum 50 IDs per request.

Response

{
  "items": [ DocumentObject, ... ]
}

Document object

Field	Type	Description
id	string	Unique identifier.
source	string	Origin of the document, e.g. "a16z", "Fed Speeches", "MacroVoices".
title	string	Document title.
description	string	Short description or abstract of the document.
publicationDate	string (ISO 8601)	When the document was originally published.
link	string	URL to the original source.
articleText	string	Full plain-text body of the document.
isSubstantive	boolean	Whether the document contains enough content to be worth processing.
createdAt	string (ISO 8601)	When the document was ingested.
updatedAt	string (ISO 8601)	When the document record was last updated.

Example request

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/documents?ids=doc_xyz789,doc_abc123"

Example response

{
  "items": [
    {
      "id": "doc_xyz789",
      "source": "Fed Speeches",
      "title": "Remarks on the Economic Outlook",
      "description": "Governor Powell discusses the path of inflation...",
      "publicationDate": "2026-03-01T00:00:00.000Z",
      "link": "https://www.federalreserve.gov/...",
      "articleText": "Thank you for the opportunity to speak...",
      "isSubstantive": true,
      "createdAt": "2026-03-01T08:15:00.000Z",
      "updatedAt": "2026-03-01T08:15:00.000Z"
    }
  ]
}

GET/api/v1/research

Research

AI-generated research insights scoped to the API key owner. Supports cursor pagination and date filtering.

Query parameters

Parameter	Type	Required	Description
cursor	string	optional	Opaque pagination cursor from the previous response's nextCursor field. Omit to start from the beginning.
limit	number	optional	Items per page. Default: 4. Max: 100.
date	string	optional	Filter to a single day in YYYY-MM-DD format (UTC). Returns only research created on that date.

Response

{
  "items": [ ResearchObject, ... ],
  "nextCursor": "<string> | null"
}

Research object

Field	Type	Description
id	string	Unique identifier.
title	string	Title of the research insight.
summary	string \| null	Short summary of the insight's main finding.
insight	string \| null	Full insight text. Only insights with a non-null value are returned.
research	string \| null	Background research notes used to generate the insight.
url	string	Link to the research insight on expert-system.
takeaways	array	Takeaways linked to this insight. Each entry has id and title.
createdAt	string (ISO 8601)	When the insight was created.
updatedAt	string (ISO 8601)	When the insight was last updated.

Cursor pagination

Pass the opaque nextCursor value from a response as the cursor parameter on the next request. When nextCursor is null, you have reached the last page. Do not parse or construct cursor values — treat them as opaque strings.

Example request

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/research?limit=10"

Example request — filter by date

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/research?date=2026-03-05"

Example response

{
  "items": [
    {
      "id": "ins_def456",
      "title": "Rate cycle and tech valuations",
      "summary": "Rising rates historically compress growth multiples...",
      "insight": "Analysis shows a strong inverse correlation between...",
      "research": null,
      "url": "https://expert-system.starmode.dev/insight/ins_def456",
      "takeaways": [
        { "id": "tak_abc123", "title": "Fed signals pause through Q2" }
      ],
      "createdAt": "2026-03-05T14:30:00.000Z",
      "updatedAt": "2026-03-05T14:30:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/api/v1/query/macro

Query Macro Data

Natural language interface for macroeconomic data. An AI agent translates your question into FRED API calls and returns structured data.

Available data

Ask about any of the series below using plain English — the agent resolves series IDs automatically.

Growth / Real Economy: Real GDP, Industrial Production, Capacity Utilization, Real Personal Consumption, Real Business Fixed Investment.

Labor Market: Unemployment Rate, Labor Force Participation, Employment-Population Ratio, Nonfarm Payrolls, Initial Jobless Claims, Continuing Jobless Claims, Job Openings Rate, Quits Rate.

Inflation / Prices: CPI All Items, Core CPI, PCE Price Index, Core PCE, Trimmed Mean PCE, Median CPI.

Wages / Income: Average Hourly Earnings, Employment Cost Index, Real Disposable Personal Income.

Monetary Policy / Liquidity: Fed Funds Rate, Effective Fed Funds Rate, Interest on Reserve Balances, Fed Total Assets, Reserve Balances, Overnight Reverse Repo, M2 Money Supply.

Rates / Yield Curve: 2-Year Treasury, 10-Year Treasury, 10Y-2Y Spread, 10-Year Term Premium, 10-Year Breakeven Inflation.

Credit / Financial Stress: Baa Corporate Spread, High Yield OAS, Senior Loan Officer Survey, Financial Conditions Index, Bank Credit.

Housing: Housing Starts, Building Permits, Existing Home Sales, Case-Shiller Home Price Index, 30-Year Mortgage Rate.

Sentiment: Consumer Sentiment.

Request body (JSON)

Parameter	Type	Required	Description
query	string	required	Natural-language macro question (e.g. "What is the current unemployment rate?").

Response

{
  "data": [ { ... }, ... ],
  "seriesQueried": [ "UNRATE", ... ]
}

Response fields

Field	Type	Description
data	array	Array of result objects from tool calls, preserving original structure (e.g. seriesId, observations, metadata).
seriesQueried	string[]	List of FRED series IDs that were queried.

Example request

curl -X POST -H "Authorization: Bearer esak_<your-key>" \
     -H "Content-Type: application/json" \
     -d '{"query": "What is the current unemployment rate?"}' \
     "https://expert-system.starmode.dev/api/v1/query/macro"

Example response

{
  "data": [
    {
      "seriesId": "UNRATE",
      "observations": [
        { "date": "2026-02-01", "value": "4.4" },
        { "date": "2026-01-01", "value": "4.0" }
      ]
    }
  ],
  "seriesQueried": ["UNRATE"]
}

POST/api/v1/query/financial

Query Financial Data

Natural language interface for company financial data. An AI agent translates your question into Alpha Vantage API calls and returns structured data.

Available data

Ask about any public company by name or ticker — the agent resolves symbols automatically.

Company Overview: Name, Sector, Industry, Market Cap, EBITDA, P/E Ratio, PEG Ratio, Book Value, Dividend Yield, EPS, Revenue Per Share, Profit Margin, Operating Margin, ROA, ROE, Revenue TTM, Analyst Target Price, Forward P/E, EV/Revenue, EV/EBITDA, Beta, 52-Week High/Low, Moving Averages, Shares Outstanding.

Income Statement (quarterly): Total Revenue, Gross Profit, Cost of Revenue, Operating Income, Operating Expenses, SG&A, R&D, Interest Expense, Income Before Tax, Tax Expense, Net Income, EBIT, EBITDA, D&A.

Balance Sheet (quarterly): Total Assets, Current Assets, Cash & Equivalents, Inventory, Receivables, PP&E, Goodwill, Intangible Assets, Total Liabilities, Current Liabilities, Accounts Payable, Short-Term Debt, Long-Term Debt, Total Shareholder Equity, Retained Earnings, Shares Outstanding.

Cash Flow (quarterly): Operating Cash Flow, Capital Expenditures, Cash Flow from Investing, Cash Flow from Financing, Dividend Payout, Share Repurchases, Debt Issuance, Net Income, D&A, Change in Receivables, Change in Inventory.

Request body (JSON)

Parameter	Type	Required	Description
query	string	required	Natural-language financial question (e.g. "What is Apple's revenue trend?").

Response

{
  "data": [ { ... }, ... ],
  "tickersQueried": [ "AAPL", ... ]
}

Response fields

Field	Type	Description
data	array	Array of result objects from tool calls, preserving original structure (e.g. symbol, metric, quarterly reports).
tickersQueried	string[]	List of ticker symbols that were queried.

Example request

curl -X POST -H "Authorization: Bearer esak_<your-key>" \
     -H "Content-Type: application/json" \
     -d '{"query": "What is Apple'\''s latest quarterly revenue?"}' \
     "https://expert-system.starmode.dev/api/v1/query/financial"

Example response

{
  "data": [
    {
      "symbol": "AAPL",
      "metric": "totalRevenue",
      "reports": [
        { "fiscalDateEnding": "2025-12-31", "value": "143756000000" }
      ]
    }
  ],
  "tickersQueried": ["AAPL"]
}

Error responses

Errors return a JSON body with an error field and the corresponding HTTP status code.

Field	Type	Description
400 Bad Request		Missing or invalid parameter (e.g. missing ids, invalid limit, malformed cursor or date).
401 Unauthorized		Missing, invalid, or revoked API key.
200 OK		Successful response. Always returns an items array.

Example error body

{ "error": "Missing required parameter: ids" }