Shubair Developer Portal

API & Developer Documentation

Integrate TradeInsight AI programmatically. Built by Mohd Shubair for AI agents, quant developers, and automated algorithmic pipelines analyzing 20+ NSE Indian equity sectors.

OpenAPI Spec (JSON)OpenAPI Spec (YAML)📄 llms.txt (Agent Guide)⏱️ Deprecation Policy

💻 Official CLI Tool

Command Line Interface (CLI)

Interact with TradeInsight AI directly from your terminal or automation scripts without writing custom HTTP integrations:

Run instantly via npx (Node.js)

npx tradeinsight analyze pharmaceuticals

Install via Python PyPI

pip install tradeinsight-cli
tradeinsight sectors
tradeinsight analyze technology --format json

Base URL

https://tradeinsight.shubair.in

All API endpoints are relative to this base URL. Responses are JSON unless otherwise noted.

Authentication

TradeInsight AI uses JWT (JSON Web Token) bearer authentication. Obtain a token pair by registering or logging in, then include the access token in theAuthorizationheader of subsequent requests.

1. Register

POST /api/v1/auth/register

{
  "username": "your_username",
  "email": "you@example.com",
  "password": "SecurePass123",
  "full_name": "Your Name"
}

2. Login

POST /api/v1/auth/login

{
  "username": "your_username",
  "password": "SecurePass123"
}

// Response:
{
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG...",
  "token_type": "bearer"
}

3. Use the Token

Authenticated Request

curl -X GET "https://tradeinsight.shubair.in/api/v1/analyze/pharmaceuticals" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Endpoints

Public (No Auth Required)

GET

/

API root — service info and endpoint listing

GET

/health

Health check with system status

GET

/openapi.json

Full OpenAPI specification (machine-readable)

GET

/api/v1/sectors

List all 20+ sectors available for analysis

Authentication

POST

/api/v1/auth/send-otp

Send a 6-digit OTP code to an email address

POST

/api/v1/auth/verify-otp

Verify an email OTP code

POST

/api/v1/auth/register

POST

/api/v1/auth/login

POST

/api/v1/auth/refresh

Refresh an expired access token

🔒 Auth

POST

/api/v1/auth/logout

Invalidate the current refresh token

🔒 Auth

Sector Analysis

GET

/api/v1/analyze/{sector}

Analyse a sector — returns a cited AI report with opportunities, risks, and recommendations

🔒 Auth

POST

/api/v1/analyze/compare

Compare two sectors side-by-side

🔒 Auth

GET

/api/v1/history

List past analyses for the current user

🔒 Auth

GET

/api/v1/history/{id}

Retrieve a specific past analysis

🔒 Auth

DELETE

/api/v1/history/{id}

Delete a specific analysis from history

🔒 Auth

GET

/api/v1/history/{id}/export

Export an analysis as PDF, PPTX, XLSX, or Markdown

🔒 Auth

AI & Voice

POST

/api/v1/ai/vision/analyze

Analyse an uploaded image using AI vision

🔒 Auth

POST

/api/v1/ai/tts

Convert text to speech

🔒 Auth

POST

/api/v1/ai/stt

Convert speech to text

🔒 Auth

POST

/api/v1/voice/query

Voice-based market query (text in, speech out)

🔒 Auth

POST

/api/v1/voice/agent

Full voice agent interaction

🔒 Auth

GET

/api/v1/voice/voices

List available TTS voices

User & Preferences

GET

/api/v1/users/me

Get current user profile

🔒 Auth

PUT

/api/v1/users/me

Update user profile

🔒 Auth

GET

/api/v1/users/me/stats

Get user usage statistics

🔒 Auth

GET

/api/v1/favorites

List favourite sectors

🔒 Auth

POST

/api/v1/favorites

Add a sector to favourites

🔒 Auth

DELETE

/api/v1/favorites/{sector}

Remove a sector from favourites

🔒 Auth

Example: Analyse a Sector

Request

curl -X GET "https://tradeinsight.shubair.in/api/v1/analyze/pharmaceuticals?use_cache=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response (abbreviated)

{
  "sector": "Pharmaceuticals",
  "analysis": "## Executive Summary\n\nThe Indian pharmaceutical sector...",
  "key_opportunities": [
    "CDMOs benefiting from US supply-chain reshoring",
    "Q1 order books up 18% YoY"
  ],
  "key_risks": [
    "USD weakness offsetting margin expansion for exporters"
  ],
  "sources": [
    {"title": "...", "url": "...", "reliability": "high"}
  ],
  "generated_at": "2026-08-24T14:00:00Z",
  "latency_ms": 12400
}

Rate Limits & Response Headers

Tier	Per Minute	Per Hour
Free	10	100
Pro	30	500
Enterprise	Custom — contact sales

Standard RFC RateLimit Response Headers

Every API response includes IETF/RFC standard rate limit headers enabling AI agents to self-throttle dynamically:

RateLimit-Limit: 100 // Maximum allowed requests in window

RateLimit-Remaining: 98 // Requests remaining in current window

RateLimit-Reset: 42 // Seconds until quota window resets

RateLimit-Policy: 100;w=60 // 100 requests per 60-second window

Retry-After: 60 // Present when HTTP 429 occurs (seconds to wait)

API Versioning & Deprecation Policy

We follow strict semantic URL versioning (/api/v1/...). Deprecated endpoints are guaranteed a minimum 6-month operational grace period and return RFC 8594 Deprecation and Sunset headers.

Read the full Deprecation & Stability Policy →

Error Responses

All errors return structured JSON with consistent fields:

Error Response Format

{
  "error": "Human-readable error description",
  "message": "Detailed message for debugging",
  "code": "ERROR_CODE"
}

Status	Code	Description
400	HTTP_400	Bad request — invalid parameters
401	HTTP_401	Unauthorized — missing or invalid token
404	HTTP_404	Resource not found
429	RATE_LIMITED	Rate limit exceeded — retry after Retry-After header
500	INTERNAL_ERROR	Internal server error