Geliştiriciler

API ve MCP

Legalist’in kaynaklı Yargıtay ve mevzuat aramasını, çalışma alanınızın dosyalarını, müvekkillerini, belgelerini ve araştırma oturumlarını kendi yazılımınıza ya da yapay zekâ asistanınıza bağlayın. Her anahtar tek bir çalışma alanına aittir ve yalnızca onun verisini okur.

Başlarken

  1. Legalist’te API ve MCP sayfasını açın (çalışma alanı sahibi, avukat ya da büro personeli olmanız gerekir).
  2. “Yeni anahtar” ile bir anahtar oluşturun ve gösterildiği anda kopyalayın; bir daha gösterilmez.
  3. Aşağıdaki örneklerde lgl_… yerine anahtarınızı koyun.
curl https://legalist.co/api/v1/workspace \
  -H "Authorization: Bearer lgl_…"

Kimlik doğrulama

Her istekte anahtarı Authorization: Bearer lgl_… başlığıyla (ya da x-api-key başlığıyla) gönderin. Anahtarlar iki yetki taşıyabilir:

  • read — dosyalar, müvekkiller, belgeler, oturumlar, karar ve mevzuat metni.
  • search — Yargıtay ve mevzuat araması. Her arama, Legalist Chat’teki bir soru gibi aylık sorgu hakkınızdan 1 düşer.

İptal edilen ya da çalışma alanı pasifleştirilen anahtarlar hemen 401 döner.

REST uç noktaları

Taban adres https://legalist.co/api/v1. Yanıtlar JSON; tarihler ISO 8601. POST gövdeleri Content-Type: application/json ister.

GET/api/v1/workspaceyetki: read

Anahtarın bağlı olduğu çalışma alanı, planı ve bu ayki sorgu kullanımı.

{
  "workspace": { "id": "…", "name": "Yalçın Hukuk Bürosu", "slug": "yalcin", "city": "İstanbul" },
  "plan": { "code": "premium", "name": "Premium" },
  "usage": { "queries_used": 412, "monthly_query_limit": 2000 }
}

POST/api/v1/search/decisionsyetki: search

Yargıtay kararlarında doğal dille arama. 1 sorgu harcar.

curl -X POST https://legalist.co/api/v1/search/decisions \
  -H "Authorization: Bearer lgl_…" \
  -H "Content-Type: application/json" \
  -d '{ "query": "işe iade davasında arabuluculuk süresi", "top_n": 5 }'
{
  "results": [
    { "n": 1, "decision_uid": "…", "daire": "9. Hukuk Dairesi", "esas_no": "2024/10170", "karar_no": "2024/14797",
      "decision_date": "2024-11-18", "citation": "9. HD, 2024/10170 E., 2024/14797 K., 18.11.2024", "snippet": "…" }
  ],
  "remaining_queries": 1587
}

POST/api/v1/search/legislationyetki: search

Türk mevzuatında madde düzeyinde arama. 1 sorgu harcar.

curl -X POST https://legalist.co/api/v1/search/legislation \
  -H "Authorization: Bearer lgl_…" \
  -H "Content-Type: application/json" \
  -d '{ "query": "fesih bildirimine itiraz", "top_n": 5 }'
{
  "results": [
    { "n": 1, "statute_uid": "…", "statute_title": "İş Kanunu", "mevzuat_no": "4857", "yururlukte": true,
      "section": "Madde 20", "citation": "4857 sayılı İş Kanunu m. 20", "snippet": "…" }
  ],
  "remaining_queries": 1586
}

GET/api/v1/decisions/{uid}yetki: read

Bir kararın tam metni ve künyesi. {uid}, arama sonucundaki decision_uid değeridir.

{ "decision": { "uid": "…", "daire": "…", "esas_no": "…", "karar_no": "…", "decision_date": "…", "content": "…" } }

GET/api/v1/legislation/{uid}yetki: read

Bir mevzuat kaydının tam metni. {uid}, arama sonucundaki statute_uid değeridir; yururlukte: false mülga demektir.

{ "statute": { "uid": "…", "title": "İş Kanunu", "mevzuat_no": "4857", "yururlukte": true, "rg_date": "2003-06-10", "content": "…" } }

GET/api/v1/casesyetki: read

Dava dosyaları, en son güncellenen önce (en çok 200).

{ "cases": [ { "id": "…", "title": "Arslan / Kaya Lojistik — işe iade", "case_number": "2026/418", "status": "active", "updated_at": "…" } ] }

GET/api/v1/cases/{id}yetki: read

Bir dosyanın özeti, gelişmeleri (zaman çizelgesi) ve belgeleri.

{ "case": { "id": "…", "title": "…", "summary": "…" }, "events": [ … ], "documents": [ … ] }

GET/api/v1/clientsyetki: read

Müvekkiller: ad, e-posta, şirket, telefon.

{ "clients": [ { "id": "…", "full_name": "Ece Arslan", "email": "…", "company": null, "is_active": true } ] }

GET/api/v1/documents?case_id={id}yetki: read

Belgeler; case_id ile bir dosyaya göre süzülür (isteğe bağlı).

{ "documents": [ { "id": "…", "filename": "kira-sozlesmesi.pdf", "mime_type": "application/pdf", "status": "ready" } ] }

GET/api/v1/documents/{id}/textyetki: read

Belgenin OCR ile çıkarılmış metni.

{ "document": { "id": "…", "filename": "…" }, "text": "…" }

GET/api/v1/threadsyetki: read

Legalist Chat araştırma oturumları (en çok 100).

{ "threads": [ { "id": "…", "title": "İhbar tazminatında zamanaşımı", "sources_used": ["case_law"], "updated_at": "…" } ] }

GET/api/v1/threads/{id}yetki: read

Bir oturumun mesajları ve atıfları.

{ "thread": { "id": "…", "title": "…" }, "messages": [ { "role": "user", "content": "…" }, { "role": "assistant", "content": "…", "citations": [ … ] } ] }

Hatalar ve sınırlar

Hatalar her zaman aynı biçimde döner:

{ "error": { "code": "quota_exceeded", "message": "Bu ayın sorgu hakkı doldu." } }
DurumKodAnlamı
400invalid_request · invalid_jsonEksik ya da hatalı alan
401unauthorizedAnahtar yok, geçersiz ya da iptal edilmiş
403forbiddenAnahtarın bu işlem için yetkisi yok
404not_foundKayıt bu çalışma alanında yok
429quota_exceeded · credit_exceededAylık sorgu ya da kredi hakkı doldu
502search_failed · rate_limitedArama servisi geçici olarak yanıt vermiyor; tekrar deneyin

Sorgu hakkı planınıza bağlıdır (Basic 500, Premium 2.000 sorgu/ay). Okuma uç noktaları sorgu harcamaz. Listeler en son kayıtlarla sınırlıdır (dosya ve belge 200, oturum 100).

MCP sunucusu

Legalist, Model Context Protocol sunucusu olarak da çalışır (Streamable HTTP, oturumsuz). Adres:

https://legalist.co/api/mcp

Aynı API anahtarıyla kimlik doğrulanır; araçlar anahtarın yetkilerine göre listelenir.

AraçYetkiNe yapar
legalist_workspacereadÇalışma alanı, plan ve sorgu kullanımı
search_decisionssearchYargıtay araması (query, top_n) — 1 sorgu
search_legislationsearchMevzuat araması (query, top_n) — 1 sorgu
get_decisionreadKararın tam metni (uid = decision_uid)
get_legislationreadMevzuatın tam metni (uid = statute_uid)
list_casesreadDosyalar
get_casereadDosya ayrıntısı, gelişmeler, belgeler (id)
list_clientsreadMüvekkiller
list_documentsreadBelgeler (case_id isteğe bağlı)
get_document_textreadBelge metni (id)
list_threadsreadAraştırma oturumları
get_threadreadOturum mesajları ve atıfları (id)

Doğrudan JSON-RPC ile denemek için:

curl -X POST https://legalist.co/api/mcp \
  -H "Authorization: Bearer lgl_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_decisions","arguments":{"query":"ihbar tazminatı zamanaşımı","top_n":3}}}'

Claude ve Cursor kurulumu

Claude Code

claude mcp add --transport http legalist https://legalist.co/api/mcp \
  --header "Authorization: Bearer lgl_…"

Claude Desktop

Ayarlar → Geliştirici → Yapılandırmayı düzenle; claude_desktop_config.json içine:

{
  "mcpServers": {
    "legalist": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://legalist.co/api/mcp", "--header", "Authorization:Bearer ${LEGALIST_API_KEY}"],
      "env": { "LEGALIST_API_KEY": "lgl_…" }
    }
  }
}

Cursor

.cursor/mcp.json (proje) ya da ~/.cursor/mcp.json (genel):

{
  "mcpServers": {
    "legalist": {
      "url": "https://legalist.co/api/mcp",
      "headers": { "Authorization": "Bearer lgl_…" }
    }
  }
}

Kurulumdan sonra asistana örneğin “Legalist’te işe iade arabuluculuk süresine ilişkin Yargıtay kararlarını bul ve künyeleriyle özetle” diyebilirsiniz.

Güvenlik ve veri

  • Anahtar yalnızca SHA-256 özeti olarak saklanır; Legalist bile düz anahtarı geri getiremez.
  • Her anahtar tek bir çalışma alanına bağlıdır; başka bir büronun verisine erişemez.
  • Anahtar oluşturma, iptal ve silme işlemleri denetim kaydına yazılır.
  • Anahtarı tarayıcı koduna ya da herkese açık depolara koymayın; sızdığından şüphelenirseniz hemen iptal edin.
  • Legalist hukuki tavsiye vermez; API ve MCP çıktısı araştırmadır.