REST API Aturan.org

API Aturan.org menyediakan pencarian semantik untuk regulasi Indonesia. API ini dapat digunakan oleh aplikasi, LegalTech, Retrieval-Augmented Generation (RAG), agent, dan sistem AI yang membutuhkan pencarian berdasarkan makna, bukan hanya kata kunci.

Base URL:

https://aturan.org/api/v1

1. Autentikasi

Semua endpoint memerlukan API Key.

API Key dapat dibuat dan dikelola langsung melalui Dashboard Aturan.org. Key baru memakai format atorg_key_...; key lama ao_mcp_... tetap didukung. Buat key terpisah untuk aplikasi, server, environment, atau integrasi yang berbeda agar akses dapat dikelola dan dicabut secara independen. API key yang sama dapat digunakan untuk REST API maupun MCP.

Kirim API Key menggunakan HTTP Authorization header dengan skema Bearer:

Authorization: Bearer YOUR_API_KEY

Disarankan menyimpan API Key sebagai environment variable:

export ATURANORG_API_KEY='YOUR_API_KEY'

Kemudian gunakan pada request:

curl --silent --show-error \
  'https://aturan.org/api/v1/...' \
  --header "Authorization: Bearer ${ATURANORG_API_KEY}"

Praktik keamanan

Jangan:

• menyimpan API Key langsung di source code;
• melakukan commit API Key ke repository;
• menampilkan API Key pada log;
• menaruh API Key pada frontend atau aplikasi browser publik;
• membagikan satu key untuk seluruh environment apabila dapat menggunakan key terpisah.

Gunakan environment variable, secret manager, atau mekanisme penyimpanan credential yang sesuai dengan lingkungan aplikasi Anda.

Jika sebuah key tidak lagi diperlukan atau diduga terekspos, cabut key tersebut melalui Dashboard dan buat key baru.

Request tanpa API Key atau menggunakan key yang tidak valid menerima respons:

401 Unauthorized

2. Quick Start

API Aturan.org menggunakan pola:

DISCOVER → RESOLVE → READ

Aplikasi terlebih dahulu melakukan pencarian melalui salah satu dari tiga endpoint discovery:

POST /query/judul-peraturan
POST /query/peraturan-terkait
POST /query/pasal-terkait

Hasil pencarian memberikan regulation_id untuk regulasi yang ditemukan.

Setelah memastikan regulasi yang dimaksud benar, gunakan regulation_id tersebut untuk membaca isi Pasal:

GET /query/isi-pasal

isi-pasal adalah endpoint pembacaan, bukan endpoint pencarian.

Jangan menebak, membentuk, melakukan increment/decrement, atau mengandalkan regulation_id yang tidak diperoleh dari endpoint discovery.

Hasil discovery juga dapat menyediakan pdf_download_link untuk mengakses dokumen PDF regulasi apabila tersedia. Gunakan link yang diberikan oleh hasil API; aplikasi tidak perlu membentuk sendiri URL PDF berdasarkan regulation_id.

3. Memilih endpoint

Gunakan judul-peraturan untuk pencarian literal/as-is.

Gunakan peraturan-terkait atau pasal-terkait untuk semantic retrieval.

Gunakan isi-pasal hanya setelah regulasi ditemukan dan dipastikan sesuai melalui endpoint discovery.

4. Panduan semantic retrieval

4.1. Semantic retrieval berbeda dari keyword search

peraturan-terkait dan pasal-terkait menggunakan semantic retrieval. Query dipahami berdasarkan kedekatan makna, bukan hanya kecocokan kata secara literal.

Karena itu, berikan konteks yang cukup mengenai konsep, tindakan, kewajiban, larangan, hak, peristiwa, atau isu hukum yang ingin ditemukan.

Contoh query yang baik:

kewajiban pelaku usaha melindungi data pribadi konsumen

sanksi administratif kegiatan pertambangan tanpa memenuhi kewajiban

persyaratan pembangunan pembangkit listrik tenaga surya atap

Hindari query semantik yang terlalu pendek atau hanya terdiri dari satu-dua kata seperti:

data pribadi

pertambangan

PLTS

Untuk peraturan-terkait dan pasal-terkait, gunakan setidaknya 3 kata agar query menyediakan konteks semantik yang memadai.

Ketentuan minimum tersebut tidak berlaku untuk judul-peraturan, karena endpoint tersebut menggunakan pencarian literal/as-is.

4.2. Query dapat menggunakan bahasa lain

Semantic retrieval Aturan.org menggunakan model embedding multilingual. Query tidak harus menggunakan Bahasa Indonesia.

Sebagai contoh, query:

administrative sanctions for mining companies

dapat digunakan untuk menemukan regulasi atau Pasal Indonesia yang memiliki makna terkait, meskipun teks regulasinya menggunakan Bahasa Indonesia.

Contoh lain:

foreign investor land ownership restrictions

Kemampuan ini berguna untuk aplikasi multilingual, sistem AI, penelitian lintas bahasa, pengguna internasional, dan pengguna yang tidak mengetahui terminologi hukum Indonesia secara persis.

Semantic retrieval tetap menghasilkan kandidat berdasarkan kedekatan makna. Bahasa query tidak mengubah kebutuhan untuk mengevaluasi hasil dalam konteks hukum yang sebenarnya.

4.3. Gunakan Top-K yang cukup

Ragam bahasa hukum seringkali memiliki terminologi khusus yang bersifat unik dan memiliki makna tertentu. Norma atau ketentuan yang dicari tidak selalu berada pada urutan pertama hasil semantic retrieval, mengingat perbedaan pemaknaan input dengan pemaknaan kalimat pasal.

Dengan memahami bahwa similarity ≠ relevance, maka perlu dihindari penggunaan top_k yang terlalu sedikit karena kita akan melakukan perhitungan cosine similarity secara brute-force terhadap 5,6 juta pasal satuan.

Untuk menilai relevansi, diperlukan penalaran lanjutan oleh LLM. Kami mendesain retrieval untuk dapat dicerna model kecil di level 4B-9B sehingga dapat diterapkan secara on-premise dengan hardware terbatas, namun demikian untuk penalaran kompleks yang melibatkan banyak top_k dari berbagi peraturan sebaiknya menggunakan model yang lebih besar.

Untuk menerjemahkan bahasa awam menjadi bahasa hukum, dapat dilakukan reformulasi query oleh LLM agar didapatkan kedekatan semantik yang lebih presisi. Untuk hasil optimal agar menggunakan model berkemampuan agentic, sehingga mampu melakukan iterasi reformulasi query dan mampu menelusuri pasal/peraturan lanjutan.

Untuk peraturan-terkait:

• gunakan top_k yang lebih besar untuk memperoleh cakupan regulasi yang luas;
• untuk regulatory landscape atau penelitian yang membutuhkan recall tinggi, gunakan 100–200 kandidat;
• nilai yang lebih kecil dapat digunakan bila aplikasi hanya membutuhkan pencarian yang lebih terbatas.

Untuk pasal-terkait:

• gunakan top_k di rentang 10-20 untuk menjaring pasal-pasal terdekat dengan frasa input;
• hindari pencarian dengan top_k terlalu sedikit seperti 1–5.

Aplikasi atau agent sebaiknya memperlakukan hasil semantic retrieval sebagai candidate evidence untuk kemudian dilakukan analisis relevansi isi pasal terhadap informasi judul peraturan, bab, bagian, paragraf dari pasal dimaksud.

5. Query Judul Peraturan

POST /api/v1/query/judul-peraturan

Mencari judul regulasi secara literal/as-is menggunakan indeks pencarian judul.

Gunakan endpoint ini ketika nomor, tahun, jenis, atau nama dokumen sudah diketahui, misalnya:

UU 30 Tahun 2009

PP 45 Tahun 2005

Peraturan Menteri ESDM tentang PLTS Atap

Endpoint ini bukan pencarian semantik dan tidak menyimpulkan isi norma.

query dapat berisi satu kata, singkatan, nomor, tahun, atau frasa judul dengan panjang 1–2.000 karakter. Endpoint ini tidak menerapkan minimum 3 kata.

Contoh request

curl --silent --show-error --request POST \
  'https://aturan.org/api/v1/query/judul-peraturan' \
  --header "Authorization: Bearer ${ATURANORG_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "PP 45 Tahun 2005",
    "top_k": 10,
    "sort": "relevance"
  }'

Setiap item hasil dapat mengembalikan regulation_id dan pdf_download_link.

Gunakan regulation_id dari hasil yang sudah dipastikan sesuai dengan regulasi yang dicari untuk membaca Pasal.

Gunakan pdf_download_link yang dikembalikan oleh API apabila aplikasi perlu mengakses dokumen PDF regulasi.

Detail internal seperti path penyimpanan dokumen tidak diekspos melalui public API.

6. Query Peraturan Terkait

POST /api/v1/query/peraturan-terkait

Mencari regulasi berdasarkan makna query, kemudian mengelompokkan Pasal kandidat pada masing-masing regulasi.

Endpoint ini cocok untuk:

• regulatory landscape;
• identifikasi regulasi yang mungkin terkait dengan suatu persoalan;
• discovery sebelum melakukan analisis hukum;
• menemukan regulasi ketika pengguna belum mengetahui nomor atau judul peraturannya.

Contoh request

curl --silent --show-error --request POST \
  'https://aturan.org/api/v1/query/peraturan-terkait' \
  --header "Authorization: Bearer ${ATURANORG_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "sanksi administratif kegiatan pertambangan mineral dan batubara",
    "top_k": 100
  }'

Contoh bagian respons

{
  "query": "sanksi administratif kegiatan pertambangan mineral dan batubara",
  "groups": {
    "peraturan_tingkat_pusat": {
      "PERMEN": [
        {
          "regulation_name": "Peraturan Menteri Energi dan Sumber Daya Mineral Nomor 25 Tahun 2018 tentang Pengusahaan Pertambangan Mineral Dan Batubara",
          "regulation_id": 990100,
          "regulation_hierarchy": "PERMEN",
          "validity_status": "BERLAKU",
          "semantic_hits_count": 4,
          "semantic_hit_pasals": ["40", "38", "39", "8"],
          "semantic_hits": [
            {
              "pasal": "40",
              "bab": "XIV SANKSI ADMINISTRATIF",
              "snippet": "..."
            }
          ]
        }
      ]
    },
    "peraturan_tingkat_daerah": {},
    "peraturan_lainnya": {},
    "peraturan_tidak_berlaku": {}
  },
  "request_id": "..."
}

Field penting

Hasil peraturan-terkait juga dapat mengembalikan pdf_download_link.

Gunakan pdf_download_link dari hasil API apabila aplikasi memerlukan dokumen PDF untuk pembacaan atau verifikasi sumber.

Path lokal, skor internal retrieval, dan detail implementasi backend tidak menjadi bagian dari public API.

7. Query Pasal Terkait

POST /api/v1/query/pasal-terkait

Mencari Pasal secara langsung berdasarkan makna query.

Gunakan endpoint ini bila aplikasi membutuhkan hasil pada tingkat Pasal tanpa terlebih dahulu mengelompokkannya per regulasi.

Contoh request

curl --silent --show-error --request POST \
  'https://aturan.org/api/v1/query/pasal-terkait' \
  --header "Authorization: Bearer ${ATURANORG_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "syarat pendirian perseroan terbatas oleh dua orang atau lebih",
    "top_k": 10
  }'

Setiap item hasil dapat berisi:

• nama regulasi;
• regulation_id;
• hierarki regulasi;
• status keberlakuan;
• lokasi Pasal;
• isi atau preview Pasal;
• pdf_download_link bila tersedia;
• metadata sumber yang diizinkan untuk respons publik.

Untuk pencarian substantif, gunakan top_k setidaknya 10. Gunakan hingga 20 bila membutuhkan recall lebih tinggi.

Jangan menganggap urutan pertama selalu merupakan Pasal yang paling menentukan secara hukum. Ranking semantic retrieval menunjukkan kemiripan makna dan harus dianalisis lebih lanjut dalam konteks persoalan hukum.

8. Pengelompokan, filter, dan urutan Peraturan Terkait

Respons peraturan-terkait menyediakan groups sebagai struktur utama hasil:

{
  "groups": {
    "peraturan_tingkat_pusat": {
      "UU": []
    },
    "peraturan_tingkat_daerah": {},
    "peraturan_lainnya": {},
    "peraturan_tidak_berlaku": {}
  }
}

Keempat group selalu dikirim, termasuk ketika tidak memiliki hasil.

Hierarchy hanya dikirim bila memiliki hasil. Contohnya, regulasi UU berada pada:

groups.peraturan_tingkat_pusat.UU

Sedangkan group pusat dapat berupa:

{}

bila tidak ada hasil tingkat pusat.

Endpoint ini tidak mengirim items, agar setiap hasil regulasi dan preview Pasalnya tidak diduplikasi.

Gunakan groups sebagai satu-satunya sumber hasil, dengan urutan kategori besar lalu hierarchy.

Filter dan pengelompokan diterapkan setelah semantic retrieval sehingga tidak mengubah kandidat yang dihasilkan oleh proses semantic retrieval inti.

Parameter opsional pada body peraturan-terkait

Metadata meta melaporkan jumlah sebelum/sesudah filter serta filter yang telah dinormalisasi dan diterapkan.

9. Parameter dan batas layanan

semantic_hit_pasals memuat seluruh nomor Pasal unik hasil retrieval pada regulasi tersebut dan tidak dibatasi oleh maksimum 10 preview pada semantic_hits.

top_k yang lebih tinggi memperluas kandidat hasil, tetapi dapat menambah waktu pemrosesan dan ukuran respons.

Respons public API menggunakan JSON terstruktur. Field debug, skor retrieval internal, path lokal, dan detail implementasi backend tidak diekspos.

10. Membaca isi Pasal

GET /api/v1/query/isi-pasal

Endpoint ini digunakan untuk membaca Pasal tertentu setelah regulasi ditemukan melalui salah satu endpoint discovery.

Contoh request

curl --silent --show-error \
  'https://aturan.org/api/v1/query/isi-pasal?regulation_id=990100&pasal=40' \
  --header "Authorization: Bearer ${ATURANORG_API_KEY}"

Parameter

Jangan menebak regulation_id

isi-pasal bukan endpoint discovery.

Jangan:

• menebak regulation_id;
• membentuk ID sendiri;
• melakukan increment atau decrement terhadap ID;
• menggunakan ID hanya karena pernah diketahui sebelumnya;
• menggunakan ID dari sumber yang tidak berasal dari hasil discovery Aturan.org.

Dapatkan regulation_id terlebih dahulu melalui salah satu dari:

POST /query/judul-peraturan
POST /query/peraturan-terkait
POST /query/pasal-terkait

Pastikan hasil tersebut memang menunjuk pada regulasi yang dimaksud sebelum menggunakan ID untuk membaca Pasal.

Jika regulation_id tidak lagi dapat di-resolve, lakukan pencarian kembali untuk memperoleh referensi yang tersedia saat itu.

11. Lifecycle regulation_id

regulation_id adalah identifier yang diberikan API agar regulasi hasil discovery dapat direferensikan pada endpoint lanjutan.

Aplikasi tidak boleh mengasumsikan regulation_id sebagai identifier permanen atau canonical kecuali dokumentasi menyatakan demikian.

Praktik yang disarankan:

Search
  ↓
temukan regulasi
  ↓
ambil regulation_id
  ↓
pastikan regulation_name sesuai
  ↓
baca isi Pasal

Jika aplikasi membutuhkan dokumen sumber:

Search
  ↓
temukan regulasi
  ↓
pastikan regulation_name sesuai
  ↓
gunakan pdf_download_link dari hasil

Jika ID tidak dapat digunakan, lakukan discovery kembali daripada mencoba mencari atau menebak ID pengganti.

12. Pola integrasi yang disarankan

12.1. Bila pengguna mengetahui regulasinya

Contoh:

"Tampilkan Pasal 99 PP 45 Tahun 2005"

Gunakan:

judul-peraturan
      ↓
pastikan PP 45 Tahun 2005 ditemukan
      ↓
ambil regulation_id
      ↓
isi-pasal

Jika dokumen sumber diperlukan, gunakan pdf_download_link yang diberikan pada hasil discovery.

12.2. Bila pengguna menanyakan suatu isu hukum

Contoh:

"Peraturan apa saja yang mengatur insentif kendaraan listrik?"

Gunakan:

peraturan-terkait (Top-K 100–200)
      ↓
identifikasi regulasi kandidat
      ↓
pasal-terkait bila diperlukan
      ↓
isi-pasal untuk ground truth
      ↓
pdf_download_link untuk verifikasi dokumen bila diperlukan

12.3. Bila pengguna mencari norma tertentu

Contoh:

"Ketentuan mengenai kewajiban pembayaran kompensasi PKWT"

Gunakan:

pasal-terkait (Top-K 10–20)
      ↓
periksa kandidat Pasal
      ↓
ambil regulation_id
      ↓
isi-pasal
      ↓
pdf_download_link bila verifikasi dokumen diperlukan

12.4. Bila persoalan memiliki beberapa dimensi

Jangan memaksakan seluruh persoalan kompleks ke dalam satu semantic query yang terlalu luas.

Sebagai contoh, penelitian mengenai PLTS atap dapat dipisahkan menjadi:

pengaturan PLTS atap

perizinan PLTS atap

kewajiban pemegang izin usaha penyediaan tenaga listrik terkait PLTS atap

ekspor impor energi listrik PLTS atap

kapasitas pemasangan PLTS atap

Aplikasi atau agent dapat membandingkan hasil beberapa retrieval tersebut sebelum menentukan regulasi dan Pasal yang perlu dibaca.

13. Prinsip penggunaan oleh RAG dan AI Agent

Untuk sistem RAG atau AI agent, perlakukan Aturan.org sebagai sistem retrieval, bukan sebagai mesin yang mengambil kesimpulan hukum secara otomatis.

Pola yang disarankan:

Pertanyaan pengguna
        ↓
pahami isu
        ↓
formulasikan retrieval query
        ↓
Discovery
        ↓
Candidate regulations / Pasal
        ↓
evaluasi hasil
        ↓
baca norma yang diperlukan
        ↓
verifikasi sumber bila diperlukan
        ↓
Legal reasoning oleh aplikasi / agent

Semantic retrieval digunakan untuk menemukan kandidat berdasarkan makna.

Hasil semantic retrieval bukan penetapan bahwa suatu regulasi atau Pasal pasti relevan secara hukum.

Aplikasi atau agent tetap harus menilai:

• bunyi lengkap Pasal;
• konteks Pasal dalam regulasi;
• status keberlakuan;
• perubahan dan pencabutan;
• hubungan antarregulasi;
• hierarki regulasi;
• regulasi pelaksana yang relevan; dan
• fakta yang sedang dianalisis.

Untuk penelitian yang membutuhkan recall tinggi:

• gunakan peraturan-terkait dengan top_k 100–200;
• gunakan pasal-terkait dengan top_k 10–20;
• jangan hanya mengambil hasil pertama;
• lakukan query tambahan apabila satu retrieval belum mencakup seluruh isu;
• baca Pasal yang relevan secara lengkap sebelum menjadikannya dasar analisis.

14. Penanganan error

Aplikasi sebaiknya menangani status HTTP secara eksplisit.

Bila respons menyediakan request_id, simpan identifier tersebut untuk tracing atau pelaporan masalah.

Jangan mengatasi 404 pada regulation_id dengan menebak ID lain.

Jalankan endpoint discovery kembali.

15. Ringkasan endpoint

pdf_download_link dapat tersedia pada hasil discovery sebagai referensi untuk mengakses dokumen PDF regulasi. PDF bukan endpoint discovery dan tidak perlu dicari dengan membentuk URL sendiri.

16. Ringkasan mental model

Gunakan tiga endpoint pertama untuk menemukan:

judul-peraturan
peraturan-terkait
pasal-terkait

Gunakan endpoint berikut untuk membaca norma yang sudah ditemukan:

isi-pasal

Dokumen PDF, bila tersedia, diperoleh melalui:

pdf_download_link

yang dikembalikan pada hasil discovery.

Dengan demikian:

                    DISCOVERY
                        │
          ┌─────────────┼─────────────┐
          │             │             │
        judul        peraturan       pasal
      peraturan       terkait       terkait
          │             │             │
          └─────────────┼─────────────┘
                        ▼
                VERIFY regulation
                        │
              ┌─────────┴─────────┐
              │                   │
              ▼                   ▼
        regulation_id      pdf_download_link
              │                   │
              ▼                   ▼
          isi-pasal          source PDF
              │
              ▼
          READ NORM

Jangan membalik alur tersebut dengan menebak regulation_id.

17. API atau MCP?

Aturan.org menyediakan REST API dan MCP Server di atas sistem retrieval regulasi yang sama, tetapi keduanya ditujukan untuk pola integrasi yang berbeda.

Gunakan REST API apabila:

• aplikasi menentukan sendiri endpoint yang akan dipanggil;
• developer ingin mengontrol request dan response secara eksplisit;
• retrieval menjadi bagian dari backend atau pipeline aplikasi;
• aplikasi memiliki workflow yang sudah ditentukan;
• sistem membutuhkan integrasi HTTP/JSON langsung.

Gunakan MCP apabila:

• AI agent perlu memilih sendiri tool retrieval yang diperlukan;
• model perlu melakukan retrieval secara iteratif;
• AI client mendukung Model Context Protocol;
• workflow bersifat agentic;
• model perlu berpindah antara discovery, pembacaan Pasal, dan analisis berdasarkan hasil sebelumnya.

Secara sederhana:

REST API
Application controls retrieval
        │
        ▼
Aturan.org


MCP
AI agent controls tool selection
        │
        ▼
Aturan.org

Untuk integrasi AI berbasis MCP, lihat:

https://aturan.org/mcp