Preskočiť na obsah

API: dokumenty (REST)

Tieto verejné endpointy slúžia na to, aby externý systém (ERP, CRM, skript…) spravoval dokumenty v jednom priečinku: posielal ich, vypísal ich zoznam a mazal ich. Autentifikujú sa API kľúčom typu „zápis dokumentov”, ktorý vygenerujete v administrácii, pozri API kľúče.

Kľúč je viazaný na jeden priečinok (typu „dokumenty”). Cieľový priečinok sa určí z kľúča, neposiela sa v tele.

Dokument pošlete jedným z dvoch spôsobov, na ten istý endpoint:

  • text (markdown, čistý text, CSV) ako JSON,
  • súbor (PDF, DOCX, XLSX…) ako multipart/form-data.
POST /api/v1/documents
Authorization: Bearer kw_live_…
Content-Type: application/json
{
"content": "# Zápis z porady\n\nDohodli sme sa, že …",
"id": "erp-doc-12345", // voliteľné: stabilné ID pre upsert
"title": "Zápis z porady", // voliteľné: názov záznamu
"format": "markdown" // voliteľné: markdown | text | csv (predvolené markdown)
}
  • content (povinné): text dokumentu (markdown, čistý text alebo CSV).
  • format (voliteľné): markdown (predvolené), text alebo csv.
POST /api/v1/documents
Authorization: Bearer kw_live_…
Content-Type: multipart/form-data; boundary=…
file=@zmluva.pdf // povinné: samotný súbor
id=erp-doc-12345 // voliteľné: stabilné ID pre upsert
title=Zmluva 2026/001 // voliteľné: názov záznamu
  • file (povinné): jeden súbor, najviac 100 MB. Súbor sa uloží vo svojom formáte a jeho text sa spracuje rovnako ako pri nahratí v Knižnici.
  • id, title (voliteľné): rovnaký význam ako pri texte. Bez id aj title sa názov odvodí z názvu poslaného súboru.

Podporované formáty:

Typ Prípony
Dokumenty .pdf, .docx, .pptx, .epub, .html, .eml
Tabuľky .xlsx, .xlsm, .csv, .tsv
Text a dáta .txt, .md, .mdx, .json, .xml, .yml, .yaml, .sql, .log, .conf
Obrázky .png, .jpg, .jpeg, .webp

Staré formáty Office (.doc, .xls, .ppt) a archívy (.zip) sa neprijímajú, vrátia 415. Súbor uložte ako .docx / .xlsx / .pptx, archív rozbaľte a súbory pošlite jednotlivo.

  • S id: dokument sa uloží pod stabilným názvom odvodeným z id. Opätovné poslanie s tým istým id prepíše predchádzajúcu verziu (upsert), aj keď má iný formát (napr. text nahradíte súborom PDF). Ideálne pre priebežnú synchronizáciu. Predchádzajúca verzia zmizne z vyhľadávania niekoľko minút po poslaní poslednej zmeny do priečinka; pri hromadnej aktualizácii sa môžu obe verzie krátko objaviť naraz.
  • Bez id: každé volanie pridá nový dokument.

Indexovanie prebieha asynchrónne, dokument je vyhľadateľný krátko po nahratí. Úspech vráti 202 Accepted:

{
"ok": true,
"document": { "name": "erp-doc-12345.md", "upserted": true },
"collectionKey": "faktury",
"note": "Indexing runs asynchronously; the document becomes searchable shortly."
}

Vypíše dokumenty v priečinku kľúča.

GET /api/v1/documents
Authorization: Bearer kw_live_…
{
"collectionKey": "faktury",
"count": 2,
"documents": [
{ "name": "erp-doc-12345.md", "size": 1024, "uploadedAt": "2026-08-19T10:00:00Z" }
]
}

Zmaže dokument poslaný cez API, podľa jeho id.

DELETE /api/v1/documents/{id}
Authorization: Bearer kw_live_…
{ "ok": true, "deleted": ["erp-doc-12345.md"] }

Zmazanie sa týka len dokumentov nahraných cez API (podľa konvencie názvu z id), takže kľúč nezmaže súbory, ktoré do priečinka nahral človek. Ak sa dokument s daným id nenájde, vráti 404.

  • Text (JSON): max 1 MB.
  • Súbor (multipart): max 100 MB, jeden súbor na volanie.
  • Rate limit na kľúč: zápis/mazanie 60/min, výpis 120/min. Pri prekročení 429 rate_limited.
Status Kód / dôvod
401 Chýbajúci, neplatný, zneplatnený alebo expirovaný kľúč.
403 Kľúč nie je typu „zápis dokumentov”.
403 Balík neobsahuje API (od Business).
400 Neplatné JSON telo alebo prázdny content; pri súbore chýbajúce pole file alebo prázdny súbor.
404 Dokument s daným id sa v priečinku nenašiel (pri DELETE).
413 Text je väčší ako 1 MB alebo súbor väčší ako 100 MB.
415 Nepodporovaný formát súboru.
409 Cieľový priečinok sa nedá zapisovať (spravovaný / len na čítanie).
429 rate_limited: prekročený rate limit na kľúč.
502 Operácia nad indexom zlyhala, skúste znova.

Text:

Terminal window
curl -X POST https://<vasa-instancia>/api/v1/documents \
-H "Authorization: Bearer kw_live_…" \
-H "Content-Type: application/json" \
-d '{
"id": "erp-doc-12345",
"title": "Zápis z porady",
"content": "# Zápis z porady\n\nDohodli sme sa, že …"
}'

Súbor:

Terminal window
curl -X POST https://<vasa-instancia>/api/v1/documents \
-H "Authorization: Bearer kw_live_…" \
-F "file=@zmluva.pdf" \
-F "id=erp-doc-12345" \
-F "title=Zmluva 2026/001"

Hlavičku Content-Type pri súbore nenastavujte ručne, curl -F ju doplní aj s hranicou (boundary).