API Reference

v2.1

API Access Requires Enterprise Plan

The PremiseLab API is available exclusively to Enterprise customers. Contact sales to get started.

The PremiseLab API provides programmatic access to our premise-based investment research platform. Build custom integrations, automate your research workflow, or embed our analysis directly into your applications.

All API requests are made to:

Base URL: https://api.premiselab.io/v2

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header of all requests.

Request Header

Authorization: Bearer YOUR_API_KEY

API keys can be generated and managed from your dashboard. Keep your API keys secure and never expose them in client-side code.

Rate Limits

API requests are rate limited based on your plan tier. Rate limit information is included in response headers.

Plan	Requests/min	Requests/day	Concurrent
Enterprise	60	10,000	10
Enterprise Plus	300	100,000	50

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1699574400

Error Handling

The API uses conventional HTTP status codes. All errors return a consistent JSON structure.

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
429	Rate limit exceeded
500	Internal server error

Error Response

{
  "error": {
    "code": "invalid_premise",
    "message": "Premise must be between 10 and 500 characters",
    "param": "premise",
    "request_id": "req_abc123xyz"
  }
}

POST

/analyze

Analyze an investment premise and return matching securities with confidence scores.

Request Body

Parameter	Type	Required	Description
premise	string	Yes	Investment thesis in natural language (10-500 chars)
limit	integer	No	Max results to return (1-50, default: 10)
min_confidence	float	No	Minimum confidence threshold (0-1, default: 0.5)
sectors	array	No	Filter by GICS sectors
market_cap	object	No	Market cap filter: {min, max} in USD
include_analysis	boolean	No	Include detailed AI analysis (default: true)

Example Request

cURL

curl -X POST https://api.premiselab.io/v2/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "premise": "Companies benefiting from AI infrastructure growth",
    "limit": 5,
    "min_confidence": 0.75,
    "market_cap": {
      "min": 10000000000
    }
  }'

Response

JSON Response 200 OK

{
  "request_id": "req_7f3k9x2m1n",
  "premise": "Companies benefiting from AI infrastructure growth",
  "processed_at": "2025-11-19T14:32:18Z",
  "analysis_summary": "The AI infrastructure thesis shows exceptional momentum...",
  "results": [
    {
      "ticker": "NVDA",
      "name": "NVIDIA Corporation",
      "confidence": 0.94,
      "sector": "Information Technology",
      "industry": "Semiconductors",
      "market_cap": 2890000000000,
      "rationale": "Dominant GPU provider for AI training and inference...",
      "factors": {
        "revenue_alignment": 0.96,
        "market_position": 0.98,
        "earnings_momentum": 0.92,
        "valuation": 0.71
      },
      "metrics": {
        "pe_ratio": 68.4,
        "revenue_growth_yoy": 1.22,
        "gross_margin": 0.748
      }
    },
    {
      "ticker": "AVGO",
      "name": "Broadcom Inc",
      "confidence": 0.89,
      // ... additional fields
    }
  ],
  "metadata": {
    "securities_analyzed": 12847,
    "documents_processed": 34521,
    "processing_time_ms": 1842
  }
}

GET

/stocks/{ticker}

Retrieve detailed information about a specific security including fundamentals, AI analysis, and premise history.

Path Parameters

Parameter	Type	Description
ticker	string	Stock ticker symbol (e.g., NVDA, AAPL)

Query Parameters

Parameter	Type	Description
include	array	Additional data: financials, filings, transcripts, news
period	string	Historical data period: 1y, 3y, 5y, 10y, max

Example Request

cURL

curl https://api.premiselab.io/v2/stocks/NVDA?include=financials,news \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

JSON Response 200 OK

{
  "ticker": "NVDA",
  "name": "NVIDIA Corporation",
  "exchange": "NASDAQ",
  "sector": "Information Technology",
  "industry": "Semiconductors",
  "description": "NVIDIA Corporation provides graphics and compute...",
  "market_cap": 2890000000000,
  "employees": 29600,
  "headquarters": "Santa Clara, CA",
  "financials": {
    "revenue_ttm": 96309000000,
    "net_income_ttm": 42597000000,
    "gross_margin": 0.748,
    "operating_margin": 0.542,
    "pe_ratio": 68.4,
    "ps_ratio": 30.1,
    "debt_to_equity": 0.41,
    "free_cash_flow_ttm": 38421000000
  },
  "price": {
    "current": 875.42,
    "change_1d": 0.0234,
    "change_1w": 0.0512,
    "change_1m": 0.1847,
    "change_1y": 1.854,
    "high_52w": 974.00,
    "low_52w": 342.15
  },
  "premise_matches": [
    {
      "premise": "AI infrastructure growth",
      "confidence": 0.94,
      "match_count_30d": 8472
    }
  ]
}

POST

/backtest

Run historical backtests on your investment premise. See how it would have performed over time.

Request Body

Parameter	Type	Required	Description
premise	string	Yes	Investment thesis to backtest
start_date	string	Yes	Backtest start date (YYYY-MM-DD)
end_date	string	No	Backtest end date (default: today)
rebalance	string	No	Rebalance frequency: daily, weekly, monthly, quarterly
benchmark	string	No	Benchmark ticker (default: SPY)

Example Response

JSON Response

{
  "backtest_id": "bt_9k2m4x7p",
  "premise": "Companies benefiting from AI infrastructure growth",
  "period": {
    "start": "2022-01-01",
    "end": "2025-11-19"
  },
  "performance": {
    "total_return": 2.847,
    "annualized_return": 0.412,
    "sharpe_ratio": 1.82,
    "max_drawdown": -0.284,
    "volatility": 0.312,
    "alpha": 0.187,
    "beta": 1.24
  },
  "benchmark_performance": {
    "total_return": 0.842,
    "annualized_return": 0.178
  },
  "holdings_history": [
    {
      "date": "2022-01-01",
      "holdings": ["NVDA", "AMD", "AVGO", "MRVL", "ANET"]
    }
    // ... more periods
  ]
}

Watchlists

Create and manage watchlists to track securities and receive alerts when premise matches change.

POST /watchlists

Create a new watchlist

GET /watchlists

List all watchlists

GET /watchlists/{id}

Get watchlist details and current matches

PUT /watchlists/{id}

Update watchlist settings

DELETE /watchlists/{id}

Delete a watchlist

Webhooks

Receive real-time notifications when important events occur, such as new premise matches or significant confidence score changes.

Event Types

Event	Description
premise.match.new	New stock matches a watched premise
premise.match.removed	Stock no longer matches premise criteria
confidence.changed	Confidence score changed significantly (>10%)
filing.new	New SEC filing for watched security

Webhook Payload

Example: premise.match.new

{
  "event": "premise.match.new",
  "timestamp": "2025-11-19T14:32:18Z",
  "data": {
    "watchlist_id": "wl_abc123",
    "premise": "AI infrastructure growth",
    "ticker": "SMCI",
    "name": "Super Micro Computer",
    "confidence": 0.87,
    "rationale": "Server manufacturer with GPU-optimized systems..."
  }
}

SDKs & Libraries

Official client libraries to integrate PremiseLab into your applications.

Python

pip install premiselab

View documentation →

Node.js

npm install @premiselab/sdk

View documentation →

REST API

OpenAPI 3.0 spec available

Download spec →

Postman Collection

Pre-built requests

Import collection →

Changelog

v2.1.0 November 15, 2025

• Added backtesting endpoint with customizable rebalance periods
• New webhook events for confidence score changes
• Improved rate limit headers

v2.0.0 October 1, 2025

• Major API redesign with improved response structure
• Added factor breakdown in analysis results
• New /stocks endpoint with comprehensive data
• Breaking: Changed authentication to Bearer tokens

v1.5.0 August 20, 2025

• Added sector and market cap filters
• Watchlist API endpoints
• Python SDK release

Ready to integrate?

Contact our team to get API access and dedicated support.

Contact Sales