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.
Poslanie dokumentu
Section titled “Poslanie dokumentu”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.
Text (JSON)
Section titled “Text (JSON)”POST /api/v1/documentsAuthorization: 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é),textalebocsv.
Súbor (multipart/form-data)
Section titled “Súbor (multipart/form-data)”POST /api/v1/documentsAuthorization: Bearer kw_live_…Content-Type: multipart/form-data; boundary=…
file=@zmluva.pdf // povinné: samotný súborid=erp-doc-12345 // voliteľné: stabilné ID pre upserttitle=Zmluva 2026/001 // voliteľné: názov záznamufile(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. Bezidajtitlesa 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.
Upsert vs. nový dokument
Section titled “Upsert vs. nový dokument”- S
id: dokument sa uloží pod stabilným názvom odvodeným zid. Opätovné poslanie s tým istýmidprepíš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."}Zoznam dokumentov
Section titled “Zoznam dokumentov”Vypíše dokumenty v priečinku kľúča.
GET /api/v1/documentsAuthorization: Bearer kw_live_…{ "collectionKey": "faktury", "count": 2, "documents": [ { "name": "erp-doc-12345.md", "size": 1024, "uploadedAt": "2026-08-19T10:00:00Z" } ]}Zmazanie dokumentu
Section titled “Zmazanie dokumentu”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.
Limity
Section titled “Limity”- 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. |
Príklady (curl)
Section titled “Príklady (curl)”Text:
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:
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).