API key

API key bikin kodemu sendiri bisa ngobrol sama Publiz: menjadwalkan post dari CMS-mu, menarik aset ke proses build, atau menjalankan job AI lewat script. Satu key melekat ke satu workspace dan cuma membawa scope yang kamu kasih.

Mau asisten AI seperti Claude yang pakai Publiz buatmu? Key yang sama bisa dipakai, lihat Hubungkan asisten AI.

Tempatnya di Developer lalu API Keys di sidebar.

Bikin satu

1. Klik Create API Key.

2. Kasih nama yang nanti kamu kenali. Cuma itu cara membedakan key setelah dibuat, jadi “Zapier automation” jauh lebih berguna daripada “key 2”.

3. Centang resource yang dibutuhin. Yang nggak bisa dikasih paketmu tampil abu-abu dengan label Not on your plan.

   

4. Kalau mau, set tanggal kedaluwarsa. Dikosongin berarti key-nya jalan sampai kamu cabut. Mengisinya layak buat sesuatu yang berumur pendek, misalnya script migrasi. Tanggalnya bisa digeser atau dihapus nanti lewat Edit.

5. Klik Create. Key-nya muncul sekali.

Salin key-nya saat itu juga

Key lengkapnya ditampilkan sekali, tepat setelah dibuat. Publiz cuma menyimpan hash-nya, jadi nggak ada yang bisa menunjukkannya lagi, termasuk kami. Kalau hilang, satu-satunya jalan adalah me-reset key itu, yang menerbitkan key baru dan bikin apa pun yang memakai key lama berhenti jalan.

Key bentuknya publiz_sk_ diikuti 64 karakter. Setelah dibuat, daftarnya cuma menampilkan bagian awalnya sebagai prefix, misalnya publiz_sk_7f3a…, yang sudah cukup buat tahu sebuah baris log punya key yang mana. Key yang dibuat sebelum format baru diawali pk_ dan tetap jalan seperti biasa.

Scope

Sebuah key cuma menjangkau yang kamu centang. Kasih tiap integrasi sesedikit mungkin — key yang cuma menerbitkan post nggak bisa sekalian menghapus mediamu.

Scope	Cakupannya
Posts	Baca, bikin, ubah, hapus, terbitkan, dan coba ulang post
Tags	Daftar, bikin, ganti nama, dan hapus tag post, biar bisa dipasang ke post
Signatures	Daftar, tulis, ubah, dan hapus signature, biar bisa dipilih per akun atau per post
Personas	Daftar, bikin, ubah, duplikat, dan hapus persona. Menghapus butuh key buatan pemilik workspace
Ideas	Baca dan kelola ide konten, termasuk men-generate
Media	Daftar, unduh, unggah, dan hapus aset
Webhooks	Bikin, ubah, tes, dan hapus webhook, plus baca atau kirim ulang pengirimannya
Usage	Cuma baca. Pemakaian paket dan saldo kredit AI serta X
Accounts	Menampilkan akun yang terhubung. Cuma baca, nggak bisa menghubungkan akun lewat API
Members	Daftar member dan undangan, undang lewat email, keluarkan member
Analytics	Cuma baca. Total workspace dan analitik per post
AI	Menjalankan tool AI
Insights	Cuma baca. Waktu terbaik posting, engagement harian, peringkat post, dan riwayat follower
Channels	Lihat kesehatan koneksi tiap channel, ubah pengaturan channel (signature yang dipakai, privasi TikTok, opsi X), putuskan koneksinya
Automation	Kelola aturan balas komentar otomatis beserta template balasan yang dikirimnya, dan lihat apa saja yang sudah dijalankan

Scope cuma-baca

Scope apa pun yang bisa mengubah sesuatu juga bisa dikasih read only. Centang scope-nya, lalu nyalakan Read only di bagian Access pada dialog bikin atau edit. Key-nya tetap bisa menampilkan dan mengambil data, tapi semua yang membuat, mengubah, atau menghapus dapat 403 dengan kode READ_ONLY_KEY. Cocok buat dashboard dan script laporan yang nggak boleh menyentuh kontenmu.

Beberapa hal yang perlu diketahui:

• Usage, Analytics, Insights, dan Accounts memang cuma-baca, jadi nggak punya tombol.
• Menghitung harga job AI lewat path /estimate dihitung sebagai baca, jadi key AI yang cuma-baca tetap bisa mengecek biayanya.
• Aturannya sama di semua route, dan scope-nya tampil sebagai read only di daftar key.

Endpoint member butuh key yang dibuat pemilik workspace, aturannya sama dengan di dashboard.

Channel nggak bisa dihubungkan lewat API, dan API juga nggak bisa menyuruh Publiz sinkron ulang post atau refresh statistik dari platform. Semua itu tetap di dashboard, supaya script yang kebablasan nggak menghabiskan batas rate platform untuk semua orang.

Scope mana yang bisa kamu kasih tergantung level API access paketmu, nama yang sama dengan yang kamu lihat di halaman harga. Tiap level sudah mencakup semua yang ada di level sebelumnya.

Paket	API access	Jumlah key	Scope yang tersedia
Free	Posts + usage	1	Posts, Usage, Signatures
Starter	Standard	1	semua di atas, plus Tags, Personas, Ideas, Media, dan Webhooks
Creator	Standard	1	semua di atas, plus Tags, Personas, Ideas, Media, dan Webhooks
Pro	Advanced	3	semua di atas, plus Accounts, Members, dan Analytics
Agency	Full	5	semuanya, termasuk AI, Insights, Channels, dan Automation

Kalau kamu pindah ke paket dengan level lebih rendah, key-mu tetap jalan. Scope yang nggak dicakup paket barunya cuma berhenti dihormati, dan dialog edit menandainya Kept from a previous plan. Naik lagi dan scope-nya jalan lagi, nggak perlu bikin ulang apa pun.

Webhook cuma ada di paket berbayar. Di Free kamu bisa posting dan mengelola signature lewat API, tapi nggak bisa bikin webhook.

Scope cuma membuka pintunya, batas paket fiturnya tetap berlaku. Tag mulai dari Starter, dan tiap paket membatasi jumlah persona dan template balasan per workspace, jadi kalau lewat batas jawabannya sama seperti di dashboard.

Halamannya menampilkan posisimu, misalnya “2 of 3 keys used”. Kalau sudah mentok, tombol Create API Key mati sampai kamu mencabut salah satu.

Member butuh izin

Member workspace cuma melihat halaman ini kalau sudah dikasih izin API keys. Owner selalu punya. Dengan izin itu, member bisa bikin key, mengubah scope dan masa berlakunya, dan membaca log-nya. Reset dan cabut tetap di tangan owner, karena keduanya bisa memutus integrasi yang sedang jalan. Lihat workspace dan member.

Memakai key-nya

Kirim sebagai Bearer token di header Authorization. API-nya ada di https://api.publiz.app/v1.

curl https://api.publiz.app/v1/me \
  -H "Authorization: Bearer publiz_sk_key_kamu_di_sini"

Header X-API-Key: publiz_sk_key_kamu_di_sini juga bisa, kalau tool-mu lebih gampang begitu. Pilih salah satu, hasilnya sama.

/me panggilan pertama yang berguna: dia ngasih tahu key-nya milik workspace mana dan memegang scope apa saja, tanpa butuh scope apa pun.

Bikin post kira-kira begini:

curl -X POST https://api.publiz.app/v1/posts \
  -H "Authorization: Bearer publiz_sk_key_kamu_di_sini" \
  -H "Content-Type: application/json" \
  -d '{"content": "Batch baru barusan mendarat.", "platforms": ["bluesky"]}'

Daftar endpoint lengkapnya, beserta scope yang dibutuhkan masing-masing, ada di referensi API. SDK resmi TypeScript, Go, dan Dart segera hadir, jadi untuk sekarang kamu panggil REST API-nya langsung.

Satu hal yang nggak bisa dilakukan sebuah key: mengelola API key. Membuat, me-reset, dan mencabut key semuanya butuh user yang login, jadi sebuah key nggak akan pernah bisa menerbitkan key lain.

Generate AI itu asinkron

Endpoint AI menjawab 202 beserta jobId, bukan hasil jadinya. Poll GET /v1/ai/jobs/{jobId} sampai status jadi COMPLETED atau FAILED. Kamu juga bisa menghitung harga sebuah job sebelum menjalankannya dengan mengirim body yang sama ke path /estimate milik tool itu, dan itu nggak memotong kredit.

Satu-satunya pengecualian adalah POST /v1/ai/first-comment, yang menulis teks pendek dan langsung menjawab dengan teksnya. Path /estimate-nya juga ada, dan nggak ada yang disimpan: taruh teksnya di platformContents[].firstComment sebuah postingan.

Batas permintaan

Ada dua jenis batas, dan sebuah request harus muat di keduanya.

Batas harian

Tiap paket punya jatah request per workspace, per hari. Semua key di workspace itu memakai jatah yang sama, dan hitungannya mulai lagi pukul 00:00 UTC.

Paket	Request per hari
Free	100
Starter	200
Creator	1.000
Pro	10.000
Agency	50.000

Tiap respons ngasih tahu posisimu:

Header	Artinya
X-RateLimit-Limit	Batas harian paketmu
X-RateLimit-Remaining	Sisa request hari ini
X-RateLimit-Reset	Kapan hitungannya reset, dalam Unix timestamp

Kalau lewat batas, kamu dapat 429 dengan kode DAILY_LIMIT_REACHED, plus header Retry-After berisi jumlah detik sampai tengah malam UTC. GET /v1/workspace/usage juga mengembalikan angka yang sama di apiRequests, kalau key-mu punya scope Usage.

Batas per menit

Batas ini per key, per menit, dan beda-beda tergantung jenis panggilannya:

Jenis permintaan	Per menit
Baca, termasuk polling status job	600
Tulis ke post dan ide	60
Unggah	30
Generate AI	10

Generate paling ketat karena tiap job memotong kredit dan memanggil provider. Kalau kamu memproses banyak sekaligus, kasih jeda kecil antar job daripada menembakkan semuanya berbarengan.

Mengulang dengan aman

Jaringan bisa putus. Kalau sebuah POST timeout, kamu nggak tahu apakah Publiz sudah menerimanya, dan mengirim ulang bisa bikin post-nya dobel. Header Idempotency-Key menyelesaikan itu.

curl -X POST https://api.publiz.app/v1/posts \
  -H "Authorization: Bearer publiz_sk_key_kamu_di_sini" \
  -H "Idempotency-Key: 4f1c2b9e-order-1042" \
  -H "Content-Type: application/json" \
  -d '{"content": "Batch baru barusan mendarat.", "platforms": ["bluesky"]}'

Pakai string unik apa saja sampai 255 karakter, misalnya UUID atau nomor order-mu sendiri. Lalu:

• Request pertama jalan seperti biasa.
• Mengirim key yang sama dengan body yang sama dalam 24 jam mengembalikan respons pertama, dengan header Idempotent-Replayed: true, dan nggak ada yang jalan dua kali.
• Key yang sama dengan body berbeda dapat 422. Request baru butuh key baru.
• Kalau request pertama masih jalan, pengulangannya dapat 409. Tunggu sebentar lalu coba lagi.
• Error server (5xx) dan respons batas rate nggak disimpan, jadi yang itu bisa diulang dengan key yang sama.

Ini berlaku di semua POST. Estimasi mengabaikannya, karena nggak mengubah apa pun.

Log request

Tab Logs di halaman API Keys menampilkan semua request dari key workspace itu, yang terbaru di atas: kapan terjadi, key mana, method dan endpoint, status, berapa lama, dan dari IP mana. Filter berdasarkan key, status (2xx, 4xx, 5xx), method, atau tanggal, dan request yang diulang ditandai Replayed.

Yang disimpan cuma detail tiap request, bukan isi yang dikirim atau dikembalikan, jadi kontenmu dan token-mu nggak ikut masuk log.

Berapa lama log disimpan tergantung paketmu:

Paket	Disimpan selama
Free	1 hari
Starter	3 hari
Creator	7 hari
Pro	30 hari
Agency	90 hari

Rotasi dan pencabutan

Tiap baris punya tiga aksi:

• Edit (pensil) mengubah scope yang dipegang sebuah key dan kapan dia kedaluwarsa, tanpa mengubah key-nya. Nggak ada yang perlu di-deploy ulang. Pilih No expiry buat menghapus tanggalnya.
• Reset (panah) menerbitkan key baru buat baris yang sama, nama dan scope-nya tetap. Key lama langsung berhenti jalan, dan yang baru ditampilkan sekali, sama kayak waktu dibuat. Ini yang dipakai kalau sebuah key bocor.
• Revoke (tong sampah) menghapus key-nya permanen. Nggak bisa dibatalkan.

Reset dan revoke cuma muncul untuk owner workspace.

Kolom Usage menampilkan berapa request yang dibuat tiap key hari ini dan kapan terakhir dipakai. Key yang sudah berbulan-bulan nggak dipakai biasanya aman dicabut. Key yang sudah lewat tanggal kedaluwarsanya ditandai Expired.

Key yang bocor itu key yang hidup

Sebuah key jalan dari mana pun sampai di-reset atau dicabut, dan dia bisa melakukan semua yang diizinkan scope-nya. Jauhkan key dari kode sisi klien dan dari git, dan reset begitu kamu curiga dia kebuka.

Kalau nggak jalan

missing API key: key-nya nggak sampai ke kami. Cek ejaan header-nya, pastikan Bearer token diawali kata Bearer dan spasi, dan klienmu nggak membuang header waktu kena redirect.

unauthorized: invalid api key: key-nya salah, atau sudah di-reset atau dicabut. Bandingkan prefix di error dengan prefix yang ada di halaman ini.

unauthorized: api key expired: key-nya punya tanggal kedaluwarsa dan tanggalnya sudah lewat. Buka Edit lalu geser tanggalnya atau pilih No expiry, dan key yang sama jalan lagi.

429 dengan DAILY_LIMIT_REACHED: workspace-mu sudah menghabiskan jatah request hari ini. Jatahnya balik pukul 00:00 UTC, dan Retry-After ngasih tahu berapa lama lagi. Kalau sering kena, paket di atasnya punya jatah lebih besar.

403 dengan READ_ONLY_KEY: key-nya memegang scope itu dalam mode cuma-baca. Edit key-nya dan matikan Read only untuk scope itu, atau pakai key lain untuk menulis.

403 yang menyebut resource tertentu: key-nya valid tapi nggak memegang scope itu. Edit dan centang resource-nya, selama paketmu mengizinkan.

“the … scope is not enabled on your plan”: masalah yang beda, dan kalimatnya sengaja dibedakan. Key-nya memang memegang scope itu, tapi paketmu sudah nggak mencakupnya lagi. Ini yang muncul setelah turun paket: scope-nya tetap kelihatan di halaman, ditandai Kept from a previous plan, dan berhenti jalan sampai kamu naik paket lagi.

404 di sesuatu yang kamu kira ada: cek path-nya di referensi API.

403 di webhook atau ideas pada paket gratis. Key di Free bisa dipakai untuk post dan membaca usage. Sisanya, termasuk webhook, mulai dari Starter.