API Reference

Query parameters

Response

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

Takeaway object

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...",
      "publicationDate": "2026-03-01T00:00:00.000Z",
      "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"
      }
    }
  ]
}

Query parameters

Response

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

Takeaway object

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",
      "summary": "The Fed expects inflation to cool before changing rates.",
      "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" }
      ]
    }
  ]
}

Query parameters

Response

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

Search result object

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%...",
      "publicationDate": "2026-03-01T00:00:00.000Z",
      "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"
      }
    }
  ]
}

Query parameters

Response

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

Document object

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"
    }
  ]
}

Query parameters

Response

{
  "item": {
    "id": "doc_xyz789",
    "title": "Remarks on the Economic Outlook",
    "source": "Fed Speeches",
    "link": "https://www.federalreserve.gov/...",
    "publicationDate": "2026-03-01T00:00:00.000Z",
    "content": {
      "text": "Thank you for the opportunity to speak...",
      "offset": 0,
      "nextOffset": 12000,
      "totalCharacters": 48320,
      "truncated": true
    }
  }
}

Response

{
  "catalogVersion": "1",
  "metrics": [
    {
      "id": "revenue",
      "label": "Revenue",
      "statement": "incomeStatement",
      "unitType": "monetary"
    }
  ]
}

Example request

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

Path parameters

Query parameters

Response

{
  "catalogVersion": "1",
  "symbol": "AAPL",
  "cik": "0000320193",
  "company": "Apple Inc.",
  "period": "quarterly",
  "metrics": [
    {
      "id": "revenue",
      "label": "Revenue",
      "statement": "incomeStatement",
      "unit": "USD"
    }
  ],
  "source": "SEC"
}

Example request

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/financials/AAPL/metrics?period=quarterly"

Path parameters

Query parameters

Response fields

Example request

curl -H "Authorization: Bearer esak_<your-key>" \
     "https://expert-system.starmode.dev/api/v1/financials/AAPL/accountsPayable?period=quarterly&limit=4"

Compact response

{
  "catalogVersion": "1",
  "symbol": "AAPL",
  "cik": "0000320193",
  "company": "Apple Inc.",
  "metric": "accountsPayable",
  "period": "quarterly",
  "unit": "USD",
  "data": [
    {
      "date": "2026-06-27",
      "value": 64525000000,
      "periodType": "instant"
    }
  ],
  "source": "SEC"
}

Provenance observation

{
  "date": "2026-06-27",
  "value": 64525000000,
  "periodType": "instant",
  "filed": "2026-07-31",
  "form": "10-Q",
  "accession": "0000320193-26-000020",
  "concept": "AccountsPayableCurrent"
}

Request body (JSON)

Example request

curl -X POST -H "Authorization: Bearer esak_<your-key>" \
     -H "Content-Type: application/json" \
     -d '{"symbol":"JPM","metrics":["netIncome","inventory"],"period":"quarterly","limit":4}' \
     "https://expert-system.starmode.dev/api/v1/financials"

Partial-success response

{
  "catalogVersion": "1",
  "symbol": "JPM",
  "cik": "0000019617",
  "company": "JPMORGAN CHASE & CO",
  "period": "quarterly",
  "metrics": {
    "netIncome": {
      "unit": "USD",
      "data": [
        {
          "date": "2026-03-31",
          "value": 16494000000,
          "periodType": "quarter"
        }
      ]
    }
  },
  "errors": {
    "inventory": {
      "code": "METRIC_UNAVAILABLE",
      "message": "inventory is unavailable for JPM"
    }
  },
  "source": "SEC"
}

Valid but unavailable metrics appear in errors while available metrics are returned normally with status 200. An unknown metric ID rejects the whole request with METRIC_NOT_FOUND.

Query parameters

Response

{
  "items": [
    {
      "id": "UNRATE",
      "description": "Civilian Unemployment Rate (%)",
      "category": "Labor Market",
      "nativeFrequency": "monthly",
      "nativeUnits": "Percent",
      "sourceUrl": "https://fred.stlouisfed.org/series/UNRATE"
    }
  ]
}

Available data

Select series directly or search the macro series catalog first. Each series keeps its native timeline unless you explicitly request a lower frequency.

Request body (JSON)

{
  "series": [
    { "id": "UNRATE", "lastN": 12, "units": "lin" },
    {
      "id": "ICSA",
      "lastN": 12,
      "frequency": "m",
      "aggregationMethod": "avg"
    }
  ]
}

Send one to five unique series. Each accepts either lastN or a complete startDate/endDate range. Transformations are lin, chg, ch1, pch, pc1, pca, cch, and cca. Frequency aggregation supports avg, sum, and eop; upsampling is rejected.

lin returns levels; chg and ch1 return period and year-ago changes; pch and pc1 return period and year-ago percent changes; pca is compounded annualized percent change; and cch/cca are continuously compounded period and annualized changes.

Use one series for simple questions and batches for comparisons. Keep native frequency by default; request an explicit lower frequency and aggregation method only when comparable periods are required.

Response

{
  "asOf": "2026-08-02T00:00:00.000Z",
  "items": [
    {
      "seriesId": "UNRATE",
      "description": "Civilian Unemployment Rate (%)",
      "sourceUrl": "https://fred.stlouisfed.org/series/UNRATE",
      "nativeFrequency": "monthly",
      "returnedFrequency": "monthly",
      "nativeUnits": "Percent",
      "transformation": "lin",
      "observations": [{ "date": "2026-07-01", "value": 4.2 }]
    }
  ],
  "errors": []
}

Response fields

Example request

curl -X POST -H "Authorization: Bearer esak_<your-key>" \
     -H "Content-Type: application/json" \
     -d '{"series":[{"id":"UNRATE","lastN":12}]}' \
     "https://expert-system.starmode.dev/api/v1/macro/observations"