API REFERENCE

Endpoints, parameters, and responses.

Every public endpoint, grouped by resource. All responses are JSON. All requests require an API key.

AUTHENTICATION

Authentication

Pass your API key in the X-API-Key header on every request.

X-API-Key: YOUR_API_KEY

info Get your key from your console. Treat it like a password — store it in environment variables, never commit it to a public repo.

Base URL

All endpoints live under a single base URL. The base never changes between environments.

https://api.malinal.ai

Endpoints

Endpoints are grouped by resource. Each entry lists the HTTP method, full path, parameters, and a copy-pasteable cURL example. Pro-tier endpoints are flagged inline.

System

Service health and infrastructure status.

GET /v1/health

Health check returning database and Redis connection status. No authentication required.

Parameters

None

Example request

curl https://api.malinal.ai/v1/health

Tickers

Discover and look up symbols in coverage.

GET /v1/tickers

List active S&P 500 tickers with optional filtering by sector or search term.

Parameters

Name	Type	Required	Description
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Results per page (default 20)
`sector`	string	No	Filter by GICS sector
`search`	string	No	Search by symbol or company name

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.malinal.ai/v1/tickers?sector=Technology&page_size=10"

GET /v1/tickers/{symbol}

Get ticker detail with company profile.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/tickers/AAPL

Profiles

Company information and shares outstanding history.

GET /v1/profiles/{symbol}

Company profile: sector, industry, CEO, headquarters, and business description.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/profiles/AAPL

Prices

Historical daily OHLCV price data.

GET /v1/prices/{symbol}

Daily OHLCV (open, high, low, close, volume) for a symbol. Optional date range and pagination.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)
`start_date`	string	No	Start date in YYYY-MM-DD format
`end_date`	string	No	End date in YYYY-MM-DD format
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Results per page (default 20)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.malinal.ai/v1/prices/AAPL?start_date=2026-01-01&end_date=2026-03-01"

Fundamentals

Financial statements, KPIs, earnings, and analyst coverage.

GET /v1/fundamentals/{symbol}/income

Income statements (annual or quarterly).

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)
`period_type`	string	No	`annual` or `quarterly` (default annual)
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Results per page (default 20)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.malinal.ai/v1/fundamentals/AAPL/income?period_type=annual"

GET /v1/fundamentals/{symbol}/balance

Balance sheet statements (annual or quarterly).

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)
`period_type`	string	No	`annual` or `quarterly` (default annual)
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Results per page (default 20)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.malinal.ai/v1/fundamentals/MSFT/balance?period_type=quarterly"

GET /v1/fundamentals/{symbol}/cashflow

Cash flow statements (annual or quarterly).

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)
`period_type`	string	No	`annual` or `quarterly` (default annual)
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Results per page (default 20)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/fundamentals/GOOGL/cashflow

GET /v1/fundamentals/{symbol}/kpis

Key performance indicators: P/E, EPS, ROE, margins, and other fundamental metrics.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Results per page (default 20)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/fundamentals/AAPL/kpis

GET /v1/fundamentals/{symbol}/earnings

Earnings calendar with EPS estimates, actuals, and surprise data.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Results per page (default 20)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/fundamentals/TSLA/earnings

GET /v1/fundamentals/{symbol}/analyst-ratings

Analyst price targets and consensus recommendations (buy, hold, sell).

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)
`page`	integer	No	Page number (default 1)
`page_size`	integer	No	Results per page (default 20)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/fundamentals/NVDA/analyst-ratings

Malinal Signal

AI-powered analysis: valuations, transcript summaries, moat scoring, risk analysis.

workspace_premium Free includes Signal on AAPL. Pro covers every S&P 500 ticker.

GET /v1/signal/{symbol}/intrinsic-value Pro

Three-scenario DCF intrinsic value estimate (bear / base / bull) with reasoning.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/signal/AAPL/intrinsic-value

GET /v1/signal/{symbol}/transcript-summaries Pro

AI-generated summaries of earnings calls — guidance, growth drivers, risks, management tone.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/signal/AAPL/transcript-summaries

GET /v1/signal/{symbol}/competitive-advantages Pro

AI assessment of competitive moats and their durability.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/signal/AAPL/competitive-advantages

GET /v1/signal/{symbol}/investment-risks Pro

AI-identified investment risks ranked by severity.

Parameters

Name	Type	Required	Description
`symbol`	string	Yes	Ticker symbol (e.g., AAPL)

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.malinal.ai/v1/signal/AAPL/investment-risks

ERROR CODES

Error codes

All errors return JSON with a code and a human-readable message.

Code	Meaning
`400`	Bad request — malformed parameters.
`401`	Missing or invalid API key.
`403`	Authenticated, but your plan does not cover this endpoint or ticker.
`404`	Symbol not in coverage, or resource not found.
`429`	Rate limit exceeded. `Retry-After` header tells you when your limit resets.
`500`	Server error on our side. Retry; if it persists, email [email protected].

Common Responses

JSON

200 · /v1/tickers

// GET /v1/tickers?sector=Technology&page_size=2
{
  "count": 68,
  "next": "https://api.malinal.ai/v1/tickers?page=2&sector=Technology",
  "previous": null,
  "results": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "sector": "Technology"
    },
    {
      "symbol": "MSFT",
      "name": "Microsoft Corporation",
      "sector": "Technology"
    }
  ]
}

200 · /v1/profiles/AAPL

// GET /v1/profiles/AAPL
{
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "sector": "Technology",
  "industry": "Consumer Electronics",
  "ceo": "Tim Cook",
  "headquarters": "Cupertino, California",
  "description": "Designs, manufactures, and markets..."
}

200 · /v1/signal/AAPL/intrinsic-value

// Pro endpoint
{
  "symbol": "AAPL",
  "suggested_intrinsic_value": 215.80,
  "valuation_low": 187.50,
  "valuation_high": 258.40,
  "confidence": "HIGH",
  "last_updated": "2026-04-20T14:30:00Z"
}

401 · Unauthorized

// Missing or invalid X-API-Key header
{
  "code": "unauthorized",
  "message": "Missing or invalid API key."
}

403 · Pro Required

// Free key calling Signal for a ticker other than AAPL
{
  "code": "plan_required",
  "message": "The Free plan includes Malinal Signal for AAPL only. Upgrade to Pro for Signal on every S&P 500 ticker at malinal.ai/pricing.",
  "upgrade_url": "https://malinal.ai/pricing"
}

429 · Rate Limited

// Response also sets Retry-After header
{
  "code": "rate_limited",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retry_after": 60
}