Veri Cikarimi ve Artifact'ler

Ayrıştırma nerede çalışır: belge ayrıştırma (sayfa okuma + yerleşim) Docsfra'nın kendi GPU altyapısında çalışır — sayfa görüntüleri üçüncü-taraf AI sağlayıcılarına asla gönderilmez. Model şeritlerine (ya da kendi BYOK endpoint'lerinize) yalnızca çıkarılmış metin ulaşır.

Bir belgenin isleme adimi bittiginde Docsfra size sadece ham metin geri vermez — belgenin AI-native bir temsilini (AIDR) olusturur: yapili bir "kimlik karti" (memory), sayfalarda bulunan tablo ve figurler (structured objects), belgede gecen entity'lerin ve iliskilerin bir grafi (entity graph), belge icinde kurulan mantiksal bagimliliklar (reasoning graph) ve o belge icin mevcut olan her seyin bir dokumu (artifacts). Bu bolum, o temsili disariya acan uc noktalari anlatir.

Temsil → artifact

Ic yapida, bir belgenin temsili, her cikarim adimi tamamlandikca doldurulan bagimsiz katmanlardan (memory, structured_objects, entity_graph, ...) olusan tek bir JSON nesnesidir. Her katman en-iyi- caba mantigiyla uretilir: bir katman uretilemediyse (LLM hatasi ya da belge temsil hattindan onceki bir tarihte yuklendiyse) o katman sadece eksik olur — bu hicbir zaman temel belge teslimini (markdown/JSON export) engellemez. Asagidaki uc noktalarda okudugunuz sey o temsile okuma goruntusudur, ayri bir artifact deposu degildir.

Uc nokta	Katman	Ne doner
`GET /v1/documents/{id}/memory`	`memory`	Belgenin kimlik karti: baslik, tur, amac, ozet, konular, bolum agaci
`GET /v1/documents/{id}/objects`	`structured_objects`	Belgede bulunan tablolar (row/cell JSON) ve figurler
`GET /v1/documents/{id}/entities`	`entity_graph`	Tipli entity node'lari ve aralarindaki iliskiler (edge)
`GET /v1/documents/{id}/reasoning`	`reasoning_graph`	Mantiksal bagimlilik node'lari (yukumluluk, kosul, cezai sart, ...) ve aralarindaki iliskiler (edge)
`GET /v1/documents/{id}/extract`	memory + objects + entities + reasoning	Dort katmanin tamami tek yanitta birlesik
`GET /v1/documents/{id}/artifacts`	—	Belge icin her AI artifact'inin (yukaridaki besi dahil) durum bayrakli katalogu

Auth ve entitlement

Bu alti uc noktanin tamami Authorization: Bearer <api_key> basligi gerektirir ve extract modul entitlement'i ile korunur — extract icin yetkilendirilmemis bir key 403 service_not_enabled doner (bkz. Baslangic ve Auth → Entitlement). search ve ask'in aksine, bu uc noktalarin hicbiri olculmez — cikarim sonuclarini okumak, kac kez cagrilirsa cagrilsin kredi dusmez.

Fiyatlandirma

Okumak ucretsizdir (yukariya bkz.) — faturalandirilan sey, Docsfra bir artifact'i bir belge icin ilk kez basariyla urettiginde tek seferlik uretim ucretidir:

Modul	Artifact	Birim	Varsayilan oran
`memory`	Belge Kimlik Karti (Document Memory)	belge	0.10
`entities`	Varlik Grafi (Entity Graph)	belge	0.15
`reasoning`	Mantik Grafi (Reasoning Graph)	belge	0.15
`layout`	Yerlesim/bbox (Layout Model)	sayfa	0.05

Her modul, belge basina bir kez (layout icin sayfa basina bir kez) yalnizca o artifact gercekten uretildiginde ucretlendirilir — basarisiz bir uretim denemesi (LLM hatasi, ya da modulun tenant'in plani icin acik olmamasi) hicbir zaman ucretlendirilmez; katman yukarida anlatildigi gibi sadece eksik kalir. structured_objects (tablo/figur) icin ayri bir uretim ucreti yoktur: tablo/figur cikarimi deterministiktir ve temel boru hattina dahildir. Bu oranlar tenant basina override edilebilir, Baslangic ve Auth → Metering ve kredi'deki modul oranlariyla ayni sekilde — gecerli oranlarinizi dashboard'daki usage/fiyat ekraninda gorebilirsiniz. Tekrar vurgu: bu sayfadaki okuma uc noktalari, bu uretim oranlarindan bagimsiz olarak olcumsuzdur — bir artifact var oldugu surece /memory, /entities, /reasoning, /layout, /extract ve /artifacts'i istediginiz kadar ucretsiz cagirabilirsiniz.

Memory (kimlik karti)

GET /v1/documents/{document_id}/memory

curl https://api.docsfra.com/v1/documents/d_9c1a2b3c4d5e/memory \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "document_id": "d_9c1a2b3c4d5e",
  "memory": {
    "title": "Konsimento — INV-001",
    "doc_type": "bill_of_lading",
    "purpose": "Izmir'den Rotterdam'a gonderilen bir konteyner yuk icin sevkiyat ve mulkiyet devri kaniti",
    "summary": {
      "one_line": "Izmir'den Rotterdam'a sevk edilen 40ft'lik bir konteynere ait deniz konsimentosu.",
      "paragraph": "Bu belge, INV-001 sevkiyatini kapsayan konsimentodur, ..."
    },
    "language": "tr",
    "entities": [
      { "name": "Acme Lojistik A.S.", "type": "company" },
      { "name": "Rotterdam Liman Idaresi", "type": "organization" }
    ],
    "topics": ["denizyolu tasimaciligi", "lojistik", "konteyner navlun"],
    "timeline": [
      { "date": "2026-03-14", "event": "Mal gemiye yuklendi" }
    ],
    "definitions": [],
    "references": [
      { "kind": "purchase_order", "target": "PO-88231" }
    ],
    "section_tree": [
      { "path": "1", "title": "Gonderici / Alici" },
      { "path": "2", "title": "Yuk Tanimi" }
    ],
    "segments": [
      {
        "doc_type": "bill_of_lading",
        "title": "Konsimento — INV-001",
        "page_start": 1,
        "page_end": 4,
        "one_line": "Izmir'den Rotterdam'a sevk edilen 40ft'lik bir konteynere ait deniz konsimentosu."
      }
    ]
  },
  "generated_at": "2026-03-14T10:22:03Z",
  "prompt_version": "mem-v1"
}

Buradaki memory.entities, hizli okuma icin hafif bir ad/tip listesidir — tam entity graph degildir (bkz. asagida Entities). section_tree, belgenin bolum basliklarindan deterministik olarak kurulur (LLM-uretimli degildir), bu yuzden belge bolumlerle chunk'landiysa her zaman doludur.

Cok-belgeli / birlestirilmis dosyalar

Tek bir yukleme, birden fazla mantiksal olarak ayri belgeyi birlestiren bir tarama olabilir (orn. arka arkaya taranmis bir konsimento, ardindan bir ceki listesi ve bir fatura, tek dosya icinde). memory.segments bunu yuzeye cikaran alandir: her eleman kendi doc_type, title, one_line ozeti ve birlestirilmis dosya icinde kapladigi sayfa araligiyla (page_start–page_end, 1'den baslar, her iki uc dahildir) tanimlanan bir mantiksal belgedir. Tek-belgeli bir yuklemede segments, tum sayfa araligini kapsayan tek bir elemandan olusur.

Hatalar

HTTP	code	Aciklama
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
403	`service_not_enabled`	Key, `extract` modulu icin yetkilendirilmemis
404	`not_found`	Belge yok, ya da baska bir tenant'a ait
404	`memory_not_available`	Belge var ama memory henuz uretilmedi (temsil yok, ya da `memory` katmani bos)

Objects (tablolar ve figurler)

GET /v1/documents/{document_id}/objects

curl https://api.docsfra.com/v1/documents/d_9c1a2b3c4d5e/objects \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "document_id": "d_9c1a2b3c4d5e",
  "objects": {
    "tables_count": 1,
    "figures_count": 0,
    "truncated": false,
    "tables": [
      {
        "object_id": "tbl-3-0",
        "page": 3,
        "caption": "Yuk Tanimi",
        "columns": ["Kalem", "Adet", "Agirlik (kg)"],
        "rows": [
          ["Makine parcalari", "12", "480"],
          ["Yedek parca seti", "3", "60"]
        ],
        "merged_cells": [],
        "evidence": { "page_no": 3, "span": null, "source": "page_markdown" }
      }
    ],
    "figures": []
  },
  "generated_at": "2026-03-14T10:22:07Z"
}

Tablolar deterministik olarak cikarilir (her sayfanin markdown'indan GFM pipe-tablolar ve ham HTML <table>'lar parse edilir) — bu katman bir LLM cagrisina bagli degildir. Buyuk belgelerde belge basina en cok 300 tablo / tablo basina 500 satir sinirlanir; belge bu sinira carparsa yanit "truncated": true isaretlenir.

Hatalar

HTTP	code	Aciklama
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
403	`service_not_enabled`	Key, `extract` modulu icin yetkilendirilmemis
404	`not_found`	Belge yok, ya da baska bir tenant'a ait
404	`objects_not_available`	Belge var ama structured objects henuz uretilmedi

Entities (tipli graf)

GET /v1/documents/{document_id}/entities

curl https://api.docsfra.com/v1/documents/d_9c1a2b3c4d5e/entities \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "document_id": "d_9c1a2b3c4d5e",
  "entities": {
    "node_count": 2,
    "edge_count": 1,
    "nodes": [
      {
        "entity_id": "e1",
        "type": "company",
        "canonical_name": "Acme Lojistik A.S.",
        "attributes": { "role": "shipper" },
        "evidence": { "page_no": 1 },
        "confidence": 0.6,
        "variants": [{ "name": "Acnne Lojistik A.S.", "count": 1 }],
        "needs_review": true
      },
      {
        "entity_id": "e2",
        "type": "port",
        "canonical_name": "Rotterdam",
        "attributes": {},
        "evidence": { "page_no": 1 },
        "confidence": 1.0,
        "variants": [],
        "needs_review": false
      }
    ],
    "edges": [
      { "from": "e1", "to": "e2", "relation": "ships_to" }
    ]
  },
  "generated_at": "2026-03-14T10:22:11Z"
}

type acik bir kumedir (cikarim promptu company, person, amount, date, reference, shipment, vessel, port, product, bank gibi ornekler kullanir ama bunlarla sinirli degildir). Her node, biliniyorsa gectigi sayfayi tasir; edge'ler her zaman nodes icinde bulunan entity_id'lere referans verir (sarkan edge'ler uretim sirasinda elenir).

OCR uzlastirmasi

Taranmis ya da fotografla cekilmis belgelerde ayni gercek varlik, belge icindeki farkli yerlerde farkli okunabilir — yaygin OCR/VLM karisikliklari: G↔0, 5↔S, 8↔B. Docsfra bu gecisleri ayri entity'ler olarak birakmak yerine konsensusle tek bir kanonik node'da uzlastirir: confidence (0 ile 1 arasi bir sayi, ya da hesaplanmadiysa null) secilen kanonik formun belgenin gecisleri arasinda ne kadar baskin oldugunu yansitir; variants bu node'a katilan diger yuzey formlarini, her biri {name, count} seklinde listeler; needs_review ise guven duskse YA DA node'un sayfa kaniti bulunamadiysa true olur ve node'u insan gozden gecirmesi icin isaretler. Temiz okunmus, belirsiz olmayan bir varlik ise sadece confidence: 1.0, bos bir variants dizisi ve needs_review: false alir.

Uzlastirmanin asiri-birlestirme yapmamasi icin iki korkuluk vardir: rakam iceren degerler (tarih, tutar, referans, telefon) yalnizca bilinen OCR karisikliklariyla ayrisiyorsa birlesir — gercek bir rakam farki (20,560 vs 20,000) her zaman iki ayri varlik kalir; ve ayni varliga gore FARKLI rol oynayan iki deger (ornegin bir duzenleme tarihi ile bir vade tarihi) yuzeyleri ne kadar benzerse benzesin asla birlestirilmez. Ayrica her varligin evidence alani, yuzey formunun belgede GERCEKTEN bulundugu sayfa numarasi ve karakter araligini tasir — model beyanindan degil, metinde deterministik aramayla turetilir; yuzeyi bulunamayan varlik page_no: null kalir ve needs_review isaretlenir.

Bbox-hedefli yeniden okuma

needs_review isaretli bir varlik icin Docsfra, opsiyonel olarak kaynak bolgeyi dogrudan sayfa goruntusunden yeniden okutabilir: varligin bulundugu bolge (bbox) kaynak sayfadan az bir pay (padding) ile kirpilir ve odaklanmis bir gorsel modele (VLM) ikinci, izole bir okuma icin gonderilir — sayfanin geri kalanindaki gorsel gurultuden arinmis halde. Sonuc, mevcut okumayi ya dogrular ya da duzeltir:

"evidence": {
  "page_no": 1,
  "reread": {
    "status": "corrected",
    "was": "Acnne Lojistik A.S.",
    "now": "Acme Lojistik A.S.",
    "model": "google/gemini-2.5-flash"
  }
}

status "corrected" oldugunda kanonik okuma now degerine guncellenir (eski okuma variantse tasinir) ve needs_review temizlenir. status "confirmed" oldugunda mevcut okuma degismeden korunur, sadece guven yukseltilerek needs_review temizlenir. Bu opsiyonel, best-effort bir ozelliktir (REREAD_ENABLED ile acilir/kapanir) — kapaliysa, ya da yeniden okuma basarisiz olur veya kullanilabilir bir sonuc donmezse, varlik mevcut uzlastirma sonucunu degismeden korur.

Hatalar

HTTP	code	Aciklama
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
403	`service_not_enabled`	Key, `extract` modulu icin yetkilendirilmemis
404	`not_found`	Belge yok, ya da baska bir tenant'a ait
404	`entities_not_available`	Belge var ama entity graph henuz uretilmedi

Reasoning graph (mantiksal bagimliliklar)

GET /v1/documents/{document_id}/reasoning

Bir belgede ne oldugunun (entity'ler, tablolar) otesinde, reasoning graph belge icinde ifade edilen mantiksal bagimliliklari yakalar — bir maddenin, yukumlulugun veya kosulun bir digeriyle nasil iliskili oldugunu. Tipik desenler: bir odemenin bir faturanin kesilmesine bagli olmasi, bir gecikmenin bir cezai sarti tetiklemesi, bir maddenin bir digerini gecersiz kilmasi. Bu katman yalnizca belge-ici'dir (birden fazla belge arasinda akil yurutmez) ve bilincli olarak temkinlidir: yalnizca belgenin acikca kurdugu iliskiler cikarilir — hicbir sey yorumlanmaz ya da varsayilmaz. Bir baglanti metinde ifade edilmiyorsa, grafa eklenmez.

curl https://api.docsfra.com/v1/documents/d_9c1a2b3c4d5e/reasoning \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "document_id": "d_9c1a2b3c4d5e",
  "reasoning": {
    "node_count": 2,
    "edge_count": 1,
    "nodes": [
      {
        "node_id": "r1",
        "kind": "condition",
        "statement": "Teslimat, yukleme tarihinden itibaren 15 gun icinde tamamlanmaz.",
        "entity_refs": ["e1"],
        "evidence": { "page_no": 2 }
      },
      {
        "node_id": "r2",
        "kind": "penalty",
        "statement": "Her gecikme gunu icin gunluk %0,1 cezai sart uygulanir.",
        "entity_refs": [],
        "evidence": { "page_no": 2 }
      }
    ],
    "edges": [
      { "from": "r2", "to": "r1", "relation": "depends_on" }
    ]
  },
  "generated_at": "2026-03-14T10:22:15Z",
  "prompt_version": "rsn-v1"
}

kind, obligation, condition, clause, deadline, penalty, right veya fact degerlerinden biridir. entity_refs, ifade bilinen bir entity ile ilgiliyse bir reasoning node'unu entity graph'taki entity_id'lere geri baglar (bkz. yukarida Entities) — boyle bir baglanti yoksa bos bir dizidir. relation, depends_on, requires, overrides, triggers, references veya excludes degerlerinden biridir; edge'ler her zaman nodes icinde bulunan node_id'lere referans verir (sarkan edge'ler uretim sirasinda elenir) — entity graph'in edge'leriyle ayni garanti.

/extract'in birlesik yaniti bu katmani da icerir, memory, objects ve entities'in yaninda bir reasoning alani olarak — diger katmanlarla ayni kurallar altinda bagimsiz olarak null olabilir (bkz. asagida Extract).

Hatalar

HTTP	code	Aciklama
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
403	`service_not_enabled`	Key, `extract` modulu icin yetkilendirilmemis
404	`not_found`	Belge yok, ya da baska bir tenant'a ait
404	`reasoning_not_available`	Belge var ama reasoning graph henuz uretilmedi (temsil yok, `reasoning_graph` katmani bos, ya da belge bu katmandan onceki bir tarihte yuklendi)

Layout ve bounding box'lar

GET /v1/documents/{document_id}/layout

Layout, sayfada neyin nerede oldugunu yakalar — her sayfa icin piksel boyutlarini ve her biri bir bounding box kaplayan tipli bloklarin (tablo, metin, baslik, gorsel, footer, ...) bir listesini. Bu, herhangi bir alintinin ("bu olgu buradan geldi") sadece bir sayfa numarasi yerine kaynak sayfa uzerinde vurgulanmis bir dikdortgen olarak cizilebilmesini saglar.

curl https://api.docsfra.com/v1/documents/d_9c1a2b3c4d5e/layout \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "document_id": "d_9c1a2b3c4d5e",
  "pages": [
    {
      "page": 3,
      "page_size": [1654, 2339],
      "blocks": [
        {
          "type": "title",
          "bbox": [120, 88, 980, 140],
          "text_head": "Yuk Tanimi"
        },
        {
          "type": "table",
          "bbox": [120, 160, 1520, 640],
          "text_head": "Kalem | Adet | Agirlik (kg)"
        },
        {
          "type": "text",
          "bbox": [120, 660, 1520, 900],
          "text_head": "Toplam brut agirlik: 540 kg, 3 kasada paketli."
        }
      ]
    }
  ]
}

page_size, piksel cinsinden [genislik, yukseklik]'tir ve o sayfadaki her bbox ([x1, y1, x2, y2], sol-ust/sag-alt koseler) ayni koordinat sistemindedir — renderer'iniz normalize (0-1) koordinat istiyorsa page_size'a bolun. text_head, blogun metninin kisa (≤80 karakter) bir onizlemesidir; sayfayi yeniden parse etmeden bir blogu bir tablo satirina ya da bir chunk'a eslemek icin kullanislidir. type, table, text, title, image, footer/header degerlerinden biridir (alttaki layout modelinden gelir; kapsayici bir enum degildir).

Layout, en-iyi-caba yan bir katmandir: normal parse'in yaninda (onun yerine degil) calisan ayri bir layout-tespit gecisinden gelir ve yok olabilir — bu katman var olmadan once islenen belgeler icin, ya da layout gecisinin kendisi basarisiz olduysa veya o belge icin yapilandirilmadiysa. Yoklugu, temel belgenin, memory'nin, objects'in, entities'in ya da reasoning katmaninin teslimini hicbir zaman etkilemez.

Bu ayni zamanda evidence.bbox / evidence.page_size alanlarinin, bu sayfada baska yerde gordugunuz evidence nesnelerine (Objects'in tablo evidence'i, Entities'in ve Reasoning graph'in node evidence'i) opsiyonel eklemeler olmasinin nedenidir: bir chunk'in kaynak sayfasinda layout verisi varsa ve bir layout blogu ona eslenebildiyse, evidence'i mevcut page_no'nun yaninda "bbox": [[x1, y1, x2, y2], ...] ve "page_size": [W, H] kazanir — eslesme bulunamazsa (ya da sayfada layout yoksa) evidence duz { "page_no": ... } seklinde kalir.

Hatalar

HTTP	code	Aciklama
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
403	`service_not_enabled`	Key, `extract` modulu icin yetkilendirilmemis
404	`not_found`	Belge yok, ya da baska bir tenant'a ait
404	`layout_not_available`	Belge var ama onun icin layout uretilmedi (en-iyi-caba katman — her belgede olmaz)

Extract (birlesik gorunum)

GET /v1/documents/{document_id}/extract

Memory + objects + entities + reasoning'i tek cagrida birlikte doner — dort katmanin tamamini dort ayri gidip-gelme yapmadan gormek istediginizde kullanislidir.

curl https://api.docsfra.com/v1/documents/d_9c1a2b3c4d5e/extract \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "document_id": "d_9c1a2b3c4d5e",
  "memory": { "title": "Konsimento — INV-001", "...": "..." },
  "objects": { "tables_count": 1, "figures_count": 0, "...": "..." },
  "entities": { "node_count": 2, "edge_count": 1, "...": "..." },
  "reasoning": { "node_count": 2, "edge_count": 1, "...": "..." },
  "schema_version": "0.2-ku",
  "generated": {
    "memory": { "model": "...", "prompt_version": "mem-v1" },
    "structured_objects": { "model": null },
    "entity_graph": { "model": "...", "prompt_version": "ent-v1", "resolver_version": "res-v1" },
    "reasoning_graph": { "model": "...", "prompt_version": "rsn-v1" }
  }
}

Tek-katman uc noktalarindan farkli olarak /extract, tek tek katmanlar eksik olsa bile 200 doner — memory, objects, entities veya reasoning'ten her biri, o katman uretilemediyse ya da henuz calismadiysa bagimsiz olarak null olabilir. Yalnizca belgenin hic temsili olmadiginda 404 doner (orn. AIDR hatti var olmadan once yuklenmis eski bir belge).

Hatalar

HTTP	code	Aciklama
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
403	`service_not_enabled`	Key, `extract` modulu icin yetkilendirilmemis
404	`not_found`	Belge yok, ya da baska bir tenant'a ait
404	`extract_not_available`	Belgenin hic temsili yok (tek tek katmanlarin `null` olmasi 404 degildir — yukariya bkz.)

Artifacts (katalog)

GET /v1/documents/{document_id}/artifacts

Katalog uc noktasi: tek cagri, uygulamanizin bu belge icin ihtiyaci olan her artifact, bir available bayragi ve gercekte nereden cekeceginizi gosteren bir via isaretcisiyle birlikte. Her uc noktayi tek tek yoklamadan bir UI'i ("bu belge icin ne hazir?") suruklemek icin kullanin.

curl https://api.docsfra.com/v1/documents/d_9c1a2b3c4d5e/artifacts \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "document_id": "d_9c1a2b3c4d5e",
  "status": "completed",
  "representation": { "schema_version": "0.2-ku", "status": "ready" },
  "artifacts": {
    "source": { "available": true, "kind": "binary", "via": "GET /v1/jobs/{id}/source" },
    "markdown": { "available": true, "kind": "markdown", "via": "GET /v1/jobs/{id} → result.markdown_url" },
    "structured_markdown": { "available": true, "kind": "markdown", "via": "GET /v1/jobs/{id} → result.structured_url" },
    "canonical_json": { "available": true, "kind": "json", "via": "GET /v1/jobs/{id} → result.json_url" },
    "memory": { "available": true, "kind": "json", "via": "GET /v1/documents/{id}/memory" },
    "knowledge_units": { "available": true, "kind": "index", "count": 42 },
    "structured_objects": { "available": true, "kind": "json", "tables": 1, "figures": 0, "via": "GET /v1/documents/{id}/objects" },
    "entities": { "available": true, "kind": "graph", "nodes": 2, "edges": 1, "via": "GET /v1/documents/{id}/entities" },
    "extract": { "available": true, "kind": "json", "via": "GET /v1/documents/{id}/extract" },
    "embeddings": { "available": true, "kind": "vectors", "model": "text-embedding-3-small", "count": 87 },
    "search": { "available": true, "kind": "api", "via": "GET /v1/search" },
    "ask": { "available": true, "kind": "api", "via": "POST /v1/ask" }
  }
}

available her zaman gercek durumu yansitir (bir ref set edilmis olmasi, bir katmanin bos olmamasi, bir sayacin sifirdan farkli olmasi) — asla sabit bir yetenek bayragi degildir. via bilgi amaclidir ve durumdan bagimsiz olarak ayni string kalir, boylece henuz hazir olmayan artifact'ler icin bile bir baglanti kurabilirsiniz (yalniz available false iken devre disi birakin).

Var olan ama henuz completed olmayan bir belge yine de 200 doner — cogu artifact basitce available: false okur (isleme devam ediyor). Temsili olmayan eski bir belge de representation: null ile birlikte 200 doner ve temsile bagli artifact'ler (memory, structured_objects, entities, extract) kullanilamaz isaretlenir — belgenin kendisi eksik degildir, yalniz bu artifact'ler eksiktir. 404 yalnizca belge gercekten yoksa (ya da baska bir tenant'a aitse) olusur.

Hatalar

HTTP	code	Aciklama
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
403	`service_not_enabled`	Key, `extract` modulu icin yetkilendirilmemis
404	`not_found`	Belge yok, ya da baska bir tenant'a ait

Provenance (denetim izi)

GET /v1/documents/{document_id}/provenance

Her temsil, nasil olusturuldugunun bir denetim izini tasir: hangi uretici hangi adimi calistirdi, hangi model/versiyonu kullandi ve dokundugu her katman icin bir icerik hash'i. Bu uc noktayi, cikarilan bir olgunun nasil ortaya ciktigini kanitlamaniz gerektiginde kullanin — uyumluluk incelemesi, anlasmazlik cozumu ya da ayni belgenin iki calistirmasinin neden farkli sonuc verdigini hata ayiklamak icin.

curl https://api.docsfra.com/v1/documents/d_9c1a2b3c4d5e/provenance \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "document_id": "d_9c1a2b3c4d5e",
  "schema_version": "0.2-ku",
  "status": "ready",
  "producers": {
    "canonical": { "producer": "parse_document", "rules_version": "canon-v1" },
    "memory": { "model": "gpt-4o-mini", "prompt_version": "mem-v1" },
    "entity_graph": { "model": "gpt-4o-mini", "prompt_version": "ent-v1", "resolver_version": "res-v1" }
  },
  "provenance": [
    { "step": "original", "hash": "sha256:1a2b3c...", "at": "2026-03-14T10:21:40Z" },
    { "step": "canonical", "producer": "parse_document", "output_hash": "sha256:4d5e6f...", "at": "2026-03-14T10:21:52Z" },
    { "step": "memory", "producer": "generate_memory", "model": "gpt-4o-mini", "prompt_version": "mem-v1", "output_hash": "sha256:7a8b9c...", "at": "2026-03-14T10:22:03Z" },
    { "step": "knowledge_units", "producer": "ai_index_document", "count": 42, "output_hash": "sha256:0d1e2f...", "at": "2026-03-14T10:22:18Z" },
    { "step": "embeddings", "producer": "embed_chunk_batch", "model": "text-embedding-3-small", "dim": 1536, "at": "2026-03-14T10:22:24Z" }
  ],
  "content_hash": "sha256:c0ffee1234...",
  "input_hash": "sha256:1a2b3c..."
}

Her provenance[] girdisi yalnizca-ekleme (append-only) mantigiyla calisir — adimlar asla yerinde yeniden yazilmaz, yeni katmanlar uretildikce yalnizca eklenir. Bir adim yeniden calisirsa (orn. belge yeniden islenirse), onceki temsil degistirilmez, yerine yenisi superseded olarak isaretlenir; boylece onun provenance izi bozulmadan kendi basina incelenebilir kalir. Temsili olmayan bir belge 404 provenance_not_available doner.

Hatalar

HTTP	code	Aciklama
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
403	`service_not_enabled`	Key, `extract` modulu icin yetkilendirilmemis
404	`not_found`	Belge yok, ya da baska bir tenant'a ait
404	`provenance_not_available`	Belge var ama henuz temsili yok

Determinizm ve yeniden-uretilebilirlik

Docsfra, her katmanin arkasindaki uretici versiyonunu sabitler (pinler), boylece belirli bir girdi her zaman yeniden-uretilebilir bir cikti ile eslesir:

canon-v1 — sayfa-basi markdown'i tek bir siralanmis belgeye ceviren canonicalization kurallari (sayfa isaretleyicileri, satir-sonu normalizasyonu, bosluk sikistirma). LLM yok: ayni sayfalar her zaman ayni markdown'a ve ayni hash'e canonicalize edilir.
ctx-v2 — knowledge unit'leri ureten chunk'lama/baglam kurallari.
mem-v1 — memory (kimlik karti) katmaninin arkasindaki prompt versiyonu.
ent-v1 — entity graph katmaninin arkasindaki prompt versiyonu.

Bu versiyon string'leri, yukarida producers.*.rules_version / producers.*.prompt_version alaninda (ve /extract'in generated blogunda) gordugunuz seylerdir. Bir temsil, olusturulduktan sonra degismezdir: her zaman uretildigi andaki sabitlenmis versiyonlari yansitir. Docsfra daha sonra bir uretidiyi iyilestirirse (orn. yeni bir mem-v2 promptu), mevcut temsiller kendi orijinal versiyon etiketlerini korur — bir belgeyi yeniden islemek yeni bir temsil uretir (eskisi superseded olarak isaretlenir), asla sessiz bir yerinde yeniden-yazma olmaz. content_hash, saf olarak katman iceriginden turetilir (canonical metin, memory JSON, knowledge unit metni, entity graph); yani yalnizca ve yalnizca alttaki icerik degistiginde degisir — bir pointer ya da zaman damgasi degildir.

Notlar

Bu bolumdeki tum uc noktalar olcumsuzdur — cikarim sonuclarini okumak, cagri hacmi ne olursa olsun kredi dusurmez. Hepsi ayni extract modul entitlement'ini paylasir, yani extract icin yetkilendirilmis bir key hepsini cagirabilir; search ve ask ayri yetkilendirilir ve ayri faturalandirilir (bkz. Semantik Arama ve Soru-Cevap (RAG)).