Dokumentasi API

TELECLOUD
API DOCS

TeleCloud menyediakan REST API untuk warung konten digital — warung video, foto, dan kombinasi keduanya. Satu API key cukup untuk mengakses semua endpoint.

API ini dirancang untuk ringan, konsisten, dan mudah diintegrasikan ke aplikasi apapun — web, mobile, maupun bot Telegram.

💡

Semua response menggunakan format JSON dengan encoding UTF-8. Timestamp menggunakan Unix time (detik).

BASE URL #

Base URL

https://api.telecloud.id/v1

Semua endpoint diawali dengan base URL di atas. Versi API saat ini adalah v1.

AUTENTIKASI #

TeleCloud menggunakan API key berbasis header. Sertakan API key kamu di setiap request menggunakan header X-API-Key.

Header Autentikasi

X-API-Key: tc_live_xxxxxxxxxxxxxxxxxxxxxxxx

API key terdiri dari prefix tc_live_ diikuti 32 karakter alfanumerik. Kamu bisa mendapatkan API key setelah mendaftar dan membuat warung di dashboard.

⚠️

Jangan pernah expose API key di source code publik, client-side JavaScript, atau repository. Gunakan environment variable.

Contoh Request dengan API Key

cURL

curl https://api.telecloud.id/v1/ping \
  -H "X-API-Key: tc_live_xxxxxxxxxxxxxxxxxxxxxxxx"

JavaScript (fetch)

const res = await fetch('https://api.telecloud.id/v1/ping', {
  headers: {
    'X-API-Key': 'tc_live_xxxxxxxxxxxxxxxxxxxxxxxx'
  }
});
const data = await res.json();

PHP (cURL)

$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL           => 'https://api.telecloud.id/v1/ping',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER    => [
    'X-API-Key: tc_live_xxxxxxxxxxxxxxxxxxxxxxxx'
  ]
]);
$response = json_decode(curl_exec($ch), true);

Python (requests)

import requests

headers = {'X-API-Key': 'tc_live_xxxxxxxxxxxxxxxxxxxxxxxx'}
r = requests.get('https://api.telecloud.id/v1/ping', headers=headers)
data = r.json()

ERROR CODES #

TeleCloud menggunakan HTTP status code standar. Setiap response error menyertakan field error dan message untuk detail tambahan.

Contoh Response Error

{
  "status":  "error",
  "error":   "UNAUTHORIZED",
  "message": "API key tidak valid atau tidak ditemukan"
}

Status	Kode Error	Keterangan
200 OK	—	Request berhasil
401	`UNAUTHORIZED`	API key tidak valid, tidak ada, atau sudah expired
403	`FORBIDDEN`	Akses ke warung ini tidak diizinkan untuk API key ini
404	`NOT_FOUND`	Resource yang diminta tidak ditemukan
429	`RATE_LIMITED`	Terlalu banyak request. Lihat header `X-RateLimit-*`
500	`SERVER_ERROR`	Kesalahan internal server. Hubungi support jika berlanjut

Rate Limit Headers

Setiap response menyertakan header berikut untuk monitoring quota:

Response Headers

X-RateLimit-Limit:     600000   // Total quota per bulan
X-RateLimit-Remaining: 594821   // Sisa quota
X-RateLimit-Reset:     1748736000 // Unix timestamp reset
X-RateLimit-Window:    "1m"     // Window rate limit per menit

RATE LIMITS #

Rate limiting diterapkan per API key menggunakan Redis dengan dua lapisan: limit per menit (burst) dan limit bulanan (quota).

Plan	Quota Bulanan	Limit / Menit	Warung
STARTER	50.000 req	60 req/min	1
PRO	600.000 req	300 req/min	5
MASTER	1.000.000 req	600 req/min	20
HYBRID	∞ Unlimited	1.200 req/min	Unlimited

💡

Ketika terkena rate limit, tunggu hingga window berikutnya (1 menit) atau cek header X-RateLimit-Reset untuk mengetahui kapan quota reset.

ENDPOINT API #

Semua endpoint menggunakan metode GET kecuali disebutkan lain. Request dan response dalam format JSON.

GET /api/v1/ping Health check ▾

Cek status server dan validasi API key. Tidak membutuhkan parameter tambahan. Cocok untuk monitoring uptime.

Authentication

Endpoint ini tidak memerlukan API key. Bisa diakses publik.

Response

                200 OK
                200
              

{
  "status":    "ok",
  "message":   "pong",
  "warung":    "Warung Saya",
  "timestamp": 1746432000
}

GET /api/v1/config Konfigurasi warung ▾

Mengambil konfigurasi warung yang terikat dengan API key. Gunakan ini untuk mengetahui tipe warung dan fitur yang tersedia.

Response

                200 OK
                200
              

{
  "warung_type":    "C",          // "A" | "B" | "C"
  "warung_name":    "Warung Saya",
  "warung_domain":  "warungsaya.com",
  "content_types": ["video", "photo"],
  "features": {
    "has_video":     true,
    "has_album":     true,
    "has_player":    true,
    "has_download":  false
  }
}

GET /api/v1/media Daftar media dengan paginasi ▾

Mengambil daftar semua media (video dan/atau foto) milik warung dengan dukungan paginasi, sorting, dan filter tipe.

Query Parameters

Parameter	Tipe	Keterangan
pageopsional	integer	Halaman yang diminta. Default: `1`
limitopsional	integer	Jumlah item per halaman. Default: `20`, maks: `100`
typeopsional	string	Filter tipe: `video` atau `photo`. Kosong = semua
sortopsional	string	`newest` (default) \| `oldest` \| `popular`

Response

                200 OK
                200
              

{
  "status": "ok",
  "total":  1284,
  "page":   1,
  "limit":  20,
  "pages":  65,
  "data": [
    {
      "id":         101,
      "title":     "Judul Konten",
      "type":      "video",
      "thumbnail": "https://cdn.telecloud.id/thumb/101.jpg",
      "duration":  184,           // detik, null jika foto
      "views":     4820,
      "likes":     312,
      "tags":      ["tag1", "tag2"],
      "created_at": 1746100000
    }
  ]
}

GET /api/v1/media/:id Detail media ▾

Mengambil detail lengkap satu media berdasarkan ID-nya.

Path Parameters

Parameter	Tipe	Keterangan
idwajib	integer	ID media yang ingin diambil

Response

                200 OK
                200
              

{
  "status": "ok",
  "data": {
    "id":          101,
    "title":      "Judul Konten",
    "description": "Deskripsi konten...",
    "type":        "video",
    "thumbnail":   "https://cdn.telecloud.id/thumb/101.jpg",
    "duration":    184,
    "views":       4820,
    "likes":       312,
    "tags":        ["tag1", "tag2"],
    "related":     [98, 104, 107],
    "created_at":  1746100000
  }
}

GET /api/v1/trending Konten trending ▾

Mengambil daftar konten trending berdasarkan weighted score yang dihitung dari views, likes, dan recency dalam 24 jam terakhir.

Query Parameters

Parameter	Tipe	Keterangan
limitopsional	integer	Jumlah item. Default: `10`, maks: `50`
typeopsional	string	Filter tipe: `video` atau `photo`

Response

                200 OK
                200
              

{
  "status": "ok",
  "data": [
    {
      "id":          812,
      "title":      "Konten Viral",
      "type":        "video",
      "views":       14820,
      "likes":       1024,
      "score":       98.4,
      "player_url":  "https://cdn.telecloud.id/play?t=..."
    }
  ]
}

GET /api/v1/search Fulltext search ▾

Pencarian fulltext menggunakan MySQL MATCH AGAINST pada judul, deskripsi, dan tag konten.

Query Parameters

Parameter	Tipe	Keterangan
qwajib	string	Kata kunci pencarian. Minimal 2 karakter
pageopsional	integer	Halaman. Default: `1`
limitopsional	integer	Jumlah hasil. Default: `20`, maks: `50`

Response

                200 OK
                200
              

{
  "status":  "ok",
  "query":   "tutorial",
  "total":   47,
  "data": [
    {
      "id":     203,
      "title": "Tutorial Lengkap",
      "type":  "video",
      "score": 15.82     // relevance score
    }
  ]
}

GET /api/v1/tags Semua tag + jumlah konten ▾

Mengambil semua tag yang digunakan beserta jumlah konten di masing-masing tag, diurutkan dari yang terbanyak.

Query Parameters

Parameter	Tipe	Keterangan
mediaopsional	string	ID media untuk mendapatkan konten berdasarkan tag tertentu

Response

                200 OK
                200
              

{
  "status": "ok",
  "data": [
    { "tag": "viral",     "count": 284 },
    { "tag": "lifestyle",  "count": 193 },
    { "tag": "tutorial",   "count": 47  }
  ]
}

GET /api/v1/album/:id Detail album foto (Tipe B & C) ▾

Mengambil detail album beserta daftar foto di dalamnya. Hanya tersedia untuk warung Tipe B (Foto + Album) dan Tipe C (Video + Foto).

⚠️

Endpoint ini akan mengembalikan 403 FORBIDDEN pada warung Tipe A yang tidak memiliki fitur album.

Path Parameters

Parameter	Tipe	Keterangan
idwajib	integer	ID album yang ingin diambil

Response

                200 OK
                200
              

{
  "status": "ok",
  "album": {
    "id":         42,
    "title":     "Nama Album",
    "cover":     "https://cdn.telecloud.id/cover/42.jpg",
    "total":     18,
    "photos": [
      { "id": 1, "url": "https://cdn.telecloud.id/p/1.jpg" },
      { "id": 2, "url": "https://cdn.telecloud.id/p/2.jpg" }
    ]
  }
}

GET /api/v1/player-url/:id Signed URL untuk player ▾

Menghasilkan signed URL dengan TTL (time-to-live) untuk memainkan video secara aman. URL yang dihasilkan hanya berlaku selama 1 jam.

🔐

Signed URL dirancang untuk digunakan langsung pada client. Jangan cache URL ini melebihi batas expires_in-nya.

Path Parameters

Parameter	Tipe	Keterangan
idwajib	integer	ID media (hanya tipe video)

Response

                200 OK
                200
              

{
  "status":     "ok",
  "media_id":   812,
  "player_url": "https://cdn.telecloud.id/play/812?token=abc123&expires=1746435600",
  "expires_in": 3600   // detik
}

TIPE WARUNG #

Setiap warung memiliki tipe yang menentukan konten dan endpoint apa saja yang tersedia. Gunakan endpoint /config untuk cek tipe warung kamu.

Tipe A — Video Only

Warung khusus konten video. Mendukung player dengan signed URL dan tidak memiliki fitur album foto.

Endpoint	Tersedia
/media	✓ Video only
/trending	✓
/search	✓
/tags	✓
/album/:id	✗ Tidak tersedia
/player-url/:id	✓

Tipe B — Foto + Album

Warung konten foto dengan dukungan koleksi album. Tidak mendukung video player.

Endpoint	Tersedia
/media	✓ Photo only
/trending	✓
/search	✓
/tags	✓
/album/:id	✓
/player-url/:id	✗ Tidak tersedia

Tipe C — Video + Foto

Warung full-featured dengan dukungan video, foto, album, dan player URL. Semua endpoint tersedia.

Endpoint	Tersedia
/media	✓ Video + Photo
/trending	✓
/search	✓
/tags	✓
/album/:id	✓
/player-url/:id	✓

QUICK START #

Mulai gunakan TeleCloud API dalam 3 langkah:

✅

Daftar gratis di telecloud.id/daftar → buat warung → salin API key dari dashboard.

1. Cek koneksi

cURL

curl https://api.telecloud.id/v1/ping \
  -H "X-API-Key: YOUR_API_KEY"

2. Ambil daftar media

JavaScript

const API_KEY = 'tc_live_xxxxxxxxxxxxxxxxxxxxxxxx';
const BASE    = 'https://api.telecloud.id/v1';

async function getMedia(page = 1) {
  const res = await fetch(`${BASE}/media?page=${page}&limit=20`, {
    headers: { 'X-API-Key': API_KEY }
  });
  return res.json();
}

const data = await getMedia();
console.log(data.data); // array of media

3. Muat player video

JavaScript

async function playVideo(mediaId) {
  const res = await fetch(`${BASE}/player-url/${mediaId}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  const { player_url } = await res.json();
  document.getElementById('video').src = player_url;
}

BACKEND UNTUK WARUNG DIGITAL

SATU PLATFORM,TIGA JENIS WARUNG

SEMUA ENDPOINTYANG KAMU BUTUHKAN

MULAI GRATIS,SCALE SAAT BUTUH

SIAP SCALEWARUNG MU?

TELECLOUDAPI DOCS

BASE URL #

AUTENTIKASI #

Contoh Request dengan API Key

ERROR CODES #

Rate Limit Headers

RATE LIMITS #

ENDPOINT API #

Authentication

Response

Response

Query Parameters

Response

Path Parameters

Response

Query Parameters

Response

Query Parameters

Response

Query Parameters

Response

Path Parameters

Response

Path Parameters

Response

TIPE WARUNG #

Tipe A — Video Only

Tipe B — Foto + Album

Tipe C — Video + Foto

QUICK START #

1. Cek koneksi

2. Ambil daftar media

3. Muat player video

KONTAK

DMCA

Apa itu DMCA?

Cara Mengajukan Laporan DMCA

Proses & Waktu Penanganan

Counter-Notice

KEBIJAKAN PRIVASI

Data yang Kami Kumpulkan

Bagaimana Kami Menggunakan Data

Penyimpanan & Keamanan

Hak Kamu

Perubahan Kebijakan

BACKEND
UNTUK
WARUNG
DIGITAL

SATU PLATFORM,
TIGA JENIS WARUNG

SEMUA ENDPOINT
YANG KAMU BUTUHKAN

MULAI GRATIS,
SCALE SAAT BUTUH

SIAP SCALE
WARUNG MU?

TELECLOUD
API DOCS