GET /notes

Menelusuri seluruh notulen milik pemilik API key, terbaru lebih dulu, dengan paginasi cursor. Transkrip TIDAK PERNAH disertakan di sini karena ukurannya bisa ratusan kilobyte per baris; ambil lewat GET /notes/{id}?include=transcript kalau memang dibutuhkan. Filter status berguna untuk memantau antrean: recording_ready dan processing berarti pekerjaan masih berjalan, completed berarti hasilnya siap diambil, dan failed berarti perlu dilihat failure_code-nya. Parameter q mencari di judul dan ringkasan, tidak di dalam transkrip.

#Endpoint

GET https://se-hari.com/api/v1/notes

Butuh scope notulen:read. Scope ditetapkan saat key dibuat dan tidak bisa ditambahkan belakangan — kalau key Anda kurang izin, buat key baru lalu cabut yang lama. Kekakuan ini disengaja: scope yang bisa dinaikkan diam-diam berarti key yang bocor hari ini bisa menjadi lebih berbahaya besok. Beri setiap integrasi key sendiri dengan scope sesempit mungkin, supaya mencabut satu integrasi tidak pernah berarti mematikan yang lain. Daftar ini memakai paginasi cursor, bukan offset. Ambil next_cursor dari respons lalu kirim kembali sebagai starting_after untuk halaman berikutnya, dan berhenti saat has_more bernilai false. Cursor dipilih karena offset melewatkan baris begitu ada data baru masuk di tengah penelusuran — pada daftar yang bertambah setiap hari itu bukan kasus langka melainkan kejadian harian, dan gejalanya adalah baris yang hilang tanpa satu pun error. Filter tanggal menerima ISO-8601. Perlu diingat seluruh jadwal Se-Hari memakai zona WIB (UTC+7): meeting yang tampil pukul 09:00 di dashboard adalah 02:00 UTC, dan menyaring dengan tanggal UTC polos akan memotong tujuh jam pertama setiap hari tanpa memberi tahu Anda.

#Parameter query

#Contoh

curl -X GET "https://se-hari.com/api/v1/notes?limit=10&starting_after=nilai" \
  -H "Authorization: Bearer $SEHARI_API_KEY"

const res = await fetch('https://se-hari.com/api/v1/notes', {
	method: 'GET',
	headers: {
			'Authorization': `Bearer ${process.env.SEHARI_API_KEY}`,
		}
});

if (!res.ok) {
	const { error } = await res.json();
	// error.code stabil dan bisa dicabang; error.message untuk manusia.
	throw new Error(`${error.code}: ${error.message}`);
}

const data = await res.json();

import os, requests

res = requests.get(
    "https://se-hari.com/api/v1/notes",
    headers={"Authorization": f"Bearer {os.environ['SEHARI_API_KEY']}"},
    timeout=30,
)

if not res.ok:
    err = res.json()["error"]
    raise RuntimeError(f"{err['code']}: {err['message']}")

data = res.json()

#Field tiap item di `data`

#Menelusuri semua halaman

Satu request hanya mengembalikan maksimum 100 baris. Untuk mengambil semuanya, ikuti next_cursor sampai has_more bernilai false — jangan menghitung sendiri posisinya.

async function ambilSemua() {
	const semua = [];
	let cursor = null;

	do {
		const qs = new URLSearchParams({ limit: "100" });
		if (cursor) qs.set("starting_after", cursor);

		const res = await fetch(`https://se-hari.com/api/v1/notes?${qs}`, {
			headers: { Authorization: `Bearer ${process.env.SEHARI_API_KEY}` }
		});
		const page = await res.json();

		semua.push(...page.data);
		cursor = page.has_more ? page.next_cursor : null;
	} while (cursor);

	return semua;
}

#Kalau gagal

Setiap kegagalan memakai amplop yang sama, dan code di dalamnya stabil — cabangkan logika Anda ke sana, jangan ke message yang teksnya bisa diperbaiki sewaktu-waktu.

{
  "error": {
    "code": "invalid_parameter",
    "message": "Penjelasan untuk manusia.",
    "docs_url": "https://se-hari.com/docs/error/invalid-parameter",
    "request_id": "req_a1b2c3d4e5f6",
    "details": {}
  }
}

#Alur khas

Notulen selalu berawal dari sebuah rekaman. Rekaman itu bisa datang sendiri (meeting Zoom yang direkam diarsipkan otomatis) atau Anda unggah sendiri. Setelah rekaman ada, pembuatan notulen berjalan asinkron: endpoint mengantre pekerjaan lalu langsung menjawab, dan hasilnya menyusul beberapa menit kemudian.

1. GET /recordings?has_note=false — cari rekaman yang belum pernah diproses
2. POST /notes dengan recording_id dari langkah 1 — antrekan pekerjaannya
3. Tunggu webhook note.completed, atau polling GET /notes/{id} sampai status menjadi completed
4. GET /notes/{id}?include=summary,action_items — ambil hasilnya

Polling bukan pilihan pertama. Rekaman satu jam butuh beberapa menit untuk diproses, dan menanyakan statusnya setiap detik hanya menghabiskan kuota rate limit Anda. Daftarkan webhook note.completed sekali, lalu biarkan Se-Hari yang memberi tahu.

#Yang sering keliru

• Key disalin sebagian. API key Se-Hari panjangnya tetap: sh_live_ diikuti 43 karakter. Kalau panjangnya berbeda, yang salah adalah proses penyalinannya, bukan key-nya — dan pesan 401 tidak akan mengatakan itu.
• Scope kurang, bukan key salah. 403 di sini berarti key-nya dikenali. Periksa scope-nya lewat GET /me, lalu buat key baru kalau memang kurang; scope tidak bisa ditambahkan ke key yang sudah jadi.
• Hormati Retry-After. Mencoba lagi lebih cepat dari yang disebutkan hanya memperpanjang masa tunggu. Kalau Anda sering menyentuhnya, kemungkinan besar Anda sedang polling sesuatu yang seharusnya ditangani webhook.

#Selanjutnya

• Autentikasi dan API key — cara membuat key dan memilih scope
• Kode error — arti setiap kode dan cara memperbaikinya
• Idempotency — kenapa retry aman kalau dilakukan dengan benar
• Spesifikasi OpenAPI — kontrak mesin, cocok untuk men-generate klien