Referensi API publik

Ikhtisar

API publik bersifat hanya-baca kecuali tiga endpoint tulis kecil (formulir lead, pencatatan 404, dan analitik). Setiap path di bawah ini relatif terhadap https://api.atlascms.id.

curl -s "https://api.atlascms.id/v1/public/settings" \
  -H "Authorization: Bearer $ATLAS_TOKEN" | jq '.data.brand.slug'

Error

Setiap respons membawa header X-Request-Id (req_ dan sepuluh karakter heksadesimal). Sebutkan saat Anda menulis ke dukungan.

Cache dan ETag

Setiap respons membawa header ETag dan Cache-Control, dan If-None-Match yang cocok dijawab 304 tanpa body. Untuk page, route, entries, dan sitemap-urls, ETag diturunkan dari versi konten brand, sehingga 304 dijawab sebelum rendering apa pun. Penerbitan, atau perubahan apa pun yang mengubah output yang tayang, menaikkan versi konten dan dengan begitu membatalkan semua ETag lama sekaligus.

URL="https://api.atlascms.id/v1/public/page?path=/&locale=en"
ETAG=$(curl -s -D - -o /dev/null "$URL" -H "Authorization: Bearer $ATLAS_TOKEN" \
  | grep -i '^etag:' | cut -d' ' -f2- | tr -d '\r')

curl -s -o /dev/null -w '%{http_code}\n' "$URL" \
  -H "Authorization: Bearer $ATLAS_TOKEN" -H "If-None-Match: $ETAG"
# 304

Cache body singkat di sisi server (120 detik secara default) berada di balik ETag; kenaikan versi konten membuat semua body lama tidak terjangkau. SDK dan layer Nuxt melakukan revalidasi dengan ETag untuk Anda.

Batas laju

Situs yang memanggil API dari servernya sebaiknya mengirim alamat pengunjung di X-Atlas-Client-Ip dan X-Atlas-Client-User-Agent, agar pengunjung yang dinilai, bukan server. API hanya mempercayai header ini pada panggilan yang membawa token baca.

Halaman

Halaman yang terbit pada sebuah path: block, SEO, tautan terjemahan, route yang cocok, dan tema yang merendernya.

Field respons: id, type, locale, path, is_front_page, template, title, seo, fields (field bertipe dari tipe kustom), terms, published_at, modified_at, blocks, translations ([{ locale, path }]), fragments, route, theme, dan fallback. 404 berarti tidak ada halaman yang terbit. Ketika brand menampilkan artikel terbaru di depan, path=/ adalah 404 dan endpoint route yang menjawab.

curl -s "https://api.atlascms.id/v1/public/page?path=/pricing&locale=en" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Route

Hanya block route dan theme, untuk path yang dijawab 404 oleh endpoint halaman: arsip, halaman artikel, pencarian, halaman tidak ditemukan, atau root locale ketika menampilkan artikel terbaru. Locale yang tidak dikenal adalah 404.

{
  "data": {
    "path": "/search",
    "locale": "en",
    "route": { "kind": "search", "template": "index", "candidates": ["search", "index"] },
    "theme": {
      "slug": "atlascms",
      "version": "0.1.0",
      "template": { "slug": "index", "source": "package", "blocks": null },
      "parts": { "header": { "slug": "header", "area": "header", "source": "package", "blocks": null } }
    }
  }
}

Entri

Daftar entri yang terbit dengan halaman cursor untuk satu tipe: artikel, halaman, atau tipe kustom.

curl -s "https://api.atlascms.id/v1/public/entries?type=post&limit=10&count=1&fields=light" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

{
  "data": [
    { "id": "01m5ffh6...", "type": "post", "locale": "en", "path": "/blog/hello", "title": "Hello", "seo": { "og_image": null }, "author_name": "Sari", "fields": {}, "terms": [], "published_at": "2026-10-21T14:58:33.000000Z" }
  ],
  "links": { "first": null, "last": null, "prev": null, "next": "https://.../v1/public/entries?type=post&cursor=eyJ..." },
  "meta": { "per_page": 10, "next_cursor": "eyJ...", "prev_cursor": null, "total": 6 }
}

Telusuri daftar dengan mengirim meta.next_cursor sebagai cursor sampai nilainya null.

Menu

Menu navigasi seperti header atau footer. Item membentuk pohon. Setiap item punya label dan boleh punya url, key, eyebrow, description, attributes, dan image ({ url, alt, width, height }). locale memilih bahasa; key yang tidak dikenal adalah 404.

{
  "data": {
    "id": "01m518vv88kdjb68enh6w74ded",
    "key": "header",
    "locale": "en",
    "items": [
      { "key": "features", "label": "Features", "url": "/features" },
      { "key": "pricing", "label": "Pricing", "url": "/pricing" }
    ]
  }
}

Pengaturan

Brand dan pengaturan yang ditandai publik oleh registry. Jawabannya membawa brand (name, slug, default_locale, locales), settings, branding (logo, favicon, gambar bagikan), serta objek reading dan permalinks yang sudah diselesaikan. Key privat tidak pernah muncul. Token pratinjau juga mendapat brand.slug, yang dibandingkan layer Nuxt sebelum menghormati cookie pratinjau.

Tema

Set token brand dan opsi tema yang sudah diselesaikan untuk satu locale. tokens berisi warna beserta skalanya, font, dan radius, dan options berisi apa yang diekspos tema untuk diedit. Token pratinjau menerima opsi draf.

String

Teks antarmuka yang dikelola brand, dikelompokkan menurut namespace.

{ "data": { "locale": "en", "strings": { "site": { "copyright": "AtlasCMS.", "language": "English" } } } }

Ketentuan

Kategori dan tag, masing-masing sebagai { taxonomy, slug, name, path } dengan path adalah path arsip dari base permalink brand.

Tipe konten

Tipe konten kustom yang dilayani brand, masing-masing dengan daftar field-nya agar situs tidak perlu mengurai skema. Kirim locale untuk mendapat label dalam satu bahasa.

URL sitemap

Setiap path publik beserta bahasanya, perubahan terakhir, dan alternatif untuk hreflang: [{ path, locale, type, lastmod, alternates: [{ locale, path }] }].

Redirect

Peta redirect sebagai [{ from, to, code }]. Memindahkan entri yang terbit menambahkan 301 di sini untuk Anda.

File yang dapat dibaca mesin

Data untuk llms.txt, sebagai JSON, atau sebagai teks dengan format=text. Menerima locale.

File key IndexNow. 404 bila IndexNow tidak diaktifkan untuk brand.

Web app manifest brand: nama, ikon (192, 512, dan maskable), warna tema, display: standalone, dan start_url.

Kirim formulir

Mengirim lead dari formulir yang didefinisikan brand. Hanya field yang dideklarasikan formulir yang diterima dan disimpan. Formulir harus aktif, dan modul Formulir harus menyala.

curl -s -X POST "https://api.atlascms.id/v1/public/forms/contact" \
  -H "Authorization: Bearer $ATLAS_TOKEN" -H "Content-Type: application/json" \
  -d '{"fields":{"name":"Sari","email":"[email protected]"},"consent":true,"source_page":"/contact"}'

Berhasil adalah 201 dengan { "data": { "id", "message" } }. Formulir yang tidak dikenal atau tidak aktif adalah 404, dan field yang tidak valid adalah 422.

Catat halaman tidak ditemukan

Memungkinkan situs mencatat 404 agar editor melihat apa yang terlewat pengunjung di dashboard dan bisa menambahkan redirect.

Beacon analitik

Menghitung tampilan halaman. Kirim path (diawali /, hingga 512 karakter), dan opsional referrer serta id visitor sepanjang 8 sampai 64 karakter. Jawabannya 204 tanpa body.

Event pelacakan

Mengirim event pelacakan ke platform iklan yang dihubungkan brand. Memerlukan token baca. Event browser hanya boleh PageView, ViewContent, atau Lead, dan custom_data.value serta custom_data.currency dibuang. Event bergaya pembelian dan uang memerlukan source: "server", yang hanya bisa dikirim panggilan dengan token baca.

Status

Kesehatan publik platform, tanpa token: status (operational, degraded, outage, atau unknown), generated_at, versi API, dan daftar services (database, redis, queue, scheduler) dengan riwayat 90 hari. Di-cache selama 10 detik. Data yang sama mengisi status.atlascms.id.

Referensi lengkap

API menyajikan referensi yang dihasilkan otomatis untuk setiap endpoint, termasuk API dashboard, di /docs/api pada alamatnya sendiri. Gunakan halaman ini sebagai panduan dan halaman itu sebagai daftar lengkap.