# Pengenalan API (/api)

```txt
Base URL: https://api.tebar.app/v1
```

API ini dipakai oleh dashboard dan server MCP Tebar sendiri, jadi semua yang bisa dilakukan di sana juga bisa lewat API.

## Autentikasi [#autentikasi]

Buat API key di dashboard: menu akun → **API key** → **Buat API key**. Pilih akses **baca** atau **baca dan tulis**. Key utuh hanya ditampilkan sekali.

Kirim key di header `Authorization`:

```bash
curl https://api.tebar.app/v1/accounts \
  -H "Authorization: Bearer tb_live_xxx"
```

- Key **hanya** diterima lewat header, tidak pernah lewat query string.
- Tebar hanya menyimpan hash key, jadi key yang hilang tidak bisa ditampilkan lagi. Cabut dan buat yang baru.
- Maksimal 25 key aktif per akun.
- Akses `write` sekaligus mencakup `read`.

## Format [#format]

- Body dan respons berupa JSON dengan nama field `snake_case`.
- Waktu dalam ISO 8601. Kirim dengan zona waktu (`2026-10-15T09:00:00+07:00`); respons selalu dalam UTC.

## Pagination [#pagination]

```txt
GET /v1/posts?limit=20&cursor=...
```

```json
{ "data": [], "next_cursor": "..." }
```

`next_cursor` bernilai `null` di halaman terakhir. `limit` maksimal 100.

## Idempotensi [#idempotensi]

Kirim header `Idempotency-Key` saat membuat post. Bila request dengan key dan body yang sama terkirim ulang (misalnya karena timeout), Tebar mengembalikan post yang sudah dibuat, bukan membuat post baru. Key yang sama dengan body berbeda ditolak dengan `409 idempotency_conflict`.

```bash
curl -X POST https://api.tebar.app/v1/posts \
  -H "Authorization: Bearer tb_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"content":"Halo!","targets":[{"account_id":"..."}]}'
```

## Rate limit [#rate-limit]

Respons menyertakan header `RateLimit-Limit`, `RateLimit-Remaining`, dan `RateLimit-Reset`. Bila batas terlampaui, API membalas `429 rate_limited`.

## Endpoint utama [#endpoint-utama]

| Method | Path                               | Scope | Fungsi                                    |
| ------ | ---------------------------------- | ----- | ----------------------------------------- |
| GET    | `/me`                              | read  | Info akun dan jenis akses token           |
| GET    | `/accounts`                        | read  | Akun sosial yang terhubung                |
| GET    | `/accounts/{id}/publishing-limit`  | read  | Sisa kuota posting                        |
| POST   | `/posts`                           | write | [Buat post](/api/posts)                   |
| GET    | `/posts`, `/posts/{id}`            | read  | Daftar dan detail post                    |
| PATCH  | `/posts/{id}`                      | write | Ubah post terjadwal                       |
| DELETE | `/posts/{id}`                      | write | Batalkan post terjadwal                   |
| POST   | `/posts/{id}/publish`              | write | Terbitkan sekarang                        |
| POST   | `/posts/{id}/retry`                | write | Ulangi akun yang gagal                    |
| POST   | `/media/from-url`, `/media/upload` | write | [Upload media](/api/media)                |
| GET    | `/comments`                        | read  | [Komentar](/api/komentar-statistik)       |
| GET    | `/accounts/{id}/insights`          | read  | [Statistik akun](/api/komentar-statistik) |