API Aturan.org menyediakan pencarian semantik untuk regulasi Indonesia. API ini dapat digunakan oleh aplikasi, LegalTech, Retrieval-Augmented Generation (RAG), dan sistem AI yang membutuhkan pencarian berdasarkan makna, bukan hanya kata kunci.
Base URL:
https://aturan.org/api/v1
Autentikasi dan key uji publik
Semua endpoint memerlukan Bearer Token.
Authorization: Bearer aturanorg-api-ujicoba-1234567890abcdef
Key di atas adalah key uji publik sementara selama sistem login belum tersedia.
Gunakan key ini hanya untuk mencoba REST API Aturan.org; key tersebut berbeda
dari token MCP. Key dapat dirotasi atau dibatasi sewaktu-waktu. Request tanpa
API key atau menggunakan key yang tidak valid menerima respons 401 Unauthorized.
Endpoint publik
Query Judul Peraturan
POST /api/v1/query/judul-peraturan
Mencari judul regulasi secara literal/as-is menggunakan indeks SQLite FTS5.
Gunakan endpoint ini untuk nomor, tahun, jenis, atau nama dokumen spesifik;
misalnya UU 30 Tahun 2009 atau PP 45 Tahun 2009. Endpoint ini bukan
pencarian semantik dan tidak menyimpulkan isi norma.
curl --silent --show-error --request POST \
'https://aturan.org/api/v1/query/judul-peraturan' \
--header 'Authorization: Bearer aturanorg-api-ujicoba-1234567890abcdef' \
--header 'Content-Type: application/json' \
--data '{"query":"PP 45 Tahun 2009","top_k":10,"sort":"relevance"}'
Setiap item mengembalikan regulation_id dan pdf_download_link. Gunakan ID
tersebut pada GET /api/v1/query/isi-pasal bila user meminta Pasal spesifik.
Detail resolver internal seperti source_pdf_relpath tidak diekspos.
Query Peraturan Terkait
POST /api/v1/query/peraturan-terkait
Mencari regulasi yang relevan untuk suatu query, lalu mengelompokkan Pasal kandidat pada masing-masing regulasi.
curl --silent --show-error --request POST \
'https://aturan.org/api/v1/query/peraturan-terkait' \
--header 'Authorization: Bearer aturanorg-api-ujicoba-1234567890abcdef' \
--header 'Content-Type: application/json' \
--data '{
"query": "sanksi administratif pertambangan",
"top_k": 30
}'
Contoh bagian respons:
{
"query": "sanksi administratif pertambangan",
"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_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:
| Field | Keterangan |
|---|---|
groups |
Hasil regulasi bertingkat: kategori besar → hierarchy → daftar regulasi. |
regulation_name |
Nama regulasi yang relevan pada item di dalam groups. |
regulation_id |
ID enam digit yang diterbitkan retrieval untuk membaca Pasal/PDF secara progresif. Agent tidak perlu mengirim ulang judul maupun shard. |
semantic_hits_count |
Jumlah Pasal kandidat semantik pada regulasi tersebut. |
semantic_hit_pasals |
Seluruh nomor Pasal unik yang ditemukan untuk regulasi tersebut. |
semantic_hits |
Preview Pasal kandidat dalam bentuk metadata dan snippet. |
request_id |
Identifier request untuk pelacakan bila diperlukan. |
Hasil peraturan-terkait juga mengembalikan regulation_id dan
pdf_download_link; source_pdf_relpath adalah detail internal dan tidak lagi
menjadi bagian dari respons public API.
Query Pasal Terkait
POST /api/v1/query/pasal-terkait
Mencari Pasal secara langsung. Gunakan endpoint ini bila aplikasi membutuhkan hasil pada tingkat Pasal tanpa terlebih dahulu mengelompokkannya per regulasi.
curl --silent --show-error --request POST \
'https://aturan.org/api/v1/query/pasal-terkait' \
--header 'Authorization: Bearer aturanorg-api-ujicoba-1234567890abcdef' \
--header 'Content-Type: application/json' \
--data '{
"query": "syarat pendirian perseroan terbatas",
"top_k": 10
}'
Setiap item hasil dapat berisi nama regulasi, hierarki, status berlaku, lokasi Pasal, isi Pasal, dan metadata sumber yang diizinkan untuk respons publik.
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.
Pengelompokan dan filter dikerjakan gateway web setelah semantic retrieval,
sehingga tidak mengubah ranking retrieval di server inti.
Parameter opsional pada body peraturan-terkait:
| Parameter | Bentuk | Perilaku |
|---|---|---|
validity_statuses |
string[] |
Checkbox keberlakuan: BERLAKU dan/atau TIDAK_BERLAKU; kosong berarti semua. |
sort |
default, hierarchy, atau hits |
Radio urutan di dalam masing-masing group. default mempertahankan urutan semantic retrieval. |
sort_latest |
boolean | Checkbox Terbaru. Menjadi urutan utama pada default, dan tie-breaker untuk hits. |
regulation_types |
string[] |
Checkbox jenis/hierarki regulasi; kosong berarti semua. |
title_include |
string[] |
Semua tag harus ada dalam judul. |
title_exclude |
string[] |
Item dibuang bila salah satu tag ada dalam judul. |
regions |
string[] |
Filter inklusif hanya untuk peraturan_tingkat_daerah; group pusat, lainnya, dan tidak berlaku tetap tidak tersaring oleh parameter ini. |
Metadata meta melaporkan jumlah sebelum/sesudah filter serta filter yang
telah dinormalisasi dan diterapkan.
Perilaku default saat ini
Nilai berikut adalah perilaku default layanan saat ini. Pengaturan ini dapat menjadi configurable pada fase berikutnya.
| Perilaku | Default saat ini |
|---|---|
| Query | Wajib diisi, panjang 1–2.000 karakter. |
top_k Query Pasal Terkait |
Default 10, rentang 1–20. |
top_k Query Peraturan Terkait |
Default 40, rentang 20–200. |
sort_override Query Peraturan Terkait |
Kosong secara default; menerima maksimal 4 nilai. |
| Snippet per regulasi | semantic_hits memuat maksimal 10 preview Pasal per regulasi. |
| Panjang snippet | Maksimal 320 karakter per snippet; dapat lebih pendek agar kutipan tetap koheren. |
| Daftar Pasal | semantic_hit_pasals memuat seluruh nomor Pasal unik hasil retrieval pada regulasi tersebut, tidak dibatasi oleh maksimum 10 snippet. |
| Respons | JSON terstruktur; field debug, skor retrieval, path lokal, dan detail internal tidak diekspos. |
top_k yang lebih tinggi dapat memperluas kandidat hasil, tetapi juga dapat
menambah waktu dan ukuran respons. Snippet dimaksudkan sebagai preview; gunakan
semantic_hit_pasals untuk mengetahui cakupan Pasal kandidat pada suatu
regulasi.
Membaca isi Pasal dengan ID retrieval
peraturan-terkait mendaftarkan setiap hasil yang dikeluarkannya ke resolver
in-memory milik proses gateway. Untuk setiap regulation_id pada respons,
agent dapat membaca Pasal lengkap tanpa mengirim regulation_name, shard, atau
source_pdf_relpath:
GET /api/v1/query/isi-pasal?regulation_id=990100&pasal=1320
Authorization: Bearer aturanorg-api-ujicoba-1234567890abcdef
ID hanya berlaku setelah ID itu didapat dari peraturan-terkait pada proses
gateway yang sama. Registry tidak disimpan ke disk, memiliki TTL/LRU, dan akan
kosong setelah restart; jika referensi tidak ditemukan, lakukan pencarian
peraturan-terkait kembali. Endpoint lama berbasis shard +
regulation_name tetap tersedia sementara untuk kompatibilitas.
Deployment: karena registry hidup di memory proses, jalankan gateway API dengan satu worker atau gunakan sticky routing yang memastikan rangkaian
peraturan-terkait → isi-pasal/PDFdiproses worker yang sama.
PDF dari hasil yang sama juga dapat dibaca dengan:
GET /api/v1/file/pdf?regulation_id=990100
Authorization: Bearer aturanorg-api-ujicoba-1234567890abcdef
Ringkasan endpoint
| Method | Endpoint | Kegunaan |
|---|---|---|
POST |
/api/v1/query/peraturan-terkait |
Mencari regulasi relevan beserta Pasal kandidatnya. |
POST |
/api/v1/query/pasal-terkait |
Mencari Pasal relevan secara langsung. |
POST |
/api/v1/query/judul-peraturan |
Mencari judul regulasi literal/as-is. |