Jaká je latence běžného volání?

p50 přibližně 600 ms pro kontrolu 500 slov proti indexovanému korpusu; p95 asi 1,8 s. Při zapnuté funkci Layer W (ověření na webu v reálném čase) připočtěte asi 2 s — probíhá dotazování přes Google + Brave. U dlouhých dokumentů (očekávaná doba zpracování nad 8 s) se vrací check_id ihned a výsledek je zaslán zpět přes webhook.

Jak se účtuje API provoz?

Jedna zpoplatněná volání /v1/checks za každé podání, bez ohledu na délku dokumentu do limitu (1500 slov Pro, 50 000 Premium, Enterprise vlastní). Retry se stejným Idempotency-Key a tělem do 24h se nepočítají znovu. /v1/checks/{id} a vedlejší SDK volání jsou zdarma.

Lze API spustit samostatně?

Ano — github.com/NoplagLabs/noplag-engine je stejná referenční implementace pod licencí Apache-2.0, která běží na engine.noplag.app. Pomocí docker compose up získáte lokální endpoint /v1/checks. Cloudová verze přidává spravovaný korpus a API klíče pro Google/Brave; pro plně self-hostované řešení si klíče zajistěte sami.

Vrací se rate-limit retry hlavička, které lze věřit?

Na 429 vždy vracíme Retry-After v sekundách. Hlavičky X-RateLimit-* jsou na každé odpovědi — lze je použít pro předběžné omezení (throttling), nečekat až na 429. Obojí je přesné, nezávisí na deployi.

Jak často vychází SDK?

Python i Node SDK se regenerují z openapi.yaml při každém tagu enginu. Hlavní vydání enginu (v0.x → v0.y) dostane SDK týž den. Patche do týdne. SDK drží semver; API se láme jen na /v1 → /v2.

Co když se změní korpus v průběhu měsíce?

Každá kontrola má X-Engine-Commit a čas snapshotu korpusu. Zopakování původní kontroly na novém korpusu je jeden query parametr (?corpus_snapshot=…). Originál reportu se nemění — nikdy tiše neupravujeme již vydané skóre.

Jak testovat, aniž bych vyčerpal měsíční limit?

Testovací klíče (nplg_test_…) jdou do sandboxu: celé API, nic se neukládá, nepočítá se do limitu. Webhooky střílí i ze sandboxu, takže end-to-end testy nic nestojí.

Jak správně udělat hromadné kontroly?

Posílejte paralelně podle svého rate-limit stropu — dávkový endpoint schválně neexistuje (500 dokumentů v dávce, selže 312., horší než 500 samostatných volání). Pro velké dávky použijte webhooks: odeslat, dostat check_id hned, rozběhnout další vlny, výsledek přijde asynchronně.

Lze omezit kontrolu jen na mé složky?

Ano — corpora: [] a folder_id v těle žádosti porovnávají jen privátní složky uživatele. Můžete kombinovat s corpora: ["academic"] pro „jen akademické + mé složky“. Nastavuje se po volání — není potřeba zvláštní tarif.

Co když potřebuji EU lokalizaci nebo on-premise řešení?

Enterprise tarif přidá dedikovaný endpoint s EU lokalizací (api.eu.noplag.com), stejné OpenAPI, data zůstanou v EHP. Nebo referenční implementaci hostujte jen ve vlastní síti — stejný engine, stejná /v1 smlouva, nic neodchází ven. (Firma se relaunchuje jako open-core; SOC 2 teprve chystáme — audituje se engine, ne compliance standardy.)

RESTOpenAPI 3.0 spec · Python + Node SDK · v0.4.2

Kontrola plagiátů API pro vývojáře

REST endpoint pro detekci plagiátů a AI. OpenAPI 3.0, Python i Node SDK, referenční implementace Apache 2.0. Od prvního curlu po webhookovou integraci — stejný engine jako na noplag.com.

REST · OpenAPI 3.0Python + Node SDKReferenční impl Apache 2.0

PRVNÍ VOLÁNÍ

Od nuly k podobnostnímu skóre v jednom curlu.

Pošlete POST s textem, dostanete zpět intervaly se skóre. SDK není potřeba, žádný compile krok, žádný proprietární formát.

POŽADAVEK · bashKopírovat

$ curl https://engine.noplag.app/v1/checks \    -H "Authorization: Bearer $NOPLAG_KEY" \    -H "Content-Type: application/json" \    -H "Idempotency-Key: $(uuidgen)" \    -d '{        "text": "The rain in Spain falls...",        "corpora": ["web", "academic"],        "ai_detection": true,        "webhook_url": "https://you.example/hook"    }'

ODPOVĚĎ · 200 OK · application/jsonKopírovat

{  "check_id": "chk_01HX9R2Y4...",  "status": "complete",  "similarity_pct": 23.4,  "ai_score": 0.08,  "engine_commit": "v0.4.2",  "sources": [    { "url": "https://en.wikipedia...",      "matched_chars": 142,      "similarity_pct": 100.0 }  ]}

ENDPOINTY

Čtyři endpointy. Jedna smlouva. Verza v URL.

Stejná OpenAPI 3.0 specifikace je dostupná v open source repozitáři i na engine.noplag.app. SDK se z ní generují při každém označeném vydání.

POST/v1/checksOdeslat kontroluSynchronní do 8s; nad 8s pomocí webhooku. Vyžaduje Idempotency-Key.

GET/v1/checks/{id}Získat kontroluVrací aktuální stav reportu. Intervaly dostupné přes Accept: text/event-stream.

GET/v1/sources/{id}Inspekce zdrojePodle ID vrací detail nalezeného zdroje — URL, datum snapshotu, zda z cache či online.

POST/v1/foldersSpráva složekVytvářejte/listujte/přesouvejte kontroly. Omezte porovnávání na privátní dokumenty ve složce.

POST/v1/webhooksRegistrovat webhookDodávky podepsané HMAC; opakování s exponenciální prodlevou po dobu 24 h; opětovné odeslání z dashboardu.

Kompletní dokumentace na api./docsopenapi.yaml

AUTH + LIMITY

Bearer tokeny. Idempotenční klíče. Upřímné rate-limit hlavičky.

Nic speciálního. Standardní HTTP postupy — dodržujeme je, takže vaše retry middleware funguje bez úprav.

OVĚŘENÍ

Bearer tokeny. Jedna hlavička, žádný podpisový tanec.

Vytvořte klíčDashboard → Nastavení → API. Klíče mají rozsah (čtení/pis, správa) a lze je otáčet dvěma kliky.

Posílejte klíč při každém voláníAuthorization: Bearer nplg_live_…. Testovací klíče (nplg_test_) jdou do sandboxu — nic neukládají.

Přidejte Idempotency-Key na POSTMůže to být libovolné UUID. Stejný klíč + tělo = 24 hodin stejná odpověď, takže retry zdarma — nevznikají duplicitní kontroly ani dvojí platby.

Authorization: Bearer nplg_live_a82f...Idempotency-Key: 0e8f9c44-...

LIMITY

Na klíč a za minutu. Hlavičky ukazují přesně, kde jste.

TARIFPOŽ/MINMĚSÍČNÍBURST

Free10100 / měs.20

Pro601 000 / měs.120

Premium30010 000 / měs.600

EnterpriseDle domluvyDle domluvyDle domluvy

X-RateLimit-Limit: 60X-RateLimit-Remaining: 41X-RateLimit-Reset: 1747920480Retry-After: 19  (only on 429)

SDK

Dvě SDK. Generovaná ze stejné OpenAPI 3.0 specifikace.

Python a Node SDK vychází při každém tagu enginu. Další jazyky (Go, Ruby, Java) lze generovat z openapi.yaml — pull requesty od komunity vítány.

PYTHONpip install noplag

from noplag import Noplag client = Noplag(api_key="nplg_live_…") report = client.checks.create(    text="...",    corpora=["web", "academic"],    ai_detection=True,) print(report.similarity_pct)

NODEnpm i @noplag/sdk

import Noplag from "@noplag/sdk"; const client = new Noplag({    apiKey: process.env.NOPLAG_KEY,}); const report = await client.checks.create({    text: "...",    corpora: ["web", "academic"],    aiDetection: true,});

<200msp95 latence

99,95%dostupnost SLA

3regiony (US/EU/AP)

OAPI 3specifikace

Apache 2.0referenční impl

WEBHOOKY

Dlouhé kontroly zavolají zpátky. Retry, které vás nezblázní.

Čtyři typy událostí. JSON tělo. HMAC-SHA256 podpis v hlavičce.

check.completedReport připraven · obsahuje celé JSON

check.failedTrvalá chyba · kód + rady k retry

check.progressPrůběžný stav · dosud nalezené zdroje

folder.sharedPřístup ke složce udělen kolegovi nebo externímu auditorovi

Exponenciální retry 24 hodin. Zázn. lze přehrát z dashboardu.

Retry křivka5s, 30s, 2m, 10m, 1h, 6h, 24h — pak dead-letter

Timeout10s na spojení, 30s celkem na pokus

Kritérium úspěchuHTTP 2xx odpověď v limitu; následujeme redirecty

Replay UIVyberte pokus v dashboardu a odešlete znovu na jinou URL

Ověřte podpis. Odhazujte vše, co nesedí.

Každá doručenka má X-Noplag-Signature: t=<unix>,v1=<hex>. Spočtěte HMAC-SHA256 přes timestamp + tělo s vaším webhook tajemstvím, porovnávejte v konstantním čase.

h = hmac.new(secret,    f"{t}.{body}".encode(),    hashlib.sha256).hexdigest()assert hmac.compare_digest(h, v1)

DEV PRINCIPY

Držíme se HTTP. To je celé API zadání.

POST je idempotentní. Verze v URL. Chybové zprávy říkají, co dělat dál. Hlavičky ukazují přesně, kde jste v limitu. Paginace přes kurzor, ne offset. Timestamps v UTC ISO 8601. Nemáme vlastní HATEOAS, nevracíme 200 OK u chyb, a nevyžadujeme OAuth pro server-server hovory. Dokumentace API je RFC 9110 a OpenAPI 3.0 — není žádná zvláštní „Noplag cesta“, kterou byste museli chápat.

Přečtěte si poznámky k návrhu

OMEZENÍ NÁVRHU

IDEMPStejný Idempotency-Key a tělo za 24 h = stejná odpověď. Síťový retry se stejným klíčem nepřepočte ani nedvojí platbu.

VERHlavní verze v URL (/v1, /v2). Breaking změny vždy vedou k nové cestě – starší verze min. 12 měsíců od oznámení.

ERRKaždá 4xx/5xx odpověď vrací problem-details JSON podle RFC 9457. type, title, detail, instance, plus noplag.retry_strategy hint.

PAGKaždý list endpoint je paginovaný kurzorem. ?limit=100&cursor=… vrací next_cursor v těle. Žádné offsetové pasti na stránce 47, když přijde nový řádek.

OBSOdpověď obsahuje X-Engine-Commit, X-Request-Id a Server-Timing za každý krok. Každou kontrolu lze přehrát podle ID; report je vázán ke konkrétní engine verzi.

OPENReferenční implementace Apache 2.0 na github.com/NoplagLabs/noplag-engine. Pokud vaše data nesmí opustit vaši síť, můžete si službu nasadit sami — API je stejné.

FAQ

Skutečné dotazy našich integračních inženýrů.

Jaká je latence běžného volání?: p50 přibližně 600 ms pro kontrolu 500 slov proti indexovanému korpusu; p95 asi 1,8 s. Při zapnuté funkci Layer W (ověření na webu v reálném čase) připočtěte asi 2 s — probíhá dotazování přes Google + Brave. U dlouhých dokumentů (očekávaná doba zpracování nad 8 s) se vrací check_id ihned a výsledek je zaslán zpět přes webhook.
Jak se účtuje API provoz?: Jedna zpoplatněná volání /v1/checks za každé podání, bez ohledu na délku dokumentu do limitu (1500 slov Pro, 50 000 Premium, Enterprise vlastní). Retry se stejným Idempotency-Key a tělem do 24h se nepočítají znovu. /v1/checks/{id} a vedlejší SDK volání jsou zdarma.
Lze API spustit samostatně?: Ano — github.com/NoplagLabs/noplag-engine je stejná referenční implementace pod licencí Apache-2.0, která běží na engine.noplag.app. Pomocí docker compose up získáte lokální endpoint /v1/checks. Cloudová verze přidává spravovaný korpus a API klíče pro Google/Brave; pro plně self-hostované řešení si klíče zajistěte sami.
Vrací se rate-limit retry hlavička, které lze věřit?: Na 429 vždy vracíme Retry-After v sekundách. Hlavičky X-RateLimit-* jsou na každé odpovědi — lze je použít pro předběžné omezení (throttling), nečekat až na 429. Obojí je přesné, nezávisí na deployi.
Jak často vychází SDK?: Python i Node SDK se regenerují z openapi.yaml při každém tagu enginu. Hlavní vydání enginu (v0.x → v0.y) dostane SDK týž den. Patche do týdne. SDK drží semver; API se láme jen na /v1 → /v2.
Co když se změní korpus v průběhu měsíce?: Každá kontrola má X-Engine-Commit a čas snapshotu korpusu. Zopakování původní kontroly na novém korpusu je jeden query parametr (?corpus_snapshot=…). Originál reportu se nemění — nikdy tiše neupravujeme již vydané skóre.
Jak testovat, aniž bych vyčerpal měsíční limit?: Testovací klíče (nplg_test_…) jdou do sandboxu: celé API, nic se neukládá, nepočítá se do limitu. Webhooky střílí i ze sandboxu, takže end-to-end testy nic nestojí.
Jak správně udělat hromadné kontroly?: Posílejte paralelně podle svého rate-limit stropu — dávkový endpoint schválně neexistuje (500 dokumentů v dávce, selže 312., horší než 500 samostatných volání). Pro velké dávky použijte webhooks: odeslat, dostat check_id hned, rozběhnout další vlny, výsledek přijde asynchronně.
Lze omezit kontrolu jen na mé složky?: Ano — corpora: [] a folder_id v těle žádosti porovnávají jen privátní složky uživatele. Můžete kombinovat s corpora: ["academic"] pro „jen akademické + mé složky“. Nastavuje se po volání — není potřeba zvláštní tarif.
Co když potřebuji EU lokalizaci nebo on-premise řešení?: Enterprise tarif přidá dedikovaný endpoint s EU lokalizací (api.eu.noplag.com), stejné OpenAPI, data zůstanou v EHP. Nebo referenční implementaci hostujte jen ve vlastní síti — stejný engine, stejná /v1 smlouva, nic neodchází ven. (Firma se relaunchuje jako open-core; SOC 2 teprve chystáme — audituje se engine, ne compliance standardy.)

Získejte API klíč. Udělejte první volání.

Zkušebních 100 volání zdarma. Pro tarif 23 USD/měsíc za 1 000. Referenční Apache 2.0 implementace, pokud si chcete API provozovat sami.

Získat API klíč Přečtěte si OpenAPI specifikaci