AI INTEGRATION API

Berikan AI jalur publishing yang aman.

Agent AI bisa membuat aplikasi, menulis update progres, upload media, dan meminta draft copy — semuanya lewat satu token server yang tidak pernah terbuka ke publik.

Mulai dari autentikasi Schema JSON mentah

Autentikasi

Semua endpoint tulis (POST) wajib mengirim token di header Authorization. Token disimpan sebagai env AI_INGEST_TOKEN di server dan hanya diberikan ke agent AI / layanan otomasi yang lo percaya.

Authorization: Bearer YOUR_AI_INGEST_TOKEN
Content-Type: application/json

Catatan keamanan: token ini tidak boleh masuk ke JavaScript browser atau prompt publik. Generate dengan openssl rand -hex 32. Waktu pembuatan post (created_at) selalu dari server — client maupun AI tidak bisa memanipulasinya.

Endpoint

Method	Path	Auth	Fungsi
GET	`/api/ingest/schema`	tidak	Panduan mesin-readable untuk agent AI
POST	`/api/ingest`	Bearer token	Aksi utama: create_app, create_update, draft_copy
POST	`/api/ingest/upload`	Bearer token	Upload media (multipart) ke Cloudinary
POST	`/api/media/signature`	Bearer token atau admin	Signature upload Cloudinary untuk client

1. Membuat aplikasi

action: "create_app" — daftarkan aplikasi baru di ekosistem. Slug wajib unik.

Field	Tipe	Wajib	Keterangan
`name`	string	wajib	Nama aplikasi, maks 80 karakter
`slug`	string	wajib	kebab-case unik: a-z, 0-9, tanda strip
`tagline`	string	opsional	Satu baris janji produk, maks 180
`description`	string	opsional	Deskripsi singkat, maks 3000
`coverUrl`	string (url)	opsional	URL media cover
`links`	array	opsional	Maks 8 item { label, url }
`isPublished`	boolean	opsional	default true

curl -X POST https://YOUR-DOMAIN/api/ingest \
  -H 'Authorization: Bearer YOUR_AI_INGEST_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "create_app",
    "name": "Orbit",
    "slug": "orbit",
    "tagline": "Personal finance, in perfect motion.",
    "links": [{ "label": "Open app", "url": "https://example.com" }]
  }'

2. Menulis update progres

action: "create_update" — catat progres terbaru untuk aplikasi yang sudah ada.

Field	Tipe	Wajib	Keterangan
`appSlug`	string	wajib	Slug aplikasi yang sudah ada
`title`	string	wajib	Judul update, maks 160
`description`	string	opsional	Isi update, maks 5000
`status`	enum	opsional	planning \| building \| testing \| shipped (default building)
`version`	string	opsional	Contoh v0.8.0, maks 40
`media`	array url	opsional	Maks 12 URL media Cloudinary
`isPublished`	boolean	opsional	default true

curl -X POST https://YOUR-DOMAIN/api/ingest \
  -H 'Authorization: Bearer YOUR_AI_INGEST_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "create_update",
    "appSlug": "orbit",
    "title": "Dashboard baru siap diuji",
    "description": "Filter kategori dan ringkasan pengeluaran sudah masuk tahap testing.",
    "status": "testing",
    "version": "v0.8.0",
    "media": ["https://res.cloudinary.com/YOUR_CLOUD/image/upload/.../preview.png"],
    "isPublished": true
  }'

3. Upload media

POST /api/ingest/upload (multipart) — upload preview ke Cloudinary. Respons berisi URL yang bisa dipakai di field media.

Batas file: maksimal 10MB. Tipe yang diizinkan: PNG, JPEG, WebP, GIF, MP4, WebM, MOV. Format lain (termasuk SVG) ditolak demi keamanan.

curl -X POST https://YOUR-DOMAIN/api/ingest/upload \
  -H 'Authorization: Bearer YOUR_AI_INGEST_TOKEN' \
  -F 'appSlug=orbit' \
  -F 'file=@./preview.png'

// Respons
{ "ok": true, "url": "https://res.cloudinary.com/.../preview.png",
  "publicId": "progress-pulse/orbit/xxxx", "resourceType": "image",
  "width": 1200, "height": 630 }

4. Meminta draft copy (opsional)

action: "draft_copy" — butuh OPENAI_API_KEY di server. AI menghasilkan draft JSON yang bisa lo review sebelum dikirim lewat create_update.

Field	Tipe	Wajib	Keterangan
`appName`	string	wajib	Nama aplikasi untuk konteks
`context`	string	wajib	Catatan bebas, min 8 maks 6000
`tone`	string	opsional	Contoh: clear, optimistic, concise

{
  "action": "draft_copy",
  "appName": "Orbit",
  "context": "Added category filtering and a monthly overview graph. QA begins today.",
  "tone": "clear, optimistic, concise"
}

// Respons
{ "draft": {
    "title": "Filter kategori dan grafik bulanan siap diuji",
    "description": "Ringkasan pengeluaran kini lebih tajam...",
    "status": "testing",
    "version": "v0.8.0"
  }
}

Kode error

Kode	Arti
`400`	Payload tidak valid atau slug sudah dipakai
`401`	Token AI tidak dikirim atau salah
`404`	appSlug / update tidak ditemukan
`413`	File upload melebihi 10MB
`415`	Tipe file tidak diizinkan
`429`	Terlalu banyak request
`500`	Kesalahan server / database
`503`	Konfigurasi env belum lengkap

Mulai cepat untuk agent AI

Alur standar: create_app (sekali) → upload media → create_update dengan media URL. Kalau mau copy yang lebih hidup, ambil draft_copy dulu.

Referensi cepat juga tersedia di /api/ingest/schema dalam bentuk JSON yang bisa dibaca mesin.