Cara menggunakan API Publik Postoria

API Publik Postoria memungkinkan Anda menghubungkan alat eksternal, skrip, dan sistem internal ke Postoria.

Anda dapat menggunakannya untuk menghubungkan dan menghubungkan kembali akun sosial, menampilkan ruang kerja dan akun yang terhubung, mengunggah media, membuat dan mengelola postingan, serta mengambil analitik postingan terkini atau gabungan.

API Publik tersedia pada paket Pro dan Agency.

Sebelum memulai

Berikut hal-hal utama yang perlu diketahui sebelum menggunakan API:

• Anda memerlukan paket Pro atau Agency yang aktif.
• Setiap akun Postoria dapat memiliki satu kunci API aktif.
• Kunci API berlaku pada tingkat akun, bukan tingkat ruang kerja.
• Endpoint khusus ruang kerja memerlukan workspace_id dalam URL.
• API menggunakan autentikasi token bearer.
• API memiliki batas 300 permintaan per 5 menit untuk setiap akun.
• Pemrosesan media bersifat asinkron.
• Respons API menggunakan kolom JSON snake_case.
• API v1 menggunakan awalan jalur /v1.

URL dasar

Gunakan URL dasar berikut:

https://api.postoria.io/v1

Dokumentasi API tersedia di sini: https://api.postoria.io/v1/docs/.

Dokumen OpenAPI tersedia di sini: https://api.postoria.io/v1/openapi.json.

Membuat kunci API

1. Buka Postoria.
2. Buka Pengaturan.
3. Temukan bagian Public API, server MCP, dan integrasi n8n.
4. Klik Buat kunci API.
5. Salin kunci dan simpan dengan aman.

Postoria hanya menampilkan kunci API lengkap satu kali. Setelah dialog ditutup, Anda hanya akan melihat awalan kuncinya.

Jika Anda kehilangan kunci, cabut kunci tersebut dan buat yang baru.

Mengautentikasi permintaan

Kirim kunci API di header Authorization:

Authorization: Bearer pst_live_your_api_key

Contoh:

curl https://api.postoria.io/v1/workspaces \
  -H "Authorization: Bearer pst_live_your_api_key"

Jika kunci tidak disertakan, tidak valid, atau sudah dicabut, Postoria mengembalikan 401 invalid_api_key.

Format respons

Respons untuk satu sumber daya mengembalikan objek secara langsung.

Respons daftar menggunakan format berikut:

{
  "data": [],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Jika endpoint daftar mendukung paginasi, has_more memberi tahu apakah halaman berikutnya tersedia. Gunakan next untuk meminta halaman berikutnya secara langsung, atau kirim next_cursor yang dikembalikan sebagai parameter kueri cursor.

Respons kesalahan menggunakan format berikut:

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Batas permintaan

API Publik mengizinkan:

300 requests per 5 minutes per account

Jika Anda melampaui batas, Postoria mengembalikan 429 rate_limit_exceeded beserta header untuk percobaan ulang.

Contoh:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1770000000

Endpoint

API Publik v1 mencakup endpoint berikut:

GET    /v1/workspaces

GET    /v1/social-account-connection-options
POST   /v1/workspaces/{workspace_id}/social-account-connections
GET    /v1/workspaces/{workspace_id}/social-account-connections/{state}
POST   /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts
POST   /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect

GET    /v1/workspaces/{workspace_id}/social-accounts
PATCH  /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
GET    /v1/workspaces/{workspace_id}/queues

POST   /v1/workspaces/{workspace_id}/media/uploads
POST   /v1/workspaces/{workspace_id}/media/{media_id}/complete
POST   /v1/workspaces/{workspace_id}/media/imports
GET    /v1/workspaces/{workspace_id}/media/{media_id}

POST   /v1/workspaces/{workspace_id}/posts
GET    /v1/workspaces/{workspace_id}/posts
GET    /v1/workspaces/{workspace_id}/posts/{post_id}
DELETE /v1/workspaces/{workspace_id}/posts/{post_id}

GET    /v1/workspaces/{workspace_id}/analytics/posts
GET    /v1/workspaces/{workspace_id}/analytics/post-performance/summary

Menampilkan daftar ruang kerja

Gunakan endpoint ini untuk mendapatkan ruang kerja yang tersedia bagi akun Anda:

GET /v1/workspaces

Contoh respons:

{
  "data": [
    {
      "id": 1,
      "name": "My Workspace",
      "timezone": "America/New_York"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Gunakan id yang dikembalikan sebagai workspace_id dalam endpoint khusus ruang kerja.

Menghubungkan atau menghubungkan kembali akun sosial

API Publik menggunakan alur OAuth interaktif untuk menghubungkan akun sosial baru atau memperbarui otorisasi akun yang sudah ada. Aplikasi Anda memulai otorisasi, membuka URL penyedia yang dikembalikan untuk pengguna, dan memeriksa status koneksi setelah penyedia mengarahkan pengguna kembali ke Postoria.

Alur otorisasi yang sama dapat mengembalikan akun baru maupun akun yang sudah ada:

• connectable_accounts berisi akun penyedia yang belum terhubung di ruang kerja yang ditentukan.
• reconnectable_accounts berisi akun yang sudah ada di ruang kerja tersebut dan dapat diotorisasi ulang dengan izin OAuth yang telah selesai diberikan.

Setelah memeriksa daftar ini, panggil endpoint penghubungan dengan PID penyedia, endpoint penghubungan kembali dengan ID akun Postoria, atau kedua endpoint jika sesuai.

Menampilkan opsi penghubungan

Dapatkan jejaring sosial dan metode autentikasi yang saat ini tersedia melalui API Publik:

GET /v1/social-account-connection-options

Contoh respons:

{
  "data": [
    {
      "network": "facebook",
      "auth_methods": [
        "facebook_login",
        "meta_business_portfolio"
      ]
    },
    {
      "network": "instagram",
      "auth_methods": [
        "instagram_login",
        "facebook_login",
        "meta_business_portfolio"
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Jangan menanamkan contoh respons sebagai daftar lengkap dalam kode. Gunakan endpoint ini sebagai acuan karena opsi yang didukung dapat berubah.

Rilis awal mendukung opsi berikut:

Jejaring	Metode autentikasi
facebook	facebook_login, meta_business_portfolio
instagram	instagram_login, facebook_login, meta_business_portfolio
linkedin	linkedin_login
tumblr	tumblr_login
youtube	google_login
pinterest	pinterest_login
tiktok	tiktok_api_for_business
google_business_profile	google_login
threads	threads_login

Memulai otorisasi

Buat status koneksi untuk ruang kerja:

POST /v1/workspaces/{workspace_id}/social-account-connections

Contoh permintaan:

{
  "network": "instagram",
  "auth_method": "instagram_login"
}

Respons berhasil (201 Created):

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "is_completed": false,
  "authorization_url": "https://www.instagram.com/oauth/authorize?...",
  "expires_at": "2026-09-07T11:25:28.222872Z"
}

Buka authorization_url di browser dan biarkan pengguna menyelesaikan alur penyedia. Penyedia mengarahkan browser ke callback yang dihosting Postoria, yang mencatat hasil OAuth untuk state. Aplikasi Anda tidak perlu menyediakan URL pengembalian atau memanggil endpoint penyelesaian terpisah.

Status ini kedaluwarsa satu jam setelah dibuat. Mulai otorisasi baru jika expires_at telah lewat. Status yang kedaluwarsa, atau status milik ruang kerja atau akun Postoria lain, mengembalikan 404 social_account_connection_not_found.

Memeriksa hasil otorisasi

Setelah pengguna menyelesaikan alur penyedia, minta status koneksi:

GET /v1/workspaces/{workspace_id}/social-account-connections/{state}

Anda dapat melakukan polling pada endpoint ini selama is_completed bernilai false. Nilai tersebut menandakan bahwa Postoria belum menerima dan menyimpan callback OAuth; kolom ini tidak menunjukkan apakah akun sudah dihubungkan atau dihubungkan kembali.

Contoh respons setelah selesai:

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "is_completed": true,
  "expires_at": "2026-09-07T11:25:28.222872Z",
  "network": "instagram",
  "auth_method": "instagram_login",
  "error": null,
  "connectable_accounts": [
    {
      "pid": "17841400000000001",
      "name": "Postoria Demo",
      "username": "postoria.demo",
      "description": "Demo account",
      "url": "https://www.instagram.com/postoria.demo/",
      "logo_url": "https://example.com/profile.jpg",
      "account_category": "profile"
    }
  ],
  "reconnectable_accounts": [
    {
      "account_id": 123,
      "pid": "17841400000000002",
      "name": "Postoria",
      "username": "postoria.app",
      "description": "Postoria",
      "url": "https://www.instagram.com/postoria.app/",
      "logo_url": "https://example.com/profile-2.jpg",
      "account_category": "profile"
    }
  ]
}

Jika is_completed bernilai true dan error bukan null, otorisasi penyedia gagal atau ditolak. Jangan panggil endpoint penghubungan maupun penghubungan kembali akun; tampilkan kesalahannya atau mulai otorisasi baru.

Menghubungkan akun baru

Pilih satu atau beberapa PID persis seperti yang dikembalikan dalam connectable_accounts:

POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts

Contoh permintaan:

{
  "pids": [
    "17841400000000001"
  ]
}

Permintaan gagal dalam validasi jika PID tidak tersedia melalui otorisasi ini atau sudah terhubung di ruang kerja.

Menghubungkan kembali akun yang sudah ada

Pilih satu atau beberapa ID akun Postoria persis seperti yang dikembalikan dalam reconnectable_accounts:

POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect

Contoh permintaan:

{
  "account_ids": [123, 456]
}

Setiap akun yang diminta harus berada dalam ruang kerja dan jejaring yang ditentukan, dan izin OAuth yang telah selesai diberikan harus menyediakan akses ke akun tersebut. Jika salah satu akun yang diminta tidak tersedia, API mengembalikan 400 social_accounts_not_available sebelum menghubungkan kembali akun yang dipilih.

Akun yang sudah ada dapat dihubungkan kembali melalui metode autentikasi apa pun yang saat ini didukung untuk jejaringnya; metode tersebut tidak harus sama dengan yang digunakan saat koneksi awal. Selalu pilih account_id yang dikembalikan, jangan mencoba mencocokkan akun sendiri.

Respons tindakan akun

Endpoint penghubungan dan penghubungan kembali sama-sama mengembalikan akun Postoria yang terpengaruh:

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "accounts": [
    {
      "id": 123,
      "name": "Postoria",
      "custom_name": "Channel 113",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app/",
      "metadata": {
        "channel_number": "113"
      }
    }
  ]
}

Menampilkan daftar akun sosial

Gunakan endpoint ini untuk mendapatkan akun sosial yang terhubung dalam ruang kerja:

GET /v1/workspaces/{workspace_id}/social-accounts

Contoh respons:

{
  "data": [
    {
      "id": 123,
      "name": "Postoria",
      "custom_name": "Channel 113",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app",
      "metadata": {
        "channel_number": "113",
        "owner_account": "acme-media"
      }
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

name adalah nama akun yang diterima dari jejaring sosial. custom_name adalah nama opsional yang ditetapkan di Postoria. metadata adalah objek opsional berisi kunci string dan nilai string yang dikendalikan oleh integrasi Anda. Kunci metadata mempertahankan bentuk huruf besar/kecil aslinya.

Gunakan ID akun yang dikembalikan dalam social_account_ids saat membuat postingan. Anda juga dapat menggunakan metadata untuk mengaitkan setiap akun yang terhubung dengan pengenal tetap dalam sistem Anda sendiri.

Memperbarui akun sosial

Gunakan endpoint ini untuk menetapkan atau memperbarui nama khusus dan metadata akun sosial yang terhubung:

PATCH /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}

Contoh permintaan:

{
  "custom_name": "Channel 113",
  "metadata": {
    "channel_number": "113",
    "owner_account": "acme-media",
    "group": "north-america"
  }
}

Kedua kolom bersifat opsional, tetapi permintaan harus menyertakan setidaknya salah satunya. Kolom yang tidak disertakan tetap tidak berubah.

Perilaku penting:

• Spasi di awal dan akhir custom_name dipangkas sebelum disimpan, dan nilainya dapat berisi hingga 255 karakter.
• Tetapkan custom_name menjadi null atau string kosong untuk berhenti menggunakan nama khusus dalam antarmuka Postoria.
• metadata harus berupa objek JSON yang berisi kunci string dan nilai string.
• Metadata dapat berisi hingga 50 entri. Kunci dapat berisi hingga 64 karakter, dan nilai dapat berisi hingga 1.024 karakter.
• Mengirim metadata mengganti seluruh objek metadata; tindakan ini tidak menggabungkan kunci satu per satu.
• Tetapkan metadata menjadi null untuk menghapusnya, atau menjadi {} untuk mempertahankan objek metadata kosong.
• Nama khusus dan metadata tetap melekat pada akun sosial Postoria saat dihubungkan kembali atau diotorisasi ulang.

Respons berhasil:

{
  "id": 123,
  "name": "Postoria",
  "custom_name": "Channel 113",
  "description": "postoria.app",
  "network": "instagram",
  "url": "https://www.instagram.com/postoria.app",
  "metadata": {
    "channel_number": "113",
    "owner_account": "acme-media",
    "group": "north-america"
  }
}

Jika akun sosial tidak ada di ruang kerja yang ditentukan, API mengembalikan 404 social_account_not_found.

Menghapus akun sosial

Gunakan endpoint ini untuk menghapus akun sosial yang terhubung dari ruang kerja:

DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}

Parameter kueri force bersifat opsional dan secara bawaan bernilai false. Secara bawaan, akun tidak dapat dihapus selama dipilih untuk postingan berstatus scheduled atau queued. Draf postingan tidak menghalangi penghapusan.

Jika masih ada postingan terjadwal atau dalam antrean, API mengembalikan 409 social_account_has_scheduled_posts tanpa mengubah akun atau kaitannya dengan postingan:

{
  "error": {
    "code": "social_account_has_scheduled_posts",
    "message": "The social account cannot be deleted while scheduled or queued posts remain.",
    "param": null,
    "details": {
      "post_ids": [3001, 3002],
      "has_more": false
    },
    "request_id": "01JEXAMPLE"
  }
}

post_ids berisi hingga 10 ID postingan yang menghalangi penghapusan. Jika ada postingan penghalang lainnya, has_more bernilai true.

Untuk menghapus akun meskipun masih ada postingan terjadwal atau dalam antrean, tetapkan force=true:

DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}?force=true

Saat penghapusan dilanjutkan, Postoria menerapkan pembersihan yang sama seperti dasbor. Akun dihapus dari draf, postingan terjadwal, postingan dalam antrean, dan otomatisasi yang terhubung. Postingan yang tidak lagi memiliki akun sosial juga dapat dihapus.

Menghapus akun memutuskan koneksinya dari ruang kerja Postoria. Tindakan ini tidak mencabut otorisasi di jejaring sosial. Permintaan yang berhasil mengembalikan 204 No Content. Jika akun sosial tidak ada di ruang kerja yang ditentukan atau sudah dihapus, API mengembalikan 404 social_account_not_found.

Menampilkan daftar antrean

Gunakan endpoint ini untuk mendapatkan antrean dalam ruang kerja:

GET /v1/workspaces/{workspace_id}/queues

Contoh respons:

{
  "data": [
    {
      "id": 456,
      "name": "Morning posts",
      "is_paused": false
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Gunakan ID antrean yang dikembalikan saat membuat postingan dengan publish_mode ditetapkan menjadi queue.

Mengunggah media

Ada dua cara untuk menambahkan media melalui API:

1. Buat URL unggahan dan unggah file sendiri.
2. Impor media dari URL HTTPS publik.

Kedua metode membuat objek media. Gunakan endpoint pemeriksaan status media untuk memeriksa kapan media siap digunakan.

Item media harus memiliki status bernilai ready sebelum Anda dapat merujuknya saat membuat postingan.

Ada dua cara untuk menyediakan thumbnail video:

1. Gambar thumbnail khusus: unggah atau impor file gambar melalui endpoint media. Setelah item media gambar berstatus ready, kirim ID-nya sebagai thumbnail_media_id untuk video dalam POST /posts.
2. Thumbnail yang dibuat dari bingkai video: sertakan thumbnail_timestamp_ms saat membuat unggahan video atau impor URL. Nilainya diukur dalam milidetik. Postoria membuat item media gambar terpisah dan mengembalikan ID-nya sebagai thumbnail_media_id. Tunggu hingga video dan gambar yang dibuat sama-sama berstatus ready, lalu kirim ID tersebut dalam POST /posts.

Jenis unggahan yang didukung mencakup format gambar, video, dan dokumen umum seperti JPEG, PNG, WebP, GIF, MP4, MOV, dan PDF.

Mengunggah media dengan URL unggahan

Pertama, buat unggahan:

POST /v1/workspaces/{workspace_id}/media/uploads

Permintaan:

{
  "name": "image.jpg",
  "content_type": "image/jpeg"
}

Contoh respons:

{
  "id": 9001,
  "status": "waiting_for_upload",
  "upload": {
    "url": "https://temporary-upload-url.example"
  }
}

Untuk membuat thumbnail bagi unggahan video langsung, sertakan penanda waktu opsional saat membuat unggahan:

{
  "name": "video.mp4",
  "content_type": "video/mp4",
  "thumbnail_timestamp_ms": 5000
}

Sebelum satu pun dari kedua file selesai diproses, respons 201 Created sudah berisi ID media thumbnail yang dibuat:

{
  "id": 9002,
  "status": "waiting_for_upload",
  "thumbnail_media_id": 9003,
  "upload": {
    "url": "https://temporary-upload-url.example"
  }
}

Unggah byte file ke upload.url yang dikembalikan menggunakan permintaan HTTP PUT. Kirim byte mentah file sebagai isi permintaan dan gunakan nilai content_type yang sama seperti saat membuat unggahan.

Contoh:

curl -X PUT "https://temporary-upload-url.example" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@image.jpg"

URL unggahan bersifat sementara. Jika kedaluwarsa sebelum Anda mengunggah dan menyelesaikan item media, buat unggahan baru.

Setelah mengunggah file, selesaikan unggahan:

POST /v1/workspaces/{workspace_id}/media/{media_id}/complete

Contoh respons:

{
  "id": 9001,
  "status": "processing",
  "file_id": null,
  "error_code": null,
  "error_message": null
}

Postoria akan memproses media di latar belakang.

Mengimpor media dari URL

Gunakan endpoint ini jika file media sudah tersedia di URL HTTPS publik:

POST /v1/workspaces/{workspace_id}/media/imports

Permintaan:

{
  "url": "https://example.com/video.mp4",
  "thumbnail_timestamp_ms": 5000
}

Contoh respons:

{
  "id": 9002,
  "status": "processing",
  "file_id": null,
  "thumbnail_media_id": 9003,
  "error_code": null,
  "error_message": null
}

Hanya URL HTTPS publik yang didukung. URL privat, URL yang memerlukan autentikasi, file lokal, dan jalur relatif tidak didukung.

Dalam contoh ini, item media 9002 adalah video dan item media 9003 adalah thumbnail yang dibuat untuknya. Lakukan polling pada kedua item media hingga siap. Video sumber berisi thumbnail_media_id, sedangkan thumbnail yang dibuat berisi thumbnail_timestamp_ms yang diminta.

Kolom opsional yang sama dapat disertakan saat membuat unggahan video langsung. Kolom ini hanya berlaku untuk media video dan harus bernilai nol atau lebih besar.

Memeriksa status media

Gunakan endpoint ini untuk memeriksa apakah item media siap:

GET /v1/workspaces/{workspace_id}/media/{media_id}

Contoh respons media siap:

{
  "id": 9001,
  "status": "ready",
  "file_id": 701,
  "error_code": null,
  "error_message": null
}

Contoh respons thumbnail yang dibuat:

{
  "id": 9003,
  "status": "ready",
  "file_id": 702,
  "thumbnail_timestamp_ms": 5000,
  "error_code": null,
  "error_message": null
}

Contoh respons gagal:

{
  "id": 9001,
  "status": "failed",
  "file_id": null,
  "error_code": "media_processing_failed",
  "error_message": "The file format is not supported."
}

Status media:

• waiting_for_upload
• processing
• ready
• failed

Membuat postingan

Gunakan endpoint ini untuk membuat postingan:

POST /v1/workspaces/{workspace_id}/posts

API tidak membuat draf. Postingan dibuat untuk salah satu mode penerbitan berikut:

• publish_now
• schedule
• queue

scheduled_time hanya wajib untuk schedule. queue_id hanya wajib untuk queue. Kedua kolom tidak boleh dikirim untuk publish_now.

Semua akun sosial yang dipilih harus mendukung jenis konten yang dipilih; jika tidak, permintaan ditolak.

Contoh permintaan postingan terjadwal:

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Post caption",
  "first_comment": "More details in the first comment.",
  "comment_delay": 5,
  "is_ai_generated": true,
  "scheduled_time": "2026-06-01T10:00:00Z"
}

Contoh respons:

{
  "id": 3001,
  "status": "scheduled",
  "date": "2026-06-01T10:00:00Z",
  "queue_id": null,
  "is_ai_generated": true,
  "results": [
    {
      "account_id": 123,
      "link_to_post": null,
      "error": null
    }
  ],
  "instagram": {
    "content": "image",
    "caption": "Post caption",
    "files": [
      {
        "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
      }
    ],
    "comment": "More details in the first comment.",
    "comment_delay": 5
  }
}

Respons postingan menyertakan satu objek untuk setiap jejaring sosial yang diaktifkan dalam postingan, seperti facebook, instagram, linkedin, youtube, atau tiktok. Setiap objek jejaring berisi:

• content: jenis konten yang berlaku untuk jejaring tersebut.
• caption: teks keterangan untuk jejaring tersebut.
• files: file media untuk jejaring tersebut. URL file berupa URL bertanda tangan sementara yang dapat dibuka tanpa autentikasi selama sekitar satu jam. Video juga dapat menyertakan thumbnail_url jika thumbnail tersedia. thumbnail_timestamp_ms hanya disertakan jika thumbnail dibuat dari bingkai video.

Contoh file video dengan thumbnail yang dibuat:

{
  "url": "https://assets.postoria.io/w/1/video.mp4?st=temporary_signed_token",
  "thumbnail_url": "https://assets.postoria.io/w/1/thumbnail.png?st=temporary_signed_token",
  "thumbnail_timestamp_ms": 5000
}

Bergantung pada jejaring dan jenis konten, objek jejaring juga dapat menyertakan comment dan comment_delay, link, atau opsi penerbitan khusus jejaring. comment_delay diukur dalam menit. Postingan tautan dan komentar pertama hanya tersedia jika jejaring dan jenis konten yang dipilih mendukungnya. Stories tidak mendukung komentar pertama.

Hasil penerbitan dikembalikan per akun dalam results jika tersedia. Untuk postingan terjadwal dan dalam antrean, hasil mungkin belum tersedia sampai postingan diproses. Publikasi satu postingan dapat berhasil di beberapa akun dan gagal di akun lain.

Pengungkapan konten buatan AI

Tetapkan kolom is_ai_generated pada tingkat teratas menjadi true jika postingan perlu menyertakan pengungkapan konten buatan AI pada jejaring sosial yang mendukungnya.

{
  "is_ai_generated": true
}

Postoria mengirim pengungkapan yang sesuai jika tujuan dan jenis konten mendukungnya:

• Akun Instagram
• Postingan video TikTok
• Video YouTube
• Postingan X
• Pin Pinterest

Pengaturan ini tidak dikirim untuk postingan foto TikTok. Tujuan dan jenis konten yang tidak mendukungnya akan mengabaikannya.

Kolom tanggal dan waktu

Kolom tanggal/waktu menggunakan string ISO 8601 UTC.

Contoh:

"scheduled_time": "2026-06-01T10:00:00Z"

Gunakan UTC dan sertakan Z di akhir.

Jika Anda menjadwalkan berdasarkan waktu lokal, konversikan ke UTC sebelum mengirimkannya ke API.

Membuat postingan untuk diterbitkan sekarang

Tetapkan publish_mode menjadi publish_now.

{
  "publish_mode": "publish_now",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Publishing from Postoria Public API"
}

Menjadwalkan postingan

Tetapkan publish_mode menjadi schedule dan sertakan scheduled_time.

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Scheduled from Postoria Public API",
  "scheduled_time": "2026-06-01T10:00:00Z"
}

scheduled_time harus berupa waktu di masa mendatang.

Menambahkan postingan ke antrean

Tetapkan publish_mode menjadi queue dan sertakan queue_id.

{
  "publish_mode": "queue",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Queued from Postoria Public API",
  "queue_id": 456
}

Antrean harus berada dalam ruang kerja yang sama.

Jenis konten

Nilai content_type yang didukung:

• text
• image
• video
• document
• carousel
• link
• story
• reel

Jika content_type tidak disertakan, Postoria mencoba menentukannya dari data permintaan:

• Beberapa item media → carousel
• Satu item media → jenis media yang sesuai, seperti image, video, atau document
• URL tautan tanpa media → link
• Hanya keterangan → text

Validasi khusus setiap jejaring sosial tetap berlaku. Semua akun sosial yang dipilih harus mendukung jenis konten yang diminta; jika tidak, API mengembalikan kesalahan validasi dan tidak membuat postingan.

Menambahkan media ke postingan

Gunakan array media untuk merujuk item media yang dibuat melalui endpoint unggah atau impor. Setiap item harus memiliki status bernilai ready.

{
  "media": [
    {
      "media_id": 9001
    }
  ]
}

Untuk video, Anda dapat menyediakan thumbnail secara opsional. thumbnail_media_id menentukan thumbnail untuk video dengan media_id yang sesuai dan harus merujuk ke item media gambar yang siap digunakan.

• Untuk gambar thumbnail khusus, unggah atau impor file gambar melalui endpoint media dan gunakan ID medianya.
• Untuk thumbnail yang dibuat dari bingkai video, kirim thumbnail_timestamp_ms saat membuat unggahan atau impor video, lalu gunakan thumbnail_media_id yang dikembalikan setelah berstatus ready.

Dalam kedua kasus, POST /posts menerima thumbnail_media_id. Penanda waktu hanya disertakan saat membuat item media video, bukan saat membuat postingan.

{
  "media": [
    {
      "media_id": 9002,
      "thumbnail_media_id": 9003
    }
  ]
}

Postingan tautan

Untuk postingan tautan, sertakan link_url:

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "link",
  "caption": "Useful link",
  "link_url": "https://example.com/article",
  "scheduled_time": "2026-06-01T10:00:00Z"
}

Postoria akan mengimpor informasi tautan saat membuat postingan.

Komentar pertama

Gunakan first_comment untuk menambahkan komentar pertama jika jejaring yang dipilih mendukungnya. Gunakan comment_delay untuk menunda komentar pertama; nilainya diukur dalam menit.

{
  "first_comment": "More details in the first comment."
}

Aturan khusus setiap jejaring tetap berlaku. Kolom respons komentar pertama hanya dikembalikan untuk jejaring yang mendukung komentar pertama.

Opsi Facebook

Gunakan objek facebook untuk opsi khusus Facebook:

{
  "facebook": {
    "location_id": "12345678901234567890",
    "also_publish_media_to_stories": true
  }
}

location_id bersifat opsional dan harus berupa string numerik positif yang berisi tidak lebih dari 64 digit. Nilai ini mengidentifikasi Halaman Facebook untuk lokasi fisik yang harus dikaitkan Meta dengan postingan. Kirim ID sebagai string JSON, bukan angka, agar ID besar tetap dipertahankan secara tepat.

Jika also_publish_media_to_stories bernilai true, Postoria membuat publikasi Facebook biasa terlebih dahulu, lalu menerbitkan setiap file media terlampir sebagai Facebook Story terpisah. Opsi ini tidak berpengaruh jika content_type bernilai story atau link.

Opsi Instagram

Gunakan objek instagram untuk opsi khusus Instagram:

{
  "instagram": {
    "location_id": "12345678901234567890",
    "also_publish_media_to_stories": true,
    "collaborators": ["creator_one"],
    "publish_as_trial_reel": false,
    "auto_share_if_performs_well": false,
    "user_tags": [
      {
        "media_id": 9001,
        "username": "creator_one",
        "x": 0.5,
        "y": 0.5
      }
    ]
  }
}

location_id bersifat opsional dan mengikuti format yang sama dengan opsi Facebook: string numerik positif yang berisi tidak lebih dari 64 digit. Nilai ini harus mengidentifikasi Halaman Facebook yang terkait dengan lokasi fisik.

Jika also_publish_media_to_stories bernilai true, Postoria membuat publikasi Instagram biasa terlebih dahulu, lalu menerbitkan setiap file media terlampir sebagai Instagram Story terpisah. Opsi ini tidak berpengaruh jika content_type bernilai story.

user_tags.media_id harus merujuk media yang dilampirkan pada postingan yang sama. Dalam respons postingan, tag pengguna menggunakan file_id sebagai pengganti media_id.

Opsi Pinterest

Gunakan objek pinterest untuk opsi khusus Pinterest:

{
  "pinterest": {
    "title": "Pin title",
    "website": "https://example.com/article",
    "alt_text": "A description of the image"
  }
}

website adalah URL tujuan untuk Pin.

Opsi Google Business Profile

Gunakan objek google_business_profile untuk menambahkan tombol tindakan:

{
  "google_business_profile": {
    "button_type": "LEARN_MORE",
    "button_url": "https://example.com"
  }
}

Jenis tombol yang didukung adalah BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, dan CALL. URL tombol wajib untuk semua jenis tombol kecuali CALL.

Pengaturan posting ulang

Gunakan repost untuk mengonfigurasi posting ulang.

Contoh:

{
  "repost": {
    "frequency": "do_not_repeat",
    "until": null
  }
}

Jika Anda menetapkan frekuensi posting ulang, until harus berupa tanggal/waktu UTC di masa mendatang jika diwajibkan oleh pengaturan posting ulang yang dipilih.

Opsi YouTube

Gunakan objek youtube saat membuat postingan untuk akun YouTube.

Contoh:

{
  "youtube": {
    "title": "Video title",
    "visibility": "public",
    "category": "People & Blogs",
    "made_for_kids": false,
    "video_language": "en",
    "recording_date": "2026-06-01T00:00:00Z",
    "tags": ["tag1", "tag2"]
  }
}

Gunakan kolom YouTube hanya jika setidaknya satu akun sosial yang dipilih adalah akun YouTube.

Untuk nilai YouTube yang didukung, lihat dokumentasi Unggahan massal: Cara mengunggah postingan secara massal dengan file CSV di Postoria.

Opsi TikTok

Gunakan objek tiktok saat membuat postingan untuk akun TikTok.

Contoh:

{
  "tiktok": {
    "who_can_watch": "public",
    "allow_comments": true,
    "allow_duet": false,
    "allow_stitch": false,
    "disclose_post_content": false,
    "your_brand": false,
    "branded_content": false,
    "photo_title": "Photo title",
    "auto_add_music": false
  }
}

Kolom TikTok yang didukung:

• who_can_watch: public, followers, friends, atau private
• allow_comments: true atau false
• allow_duet: true atau false
• allow_stitch: true atau false
• disclose_post_content: true atau false
• your_brand: true atau false
• branded_content: true atau false
• photo_title: teks biasa hingga 90 karakter
• auto_add_music: true atau false

Gunakan kolom TikTok hanya jika setidaknya satu akun sosial yang dipilih adalah akun TikTok.

Opsi Tumblr

Gunakan objek tumblr untuk menambahkan tag bawaan Tumblr secara terpisah dari keterangan postingan:

{
  "caption": "Explore our latest indie game",
  "tumblr": {
    "tags": ["gaming", "indiegame", "steam", "hades2"]
  }
}

Postoria menerima hingga 30 tag Tumblr. Spasi di awal dan akhir dipangkas, # di awal dihapus, nilai kosong diabaikan, dan tag duplikat dihapus tanpa membedakan huruf besar/kecil. Setiap item array tidak boleh berisi koma atau tanda kutip ganda. Gunakan opsi Tumblr hanya jika setidaknya satu akun sosial yang dipilih adalah akun Tumblr.

Menampilkan daftar postingan

Gunakan endpoint ini untuk menampilkan daftar postingan dalam ruang kerja:

GET /v1/workspaces/{workspace_id}/posts

Parameter kueri opsional:

• account_ids: ID akun sosial. Ulangi parameter atau gunakan nilai yang dipisahkan koma.
• queue_id: ID antrean.
• status: salah satu dari draft, scheduled, in_progress, posted, atau queued.
• networks: satu atau beberapa nilai jejaring seperti instagram, facebook, linkedin, youtube, atau tiktok.
• date_from: tanggal/waktu terjadwal pada atau setelah nilai UTC ini.
• date_to: tanggal/waktu terjadwal sebelum nilai UTC ini.
• limit: jumlah postingan yang dikembalikan. Nilai bawaan adalah 25; maksimum 100.
• cursor: kursor paginasi yang dikembalikan dari halaman sebelumnya.

account_ids dan queue_id harus berada dalam ruang kerja yang ditentukan.

Contoh permintaan:

curl "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25" \
  -H "Authorization: Bearer pst_live_your_api_key"

Contoh respons:

{
  "data": [
    {
      "id": 3001,
      "status": "scheduled",
      "date": "2026-06-01T10:00:00Z",
      "queue_id": null,
      "is_ai_generated": true,
      "results": [
        {
          "account_id": 123,
          "link_to_post": null,
          "error": null
        }
      ],
      "instagram": {
        "caption": "Scheduled post caption",
        "files": [
          {
            "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
          }
        ]
      }
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0",
    "next": "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0"
  }
}

Untuk meminta halaman berikutnya, panggil next secara langsung atau kirim kembali next_cursor sebagai cursor:

GET /v1/workspaces/{workspace_id}/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0

Memeriksa status postingan

Gunakan endpoint ini untuk memeriksa status postingan:

GET /v1/workspaces/{workspace_id}/posts/{post_id}

date adalah waktu penerbitan yang dijadwalkan. Nilainya dapat berupa null untuk postingan dalam antrean dan postingan yang langsung diterbitkan.

Contoh respons:

{
  "id": 3001,
  "status": "posted",
  "date": "2026-06-01T10:00:00Z",
  "queue_id": null,
  "is_ai_generated": true,
  "results": [
    {
      "account_id": 123,
      "link_to_post": "https://www.instagram.com/p/example",
      "error": null
    }
  ],
  "instagram": {
    "caption": "Published post caption",
    "files": [
      {
        "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
      }
    ]
  }
}

Status postingan:

• draft
• scheduled
• in_progress
• posted
• queued

Arti item hasil:

• link_to_post ditetapkan ketika postingan berhasil diterbitkan dan tautan publik tersedia.
• error ditetapkan ketika penerbitan gagal untuk akun tersebut.
• Baik link_to_post maupun error dapat bernilai null sebelum postingan diterbitkan.

Menghapus postingan

Gunakan endpoint ini untuk menghapus postingan:

DELETE /v1/workspaces/{workspace_id}/posts/{post_id}

Respons berhasil:

204 No Content

Postingan harus berada dalam ruang kerja yang ditentukan.

Menghapus postingan menghilangkannya dari Postoria. Tindakan ini tidak menghapus postingan yang sudah diterbitkan ke jejaring sosial. Jika penerbitan sudah dimulai, menghapus postingan Postoria tidak menghentikan penerbitan tersebut. Hasil akun dihapus bersama postingan dan tidak dapat diambil lagi setelahnya.

Mendapatkan analitik untuk postingan tertentu

Gunakan endpoint ini untuk mengambil analitik terbaru yang tersedia bagi satu hingga 100 ID postingan Postoria:

GET /v1/workspaces/{workspace_id}/analytics/posts?post_ids=3001&post_ids=3002

Ulangi post_ids untuk setiap postingan. ID harus berupa bilangan bulat positif. ID duplikat diterima dan diperlakukan sebagai satu ID.

Setiap postingan yang diminta harus berada dalam ruang kerja tersebut. Jika salah satu postingan tidak ada atau berada di ruang kerja lain, seluruh permintaan gagal dengan 404 post_not_found; respons tidak menunjukkan ID mana yang gagal.

Respons berisi satu baris untuk setiap publikasi akun sosial yang dipilih dan terkait dengan postingan yang diminta. Metrik disajikan sebagai pasangan nama/nilai karena ketersediaannya berbeda menurut jejaring dan dapat berubah seiring waktu:

{
  "data": [
    {
      "post_id": 3001,
      "social_account_id": 123,
      "network": "tiktok",
      "content_type": "video",
      "published_at": "2026-08-01T10:00:00Z",
      "analytics_refreshed_at": "2026-08-25T12:34:56Z",
      "metrics": [
        { "name": "views", "value": 1250 },
        { "name": "likes", "value": 84 }
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Metrik yang tidak tersedia tidak disertakan. Nilai nol yang diketahui dikembalikan sebagai nol. analytics_refreshed_at adalah waktu ISO 8601 UTC ketika Postoria terakhir berhasil memperbarui analitik publikasi dari jejaring sosial. Jika publikasi ada tetapi analitik belum tersedia, analytics_refreshed_at bernilai null dan metrics berupa array kosong.

Nilai jejaring dalam analitik menggunakan pengenal kanonis seperti linkedin, youtube, tiktok, dan google_business_profile.

Metrik YouTube menggunakan nama dengan awalan youtube_ tersendiri. Contohnya mencakup youtube_views, youtube_engaged_views, youtube_likes, youtube_dislikes, youtube_estimated_minutes_watched, youtube_average_view_duration, dan youtube_subscribers_gained. Endpoint analitik postingan dapat mengembalikan metrik yang dapat dijumlahkan maupun rata-rata atau rasio yang tidak dapat dijumlahkan.

Mendapatkan ringkasan gabungan performa postingan

Gunakan endpoint ini untuk menggabungkan metrik terbaru yang tersedia bagi postingan yang diterbitkan selama interval UTC:

GET /v1/workspaces/{workspace_id}/analytics/post-performance/summary?published_from=2026-08-01T00:00:00Z&published_to=2026-09-01T00:00:00Z&granularity=day&group_by=network

Parameter kueri wajib:

• published_from: penanda waktu ISO 8601 UTC inklusif menggunakan Z atau +00:00.
• published_to: penanda waktu ISO 8601 UTC eksklusif menggunakan Z atau +00:00.

Interval harus lebih besar dari nol dan tidak boleh melebihi 366 hari.

Parameter kueri opsional:

• granularity: hour, day, month, atau year. Jangan sertakan untuk mengembalikan hasil tanpa kelompok waktu penerbitan.
• group_by: network, content_type, atau social_account. Jangan sertakan untuk mengembalikan hasil tanpa dimensi pengelompokan tambahan.

granularity dan group_by bersifat independen. Misalnya, Anda dapat mengelompokkan menurut jejaring tanpa kelompok waktu, menggunakan kelompok harian tanpa pengelompokan dimensi, menggabungkan keduanya, atau menghilangkan keduanya untuk mendapatkan satu baris total.

Jika granularity disertakan, kelompok waktu menggunakan zona waktu ruang kerja. Respons menyertakan zona waktu IANA tersebut dan published_period untuk setiap baris. start dan end pada periode adalah titik waktu UTC, end bersifat eksklusif, dan key adalah label kelompok waktu lokal ruang kerja yang sesuai.

{
  "data": [
    {
      "published_period": {
        "start": "2026-08-01T04:00:00Z",
        "end": "2026-08-02T04:00:00Z",
        "key": "2026-08-01"
      },
      "network": "linkedin",
      "post_count": 3,
      "metrics": [
        { "name": "views", "value": 4200 },
        { "name": "comments", "value": 17 }
      ]
    }
  ],
  "timezone": "America/New_York"
}

Jika granularity tidak disertakan, published_period dan kolom timezone pada tingkat teratas juga tidak disertakan. Jika group_by tidak disertakan, kolom pengelompokan tidak dikembalikan. Jika disertakan, setiap baris berisi tepat satu kolom yang sesuai: network, content_type, atau social_account_id.

Ringkasan mengelompokkan postingan berdasarkan waktu penerbitannya. Ringkasan menjumlahkan metrik terbaru yang tersedia; ringkasan tidak menunjukkan kapan penayangan, reaksi, atau interaksi lainnya terjadi. Total metrik yang bernilai nol atau tidak tersedia tidak disertakan dalam baris ringkasan. Metrik yang tidak dapat dijumlahkan seperti video_skip_rate, video_average_watch_time_milliseconds, rata-rata YouTube, dan rasio YouTube tidak disertakan karena tidak dapat dijumlahkan dengan benar.

Kesalahan umum

Kunci API tidak valid

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Paket diperlukan

{
  "error": {
    "code": "public_api_plan_required",
    "message": "Public API access is available on Pro and Agency plans.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Validasi gagal

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": "content_type",
    "details": {
      "reason": "The selected social account does not support this content type."
    },
    "request_id": "req_abc123"
  }
}

Ruang kerja tidak ditemukan

{
  "error": {
    "code": "workspace_not_found",
    "message": "The requested workspace was not found.",
    "param": "workspace_id",
    "details": null,
    "request_id": "req_abc123"
  }
}

Praktik terbaik

• Simpan kunci API Anda dengan aman.
• Jangan tampilkan kunci API dalam kode frontend.
• Unggah atau impor media terlebih dahulu, lalu tunggu hingga status media menjadi ready.
• Gunakan GET /posts/{post_id} untuk memeriksa status setelah membuat postingan.
• Perlakukan nama metrik analitik sebagai daftar yang dapat berkembang, jangan menanamkan daftar tetap dalam kode.
• Gunakan UTC untuk filter ringkasan; saat menggunakan granularity, tafsirkan kunci kelompok waktu dalam zona waktu ruang kerja yang dikembalikan.
• Tangani kesalahan validasi dan tampilkan pesan yang dikembalikan kepada pengguna Anda.
• Lakukan percobaan ulang hanya setelah mematuhi header batas permintaan.
• Segera cabut kunci jika Anda menduga kunci telah terekspos.