Dokumentasi Resmi

|tulis.org

Arsitektur Dokumentasi

Peta jalan panduan, SDK integration, dan API reference lengkap yang disiapkan secara terstruktur.

TULIS CMS/DEVELOPER HUB

/api-reference-ai-ai

API AI Admin Tulis

Endpoint penulisan berbantuan AI untuk platform Tulis. Endpoint ini membantu mengotomatiskan pembuatan konten SEO dan sosial saat membuat posting melalui API. Endpoint ini terbatas workspace dan harus dipanggil sebelum publikasi — mereka menghasilkan alat bantu penulisan (judul, deskripsi meta, taksonomi, cuplikan sosial) yang kemudian ditinjau dan dilampirkan oleh penulis ke posting.

Endpoint khusus admin. Setiap endpoint di halaman ini adalah ADMIN / TERAUTENTIKASI. Mereka memerlukan token Authorization: Bearer *** yang valid ditambah header X-Workspace-ID (atau subdomain workspace). Mereka BUKAN publik.

API publik (didokumentasikan di folder induk) TIDAK menyertakan endpoint AI apa pun. AI adalah alat bantu penulisan yang digunakan selama pembuatan konten, sebelum sebuah posting diterbitkan melalui permukaan publik.

Persyaratan server

Semua endpoint terdaftar di bawah /api melalui routes.RegisterAIRoutes(tenantGroup, ...), sehingga mereka berada di grup tenant yang sudah menegakkan JWT + pembatasan workspace.

Backend harus memiliki baik AI_API_KEY maupun AI_PROVIDER yang dikonfigurasi, jika tidak setiap permintaan mengembalikan:

{
  "error": "AI is not configured"
}

dengan status HTTP 503 SERVICE_UNAVAILABLE:

{
  "status": "SERVICE_UNAVAILABLE",
  "message": "AI is not configured. Set AI_API_KEY and AI_PROVIDER env vars.",
  "data": null
}

Autentikasi

Header	Wajib	Deskripsi
`Authorization`	Ya	`Bearer <jwt>` — token pengguna admin/terautentikasi
`X-Workspace-ID`	Ya	Identifier workspace target (atau gunakan subdomain workspace)

Ini bukan diautentikasi dengan kunci API. Auth kunci API publik tidak memberikan akses ke endpoint AI mana pun.

`POST /api/ai/generate-titles`

Menghasilkan saran judul yang dioptimalkan untuk SEO untuk topik tertentu.

Auth: JWT admin (Bearer token + X-Workspace-ID). Tidak publik.

Badan permintaan

Field	Tipe	Wajib	Deskripsi
`topic`	string	Ya	Subjek untuk menghasilkan judul
`keywords`	string	Tidak	Kata kunci opsional yang dipisahkan koma/spasi untuk mempengaruhi saran

{
  "topic": "Cara menanam hidroponik di rumah",
  "keywords": "sayuran, pemula, hemat tempat"
}

Respons

{
  "titles": [
    "Panduan Lengkap Menanam Hidroponik di Rumah untuk Pemula",
    "7 Sayuran Hidroponik yang Cocok Ditanam di Rumah",
    "Hidroponik Hemat Tempat: Solusi Bertanam di Hunian Sempit"
  ]
}

curl

curl -X POST "https://YOUR_HOST/api/ai/generate-titles" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: <WORKSPACE_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Cara menanam hidroponik di rumah",
    "keywords": "sayuran, pemula, hemat tempat"
  }'

`POST /api/ai/generate-meta`

Menghasilkan deskripsi meta SEO untuk judul dan konten posting.

Auth: JWT admin (Bearer token + X-Workspace-ID). Tidak publik.

Badan permintaan

Field	Tipe	Wajib	Deskripsi
`title`	string	Tidak	Judul posting
`content`	string	Tidak	Badan/konten posting

{
  "title": "Panduan Lengkap Menanam Hidroponik di Rumah",
  "content": "Hidroponik adalah metode bertanam tanpa tanah yang sangat cocok untuk hunian terbatas..."
}

Respons

{
  "description": "Pelajari cara menanam hidroponik di rumah dengan panduan lengkap untuk pemula, mulai dari alat, media, hingga perawatan tanaman sayur hemat tempat."
}

curl

curl -X POST "https://YOUR_HOST/api/ai/generate-meta" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: <WORKSPACE_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Panduan Lengkap Menanam Hidroponik di Rumah",
    "content": "Hidroponik adalah metode bertanam tanpa tanah yang sangat cocok untuk hunian terbatas..."
  }'

`POST /api/ai/suggest-taxonomies`

Menyarankan kategori dan tag untuk konten posting.

Auth: JWT admin (Bearer token + X-Workspace-ID). Tidak publik.

Badan permintaan

Field	Tipe	Wajib	Deskripsi
`title`	string	Tidak	Judul posting
`content`	string	Tidak	Badan/konten posting

{
  "title": "Panduan Lengkap Menanam Hidroponik di Rumah",
  "content": "Hidroponik adalah metode bertanam tanpa tanah yang sangat cocok untuk hunian terbatas..."
}

Respons

{
  "categories": ["Bertanam", "Hidup Hijau"],
  "tags": ["hidroponik", "sayuran", "pemula", "hemat tempat"]
}

curl

curl -X POST "https://YOUR_HOST/api/ai/suggest-taxonomies" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: <WORKSPACE_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Panduan Lengkap Menanam Hidroponik di Rumah",
    "content": "Hidroponik adalah metode bertanam tanpa tanah yang sangat cocok untuk hunian terbatas..."
  }'

`POST /api/ai/generate-snippets`

Menghasilkan cuplikan media sosial untuk posting, dengan nada Indonesia.

Auth: JWT admin (Bearer token + X-Workspace-ID). Tidak publik.

Badan permintaan

Field	Tipe	Wajib	Deskripsi
`title`	string	Tidak	Judul posting
`content`	string	Tidak	Badan/konten posting

{
  "title": "Panduan Lengkap Menanam Hidroponik di Rumah",
  "content": "Hidroponik adalah metode bertanam tanpa tanah yang sangat cocok untuk hunian terbatas..."
}

Respons

{
  "twitter": "🌱 Mau tanam sayur di rumah tapi tempat sempit? Hidroponik jawabannya! Simak panduan lengkap untuk pemula. #Hidroponik",
  "linkedin": "Bertanam hidroponik di rumah kini makin mudah. Panduan ini membahas alat, media tanam, hingga perawatan harian untuk hasil optimal meski hunian terbatas.",
  "facebook": "Tertarik menanam sendiri di rumah? Pelajari cara hidroponik yang hemat tempat dan cocok untuk pemula. Sayuran segar tanpa perlu lahan luas!"
}

twitter dijamin 280 karakter atau kurang.

curl

curl -X POST "https://YOUR_HOST/api/ai/generate-snippets" \
  -H "Authorization: Bearer ***" \
  -H "X-Workspace-ID: <WORKSPACE_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Panduan Lengkap Menanam Hidroponik di Rumah",
    "content": "Hidroponik adalah metode bertanam tanpa tanah yang sangat cocok untuk hunian terbatas..."
  }'

Lini Masa Peluncuran Fitur

Fase 1: Setup Awal & KonfigurasiSELESAI

Docker Compose, pengaturan file environment, dan panduan setup lokal telah lengkap dibuat.

Fase 2: Referensi RESTful APISELESAI

Dokumentasi route endpoint publik, otentikasi JWT, dan kontrol hak akses telah selesai disusun.

Fase 3: Integrasi Frontend & Fitur LanjutSEDANG BERJALAN

Mempersiapkan boilerplate untuk Next.js client, manajemen revisi konten, dan optimasi query.