REST API Aturan.org

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:

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:

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.

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/PDF diproses 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