Documentation

Tarrasmart API Reference

Build powerful broadcast monitoring integrations using the Tarrasmart REST API. All endpoints are secured via HTTPS with OAuth 2.0 / JWT authentication.

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.

Base URL: All API requests must be sent to https://api.tarrasmart.com/v1/

Authentication

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

HTTPAuthorization: Bearer YOUR_API_KEY
Content-Type: application/json

Example Request

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

Base URL & Environments

Environment	Base URL
Production	`https://api.tarrasmart.com/v1`
Sandbox (testing)	`https://sandbox-api.tarrasmart.com/v1`

Error Handling

All errors return a consistent JSON structure with an HTTP status code:

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

Status	Meaning
`200`	Success
`400`	Bad Request — check request body
`401`	Unauthorized — invalid API key
`403`	Forbidden — insufficient permissions
`429`	Rate Limit Exceeded
`500`	Internal Server Error

Channels

GET/channelsList all monitored channels

POST/channelsAdd a new 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 language code (e.g. `id`, `en`, `ja`)
`enable_asr`	boolean	optional	Enable speech recognition (default: true)
`enable_ad_tracking`	boolean	optional	Enable ad detection (default: true)

Stream Ingestion

POST/streams/ingestSubmit a media file for AI processing

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

Transcripts (ASR)

GET/streams/{id}/transcriptGet ASR transcript for a processed stream

JSON Response{
  "stream_id": "str_xyz789",
  "language": "id",
  "accuracy": 0.97,
  "segments": [
    { "start": 0.0, "end": 3.4, "text": "Selamat pagi, ini adalah berita terkini..." },
    { "start": 3.5, "end": 7.1, "text": "Presiden mengumumkan kebijakan baru..." }
  ]
}

Analytics

GET/analytics/sentimentSentiment analysis results by channel/date

GET/analytics/adsAd appearance tracking report

GET/analytics/keywordsKeyword frequency analysis

Alerts

GET/alertsGet real-time alert feed

POST/alerts/configConfigure alert triggers

Reports & Export

GET/reports/exportExport analytics as CSV, JSON, or PDF

Parameter	Type	Description
`format`	string	`csv`, `json`, or `pdf`
`from`	ISO date	Start date e.g. `2026-05-01`
`to`	ISO date	End date e.g. `2026-05-31`
`channel_id`	string	Filter by channel (optional)

Data Deletion (GDPR)

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

Note: Data deletion is irreversible. All records across PostgreSQL, Blob Storage, Redis cache, and backup (AWS S3) will be purged within 30 days. A confirmation email will be sent.

Rate Limits

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

Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset.

SDKs & Libraries

Official SDKs are coming soon. In the meantime, use any HTTP client with the REST API directly. For integration support contact engineering@tarrasmart.com.