Trinity Data Feed — API Reference v1.0

Authentication

The Trinity Data Feed API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Getting Your API Key

API keys are provisioned upon subscription. You'll receive yours via email within 5 minutes of activation. Keep your API key secure—treat it like a password.

Making Authenticated Requests

Include the Authorization header with every API call:

                Copy
                curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.trinitydata.io/v1/health
            

Replace YOUR_API_KEY with your actual API key provided in your subscription confirmation email.

Rate Limits by Tier

Free

100

calls/day

Developer

calls/day

Pro

10K

calls/day

Rate limit information is returned in response headers:

                Copy
                X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9950
X-RateLimit-Reset: 1712870400
            

Endpoints

GET /api/v1/health

System Health Check

Returns the current status of the Trinity Data Feed API and all connected data sources. Use this endpoint for availability monitoring and health dashboards.

Parameters

This endpoint accepts no parameters.

Example Request

                    Copy
                    curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.trinitydata.io/v1/health
                

Example Response

                    Copy
                    {
  "status": "operational",
  "version": "1.0.0",
  "uptime_hours": 2847.5,
  "platforms_active": 12,
  "last_sync": "2026-04-11T14:32:15Z",
  "latency_ms": 145
}
                

Response Fields

Field	Type	Description
`status`	string	Overall system status: "operational", "degraded", or "offline"
`version`	string	Current API version
`uptime_hours`	number	Hours since last restart
`platforms_active`	number	Number of active data sources
`last_sync`	string	ISO 8601 timestamp of last data refresh
`latency_ms`	number	Current average response latency in milliseconds

GET /api/v1/trends

Parameter	Type	Required	Description
`platform`	string	No	Filter by platform: twitter, tiktok, reddit, youtube, news. Default: all
`limit`	integer	No	Number of results (1-100). Default: 20
`timeframe`	string	No	Time window: 1h, 6h, 24h. Default: 1h

Field	Type	Description
`topic`	string	Name of the trending topic
`platform`	string	Social platform or news source
`score`	number	Trend strength (0-10 scale)
`volume`	integer	Total mentions in timeframe
`velocity`	number	Growth rate (mentions per hour)
`sentiment`	string	Overall sentiment: positive, neutral, negative

Real-Time Sentiment Analysis

Get AI-powered sentiment analysis for any ticker symbol, brand, or topic. Composite scoring, confidence metrics, and platform-level breakdowns for nuanced market intelligence.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Stock ticker (e.g., NVDA, BTC) or topic name
`platforms`	string	No	Comma-separated list: twitter, reddit, tiktok, youtube. Default: all

Example Request

                    Copy
                    curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.trinitydata.io/v1/sentiment?query=NVIDIA&platforms=twitter,reddit"
                

Example Response

                    Copy
                    {
  "query": "NVIDIA",
  "composite_score": 0.72,
  "confidence": 0.94,
  "trending_direction": "up",
  "platform_breakdown": [
    {
      "platform": "twitter",
      "score": 0.75,
      "sample_size": 8432
    }
  ]
}
                

Response Fields

Field	Type	Description
`query`	string	The query that was analyzed
`composite_score`	number	Weighted sentiment (-1.0 to 1.0, where 1.0 is most positive)
`confidence`	number	Model confidence (0.0 to 1.0)
`trending_direction`	string	Sentiment momentum: up, down, or stable
`platform_breakdown`	array	Per-platform sentiment scores

GET /api/v1/competitive-intel

Competitive Intelligence

Track share of voice, sentiment, and mention volume across your brand and competitors. Perfect for marketing strategy, competitive positioning, and brand health monitoring.

Parameters

Parameter	Type	Required	Description
`brand`	string	Yes	Your brand or company name
`competitors`	string	No	Comma-separated list of competitor names (e.g., "Apple,Microsoft")

Example Request

                    Copy
                    curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.trinitydata.io/v1/competitive-intel?brand=Tesla&competitors=Ford,GM"
                

Example Response

                    Copy
                    {
  "brand": "Tesla",
  "share_of_voice": 48.3,
  "sentiment": 0.68,
  "competitor_comparison": [
    {
      "name": "Ford",
      "mentions": 23450,
      "sentiment": 0.42,
      "share": 28.5
    }
  ]
}
                

Response Fields

Field	Type	Description
`brand`	string	Your brand name
`share_of_voice`	number	Percentage of total mentions vs competitors
`sentiment`	number	Brand sentiment score (-1.0 to 1.0)
`competitor_comparison`	array	Competitive metrics for each competitor

GET /api/v1/content-research

Content Opportunity Research

Identify high-potential content topics, recommended formats, and keyword opportunities. Data-driven insights for content strategy and SEO planning.

Parameters

Parameter	Type	Required	Description
`topic`	string	Yes	Content topic or keyword to research
`platform`	string	No	Filter by platform: twitter, youtube, tiktok, blog. Default: all

Example Request

                    Copy
                    curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.trinitydata.io/v1/content-research?topic=AI+productivity&platform=youtube"
                

Example Response

                    Copy
                    {
  "opportunities": [
    {
      "title": "Top AI Tools for 2026",
      "platform": "youtube",
      "search_volume": 42000,
      "competition": "high",
      "engagement_potential": 8.7,
      "recommended_format": "video_tutorial",
      "keywords": ["AI tools", "productivity"]
    }
  ]
}
                

Response Fields

Field	Type	Description
`title`	string	Suggested content title
`platform`	string	Recommended platform for this content
`search_volume`	integer	Estimated monthly search volume
`competition`	string	Competitive level: low, medium, high
`engagement_potential`	number	Expected engagement score (0-10 scale)
`recommended_format`	string	Best format: blog_post, video_tutorial, infographic, etc.
`keywords`	array	High-value keywords to target

GET /api/v1/market-pulse

Financial Market Sentiment

Real-time correlation between social sentiment and financial market movements. Track how social conversations predict price action across stocks and cryptocurrencies.

Parameters

Parameter	Type	Required	Description
`tickers`	string	Yes	Comma-separated tickers (e.g., "NVDA,TSLA,BTC")
`include_social`	boolean	No	Include social sentiment data. Default: true

Example Request

                    Copy
                    curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.trinitydata.io/v1/market-pulse?tickers=NVDA,TSLA,BTC&include_social=true"
                

Example Response

                    Copy
                    {
  "tickers": [
    {
      "symbol": "NVDA",
      "sentiment": 0.78,
      "social_volume": 156200,
      "price_correlation": 0.82,
      "top_mentions": ["AI", "earnings"]
    }
  ]
}
                

Response Fields

Field	Type	Description
`symbol`	string	Stock ticker or crypto symbol
`sentiment`	number	Composite sentiment score (-1.0 to 1.0)
`social_volume`	integer	Total social mentions in last 24 hours
`price_correlation`	number	Correlation between sentiment and price movement (0-1)
`top_mentions`	array	Most common topics in mentions

Error Codes & Handling

The Trinity Data Feed API uses standard HTTP status codes. Here's how to handle common errors:

200 OK

Request successful. Data is in the response body.

400 Bad Request

Invalid parameters or malformed request. Check query string and body.

401 Unauthorized

Missing or invalid API key. Verify your Authorization header.

403 Forbidden

API key is valid but doesn't have access to this endpoint. Check your subscription tier.

429 Too Many Requests

Rate limit exceeded. Wait before retrying. Check X-RateLimit-Reset header.

500 Server Error

Internal server error. We've been notified. Try again in a few minutes.

Error Response Format

When an error occurs, the response includes an error object:

                Copy
                {
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Required parameter 'query' is missing",
    "status": 400
  }
}
            

Client Libraries

We're building first-class SDKs to make integration even faster. Coming soon to your favorite language:

Official SDKs — Coming Soon

Python

                    Copy
                    from trinity import DataFeed

feed = DataFeed(api_key="YOUR_API_KEY")

# Fetch trending topics
trends = feed.trends(platform="twitter", limit=10)

# Get sentiment
sentiment = feed.sentiment(query="NVIDIA")

# Market pulse
pulse = feed.market_pulse(tickers=["NVDA", "TSLA"])
                

Node.js

                    Copy
                    const { DataFeed } = require('trinity-data-feed');

const feed = new DataFeed({ apiKey: 'YOUR_API_KEY' });

// Fetch trends
const trends = await feed.trends({ platform: 'twitter', limit: 10 });

// Get sentiment
const sentiment = await feed.sentiment({ query: 'NVIDIA' });

// Market pulse
const pulse = await feed.marketPulse({ tickers: ['NVDA', 'TSLA'] });
                

Go

                    Copy
                    import "github.com/trinity/data-feed"

client := datafeed.NewClient("YOUR_API_KEY")

// Fetch trends
trends, err := client.Trends(ctx, &datafeed.TrendsOptions{
    Platform: "twitter",
    Limit:    10,
})

// Get sentiment
sentiment, err := client.Sentiment(ctx, "NVIDIA")
                

SDKs are in active development. Join our developer community for updates and beta access.

Authentication

Getting Your API Key

Making Authenticated Requests

Rate Limits by Tier

Free

Developer

Pro

Endpoints

System Health Check

Parameters

Example Request

Example Response

Response Fields

Trending Topics

Parameters

Example Request

Example Response

Response Fields

Real-Time Sentiment Analysis

Parameters

Example Request

Example Response

Response Fields

Competitive Intelligence

Parameters

Example Request

Example Response

Response Fields

Content Opportunity Research

Parameters

Example Request

Example Response

Response Fields

Financial Market Sentiment

Parameters

Example Request

Example Response

Response Fields

Error Codes & Handling

Error Response Format

Client Libraries

Official SDKs — Coming Soon

Python

Node.js

Go