Developer Docs – Tarrasmart API

Introduction

The Tarrasmart API provides programmatic access to all features of the AI Media Intelligence platform — including stream monitoring, ASR transcription, ad tracking, sentiment analysis, and real-time alerts.

All requests are made over HTTPS to the base URL below. Responses are returned in JSON format.

Base URL: https://api.tarrasmart.com/v1/

Key capabilities

Monitor 50+ broadcast channels simultaneously with 24/7 uptime
Real-time speech recognition (ASR) with 97%+ accuracy across 30+ languages
Ad appearance tracking and logo detection at 98% accuracy
NLP sentiment analysis and keyword spotting
Export reports as CSV, JSON, or PDF
GDPR-compliant data deletion via API

Authentication

All API requests require a Bearer token in the Authorization header. Obtain your API key from Dashboard → Settings → API Access.

HTTP HeaderAuthorization: Bearer YOUR_API_KEY
Content-Type: application/json

Example — authenticated request

cURLcurl -X GET https://api.tarrasmart.com/v1/channels \
  -H "Authorization: Bearer ts_pub_abc123..." \
  -H "Content-Type: application/json"

Security: Never expose your Secret Key in client-side code or public repositories. Use environment variables to store credentials.

Base URL & Environments

Tarrasmart provides two environments — production and sandbox for testing integrations without affecting live data.

Environment	Base URL	Notes
Production	`https://api.tarrasmart.com/v1`	Live data, billing applies
Sandbox	`https://sandbox-api.tarrasmart.com/v1`	Test environment, no billing

Use the same API key format for both environments. Sandbox keys are prefixed with ts_pub_sandbox_.

Error Handling

All errors return a consistent JSON body alongside an HTTP status code:

JSON{
  "error": "unauthorized",
  "message": "Invalid or expired API key.",
  "status": 401,
  "request_id": "req_m9x3k1abc"
}

Status	Code	Meaning
`200`	ok	Request succeeded
`400`	bad_request	Invalid request body or parameters
`401`	unauthorized	Missing or invalid API key
`403`	forbidden	Insufficient permissions for this resource
`404`	not_found	Resource does not exist
`429`	rate_limited	Too many requests — check rate limits
`500`	server_error	Internal error — contact support

Channels

Channels represent individual broadcast streams (TV or radio) being monitored by the AI engine.

GET/channelsList all monitored channels

POST/channelsAdd a new channel

GET/channels/{id}Get a single channel

DELETE/channels/{id}Remove a channel

POST /channels — Request body

Parameter	Type	Required	Description
`name`	string	required	Human-readable channel name
`stream_url`	string	required	RTSP / HLS / HTTP stream URL
`language`	string	required	ISO 639-1 code e.g. `id`, `en`
`enable_asr`	boolean	optional	Enable speech recognition (default: true)
`enable_ad_tracking`	boolean	optional	Enable ad detection (default: true)

Stream Ingestion

Submit a media file or live stream URL for AI processing. The engine will run ASR, sentiment analysis, and ad detection automatically.

POST/streams/ingestSubmit media for AI processing

Request body

JSON{
  "channel_id": "ch_m9x3k1",
  "file_url": "https://example.com/broadcast.mp4",
  "language": "id",
  "enable_sentiment": true,
  "enable_ad_tracking": true
}

Response

JSON{
  "stream_id": "str_xyz789",
  "status": "processing",
  "estimated_completion": "2023-05-28T10:05:00Z"
}

Transcripts (ASR)

Retrieve the automatic speech recognition transcript for a processed stream segment. Results include word-level timestamps and confidence scores.

GET/streams/{id}/transcriptGet ASR transcript

Response example

JSON{
  "stream_id": "str_xyz789",
  "language": "id",
  "accuracy": 0.97,
  "segments": [
    {
      "start": 0.0,
      "end": 4.2,
      "text": "Selamat pagi, ini adalah berita terkini...",
      "sentiment": "neutral",
      "confidence": 0.98
    }
  ]
}

Analytics

Access aggregated AI analysis results across all monitored channels — sentiment trends, ad appearances, and keyword frequency.

GET/analytics/sentimentSentiment analysis by channel/date

GET/analytics/adsAd appearance tracking report

GET/analytics/keywordsKeyword frequency analysis

Query parameters

Parameter	Type	Description
`from`	ISO date	Start date e.g. `2023-05-01`
`to`	ISO date	End date e.g. `2023-05-31`
`channel_id`	string	Filter by specific channel (optional)

Alerts

Configure real-time alerts for keyword detection, sentiment shifts, or ad appearances. Alerts can be delivered via webhook, email, or WebSocket push.

GET/alertsGet alert feed

POST/alerts/configConfigure alert triggers

DELETE/alerts/{id}Delete an alert config

Reports & Export

Export full analytics data in CSV, JSON, or PDF format for a specified time range.

GET/reports/exportExport analytics report

Parameter	Type	Description
`format`	string	`csv`, `json`, or `pdf`
`from`	ISO date	Start date
`to`	ISO date	End date
`channel_id`	string	Filter by channel (optional)

Data Deletion (GDPR)

Permanently delete all customer data associated with a record. This action is irreversible and covers all storage layers including database, blob storage, cache, and backups.

DELETE/data/{id}Permanently delete a data record

Irreversible: All records across PostgreSQL, Blob Storage, Redis, and AWS S3 backup will be purged within 30 days. A confirmation email is sent upon completion.

Rate Limits

Rate limits are applied per API key. Response headers include your current usage:

X-RateLimit-Limit — requests allowed per minute
X-RateLimit-Remaining — requests left in current window
X-RateLimit-Reset — Unix timestamp when window resets

Plan	Requests / min	Requests / day
Starter	60	10,000
Business	300	100,000
Enterprise	Unlimited	Unlimited

When rate limited, the API returns 429 Too Many Requests. Wait for the X-RateLimit-Reset timestamp before retrying.

SDKs & Libraries

Official SDKs are currently in development. In the meantime, use any HTTP client with the REST API directly using your preferred language:

Pythonimport requests

headers = {"Authorization": "Bearer ts_pub_YOUR_KEY"}
res = requests.get("https://api.tarrasmart.com/v1/channels", headers=headers)
print(res.json())

JavaScriptconst res = await fetch("https://api.tarrasmart.com/v1/channels", {
  headers: { "Authorization": "Bearer ts_pub_YOUR_KEY" }
});
const data = await res.json();

For integration support, API questions, or enterprise onboarding contact engineering@tarrasmart.com.

Tarrasmart API Reference