> ## Documentation Index
> Fetch the complete documentation index at: https://docs.csku.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Referensi API

> Pelajari struktur dan desain CSKU AI API Publik

## URL Dasar

Semua permintaan API harus dikirim ke:

```
https://api.csku.ai
```

## Arsitektur API

CSKU AI API Publik mengikuti konvensi RESTful dan menyediakan endpoint untuk:

* **Pemeriksaan Kesehatan** - Memantau status dan versi sistem
* **Pengelolaan Pesan** - Mengirim dan mengambil pesan
* **Pengelolaan Catatan** - Mengirim catatan internal
* **Pengelolaan Percakapan** - Mengelola percakapan dan intervensi manusia

## Format Permintaan

### Content-Type

Semua permintaan POST harus menyertakan:

```
Content-Type: application/json
```

### Autentikasi

Sertakan header autentikasi (lihat [Autentikasi](/authentication)):

**Metode 1: Header Terpisah**

```http theme={null}
Business: your_biz_id
Secret: your_secret_key
```

**Metode 2: Header Authorization**

```http theme={null}
Authorization: Bearer {base64_encoded_credentials}
```

## Format Respons

### Respons Sukses

Respons sukses mengikuti struktur ini:

```json theme={null}
{
  "status": 1,
  "message": "Sukses",
  "data": { ... }
}
```

### Respons Error

Error mengikuti format yang konsisten:

```json theme={null}
{
  "status": 0,
  "rc": 400,
  "error_msg": "Deskripsi pesan error"
}
```

<Callout type="error">
  Selalu periksa field `status`. Nilai `1` menunjukkan sukses, sedangkan `0` menunjukkan error.
</Callout>

## Kode Status HTTP

| Kode | Deskripsi                                                   |
| ---- | ----------------------------------------------------------- |
| 200  | Sukses - Permintaan berhasil diselesaikan                   |
| 400  | Permintaan Buruk - Parameter atau data tidak valid          |
| 401  | Tidak Terotorisasi - Autentikasi tidak valid atau tidak ada |
| 403  | Terlarang - Izin tidak mencukupi                            |
| 404  | Tidak Ditemukan - Sumber daya tidak ditemukan               |
| 429  | Terlalu Banyak Permintaan - Batas rate terlampaui           |
| 500  | Kesalahan Server Internal - Error sisi server               |

## Versi API

Versi API saat ini: **v1.3**

Endpoint versi:

```
GET /version
```

## Tipe Media

API mendukung tipe media berikut:

| Tipe     | Deskripsi    | Contoh Tipe MIME                    |
| -------- | ------------ | ----------------------------------- |
| image    | File gambar  | image/jpeg, image/png, image/gif    |
| video    | File video   | video/mp4, video/avi                |
| audio    | File audio   | audio/mp3, audio/wav                |
| document | File dokumen | application/pdf, application/msword |

## Paginasi

Saat ini, pengambilan pesan tidak mendukung paginasi. Semua pesan dalam percakapan dikembalikan dalam satu permintaan.

<Note>
  Versi mendatang akan menyertakan dukungan paginasi untuk percakapan yang besar.
</Note>

## Pembatasan Rate

API menerapkan pembatasan rate:

| Tipe Permintaan      | Batas                |
| -------------------- | -------------------- |
| Terautentikasi       | 100 permintaan/menit |
| Tidak Terautentikasi | 10 permintaan/menit  |

Informasi batas rate disertakan dalam respons error ketika batas terlampaui.

## Webhooks

Untuk notifikasi real-time, konfigurasikan webhooks di pengaturan bisnis Anda:

**Event yang Didukung:**

* `message.incoming` - Pesan baru diterima
* `message.sent` - Pesan berhasil dikirim
* `conversation.assigned` - Percakapan ditugaskan ke manusia

<Callout type="info">
  Konfigurasi webhook dilakukan melalui dashboard, bukan melalui API.
</Callout>

## Penanganan Error

### Memeriksa Error

Selalu periksa field `status` dalam respons:

```javascript theme={null}
const response = await fetch(...);
const data = await response.json();

if (data.status === 0) {
  console.error('Error:', data.error_msg);
  // Tangani error berdasarkan rc (kode respons)
  switch(data.rc) {
    case 401:
      // Tidak terotorisasi - periksa kredensial
      break;
    case 400:
      // Permintaan buruk - periksa parameter
      break;
    case 429:
      // Rate terbatas - terapkan backoff
      break;
    default:
      // Error lainnya
  }
}
```

### Kode Error Umum

| Kode | Deskripsi                 | Tindakan                        |
| ---- | ------------------------- | ------------------------------- |
| 400  | Permintaan Buruk          | Periksa parameter permintaan    |
| 401  | Tidak Terotorisasi        | Verifikasi kredensial           |
| 403  | Terlarang                 | Periksa izin                    |
| 404  | Tidak Ditemukan           | Verifikasi sumber daya ada      |
| 429  | Terlalu Banyak Permintaan | Terapkan backoff dan coba lagi  |
| 500  | Error Internal            | Hubungi dukungan jika berlanjut |

## Praktik Terbaik

1. **Selalu periksa field `status`** sebelum memproses data respons
2. **Terapkan logika retry** untuk error 5xx dengan exponential backoff
3. **Gunakan timeout yang sesuai** untuk permintaan API
4. **Validasi data input** sebelum membuat permintaan
5. **Tangani batas rate** dengan baik menggunakan strategi backoff
6. **Jaga keamanan kredensial** - jangan pernah ekspos di kode sisi klien

## Dukungan

Untuk dukungan teknis atau pertanyaan:

* Email: [support@csku.ai](mailto:support@csku.ai)
* Dokumentasi Lengkap: [https://docs.csku.ai](https://docs.csku.ai)