Hakxbox Note API — Dokümantasyon

Hızlı başlangıç

Hakxbox hesabınızda Ayarlar → API bölümünden bir API Key veya Personal Access Token (PAT) oluşturun.
GET /v1/workspaces ile workspace ID'nizi alın.
X-Workspace-Id header'ı ile notlarınızı listeleyin veya tek not detayını okuyun.

v1 yalnızca okuma destekler (listele + detay). Yazma işlemleri gelecek sürümlerde eklenecektir.

Tüm korumalı endpoint'ler için aşağıdaki header zorunludur:

Authorization: Bearer <token_veya_api_key>

hkx_live_ ile başlayan anahtar. Ayarlardan oluşturulur; tam değer yalnızca bir kez gösterilir.

Örnek

curl -H "Authorization: Bearer hkx_live_XXXXXXXXXXXX" \
  https://noteapi.hakxbox.com.tr/v1/workspaces

Sanctum tabanlı token. Gelişmiş entegrasyonlar ve sunucu tarafı scriptler için uygundur. notes:read yetkisi ile oluşturulur.

Örnek

curl -H "Authorization: Bearer 1|xxxxxxxx" \
  https://noteapi.hakxbox.com.tr/v1/workspaces

Alternatif olarak API Key için X-Api-Key header'ı da kullanılabilir.

Not listeleme için X-Workspace-Id header'ı zorunludur. Workspace ID'lerinizi almak için:

GET /v1/workspaces

curl -H "Authorization: Bearer TOKEN" \
  https://noteapi.hakxbox.com.tr/v1/workspaces

Tek not detayı (GET /v1/notes/{id|slug}) için workspace header'ı opsiyoneldir; yetki not üzerinden kontrol edilir.

Başarılı yanıtlar:

{
  "ok": true,
  "data": { ... },
  "meta": { "page": 1, "per_page": 25, "total": 42, "last_page": 2 }
}

Hata yanıtları:

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "Geçersiz veya süresi dolmuş API anahtarı / token."
  }
}

Erişebildiğiniz workspace listesini döner.

Header	Zorunlu	Açıklama
`Authorization`	Evet	Bearer token veya API key

Workspace içindeki notları sayfalı listeler. Görünürlük kuralları web uygulaması ile aynıdır.

Header / Param	Zorunlu	Açıklama
`Authorization`	Evet	Bearer token veya API key
`X-Workspace-Id`	Evet	Workspace kimliği
`page`	Hayır	Sayfa numarası (varsayılan 1)
`per_page`	Hayır	Sayfa boyutu (max 50, varsayılan 25)
`scope`	Hayır	all, recent, favorites, pinned, archived, trash, shared_with_me
`sort`	Hayır	updated_at, created_at, title_asc, title_desc, pinned, last_opened
`search` / `q`	Hayır	Metin araması

Örnek

curl -H "Authorization: Bearer TOKEN" \
  -H "X-Workspace-Id: 1" \
  "https://noteapi.hakxbox.com.tr/v1/notes?scope=all&per_page=25"

Tek not detayı: içerik, etiketler, klasör ve ek metadata.

Örnek

curl -H "Authorization: Bearer TOKEN" \
  https://noteapi.hakxbox.com.tr/v1/notes/my-note-slug

HTTP	error.code	Açıklama
401	unauthorized	Token/anahtar eksik veya geçersiz
403	forbidden	Yetki yok, ban veya e-posta doğrulanmamış
403	workspace_forbidden	Workspace erişimi yok
404	—	Not bulunamadı
422	workspace_required	X-Workspace-Id eksik
422	validation_error	Geçersiz query parametreleri
429	—	Rate limit aşıldı

Kimliği doğrulanmış istekler: 120/dakika kullanıcı başına.

Kimlik doğrulamasız istekler daha düşük limit ile sınırlanır.

429 yanıtında kısa süre bekleyip tekrar deneyin.