Jaka jest latencja wywołania dla typowego dokumentu?

p50 to około 600 ms dla sprawdzenia 500 słów względem zaindeksowanego korpusu; p95 to około 1,8 s. Po włączeniu Layer-W (weryfikacja na żywo w internecie) należy doliczyć około 2 s — to obejmuje zapytania do Google i Brave. Długie dokumenty (przewidywany czas powyżej 8 s) zwracają check_id od razu i wywołują webhook po zakończeniu sprawdzania.

Jak rozliczane są wywołania API?

Jedno płatne wywołanie na każde /v1/checks, niezależnie od wielkości dokumentu aż do limitu słów (1 500 słów Pro, 50 000 Premium, indywidualnie Enterprise). Idempotentne retry z tym samym Idempotency-Key + body w ciągu 24h nie liczą się ponownie. Odczyty /v1/checks/{id} i dodatkowe wywołania przez SDK — bez opłat.

Czy mogę hostować API u siebie?

Tak — github.com/NoplagLabs/noplag-engine to ta sama referencyjna implementacja na licencji Apache-2.0, która działa na engine.noplag.app. Polecenie docker compose up uruchamia lokalny endpoint /v1/checks. W chmurze dostępny jest zarządzany korpus oraz klucze API do Google/Brave; do pełnego self-hostingu trzeba użyć własnych kluczy.

Czy naprawdę mogę zaufać nagłówkowi retry limitu?

Na 429 zwracamy Retry-After w sekundach. Nagłówki X-RateLimit-* w każdej odpowiedzi — można wyprzedzić limit, sprawdzając X-RateLimit-Remaining zamiast czekać na 429. Obie wartości są dokładne, nie zmieniają się po wdrożeniach.

Jaka jest częstotliwość wydawania SDK?

SDK dla Pythona i Node generują się automatycznie z openapi.yaml na każdy tag silnika. Nowe wersje silnika (v0.x → v0.y) dostają SDK tego samego dnia. Poprawki wydawane w tym samym tygodniu. Oba SDK trzymają semver; API zmienia się tylko przy /v1 → /v2.

Co jeśli korpus zmieni się w środku miesiąca?

Każde sprawdzenie ma X-Engine-Commit + timestamp korpusu. Powtórzenie starego sprawdzenia na nowym korpusie to jeden parametr (?corpus_snapshot=…). Oryginalny raport zostaje z oryginalnym snapshotem — nie zmieniamy wstecznie wyników podobieństwa.

Jak testować bez zużywania limitu miesięcznego?

Klucze testowe (nplg_test_…) trafiają do sandboxa: całość API, nic nie jest zapisywane, nie wlicza się do miesięcznych limitów ani limitów wywołań. Webhooki z sandboxa też — testy integracyjne są bez kosztów.

Jak najlepiej zrobić masowe sprawdzanie?

Wysyłać równolegle do limitu — nie ma endpointu batch (500-dokumentowy batch zatrzymany na 312. to gorzej niż 500 niezależnych wywołań). Do dużych pipeline’ów: połącz API z webhookiem — submit, natychmiastowy check_id, kolejne 200 zadań, wyniki przyjmować asynchronicznie.

Czy mogę sprawdzić tylko własne foldery?

Tak — corpora: [] plus folder_id w body dopasowuje tylko do własnych folderów. Można połączyć z corpora: ["academic"], by sprawdzać “tylko academic + własne foldery”. Ustawiane per wywołanie, bez osobnej taryfy.

Co się zmienia przy EU-residency lub instalacji lokalnej?

Tier Enterprise to osobny endpoint w UE (api.eu.noplag.com) z takim samym OpenAPI, więc dane osobowe zostają w EOG. Albo własny hosting referencyjnej implementacji w prywatnej sieci — ten sam silnik, ten sam kontrakt /v1, nic nie wychodzi na zewnątrz. (Przechodzimy na model open-core; formalne atesty typu SOC 2 są na roadmapie, aktualnie jeszcze nie — oferujemy za to audytowalny silnik.)

RESTSpecyfikacja OpenAPI 3.0 · SDK dla Python + Node · v0.4.2

Antyplagiat API REST i OpenAPI 3.0

REST endpoint do sprawdzania plagiatów + detekcji AI. Specyfikacja OpenAPI 3.0, SDK dla Pythona i Node, referencyjna implementacja Apache 2.0. Od pierwszego curl po automatyzację z webhook — ten sam silnik co na noplag.com.

REST · OpenAPI 3.0SDK Python + NodeReferencja Apache 2.0

PIERWSZE WYWOŁANIE

Od zera do wyniku podobieństwa jednym curl.

POST tekstu, zwrot ocenionych przedziałów. Nie wymaga SDK, nie wymaga kompilacji, bez własnych formatów na drucie.

ŻĄDANIE · bashKopiuj

$ 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"    }'

ODPOWIEDŹ · 200 OK · application/jsonKopiuj

{  "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

Cztery endpointy. Jeden kontrakt. Wersjonowanie w URL.

Ta sama specyfikacja OpenAPI 3.0 znajduje się w repozytorium open source oraz na engine.noplag.app. SDK są generowane ponownie na podstawie tej specyfikacji przy każdej oznaczonej wersji.

POST/v1/checksWyślij zadanieSynchronicznie do 8s; powyżej callback webhookiem. Wymagany Idempotency-Key.

GET/v1/checks/{id}Pobierz sprawdzenieZwraca stan najnowszego raportu. Streamowanie przedziałów przez Accept: text/event-stream.

GET/v1/sources/{id}Podejrzyj źródłoZwraca dopasowane źródło po ID — pełne URL, data snapshotu, źródło cache lub live.

POST/v1/foldersZarządzaj folderamiTwórz / listuj / przenoś sprawdzenia. Dopasowywanie do prywatnych dokumentów ograniczone do folderu.

POST/v1/webhooksZarejestruj webhookDostawy podpisywane HMAC; wykładniczy retry przez 24h; powtórz dowolną dostawę z panelu.

Pełna dokumentacja pod api./docsopenapi.yaml

AUTORYZACJA + LIMITY

Tokeny Bearer. Klucze idempotencyjne. Szczere nagłówki limitów.

Bez udziwnień. Standard HTTP — podtrzymujemy, żeby Państwa middleware retry działały.

UWIERZYTELNIANIE

Tokeny Bearer. Jeden nagłówek, bez podpisywania.

Utwórz kluczDashboard → Ustawienia → API. Klucze zakresowe (odczyt / zapis / admin), rotacja w dwa kliknięcia.

Przekaż w każdym wywołaniuAuthorization: Bearer nplg_live_…. Klucze testowe (nplg_test_) trafiają do sandboxa, który nigdy nie zapisuje podanych danych.

Dodaj Idempotency-Key w POSTDowolny UUID. Ten sam klucz + body zwraca cache’owaną odpowiedź przez 24h, więc retry bez podwójnych opłat czy duplikacji.

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

LIMITY

Na klucz, na minutę. Nagłówki mówią dokładnie, gdzie Państwo są.

TIERREQ/MINMIESIĘCZNIEBURST

Free10100 / mies.20

Pro601 000 / mies.120

Premium30010 000 / mies.600

EnterpriseIndywidualnieUstalaneIndywidualnie

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

SDK

Dwa SDK. Generowane z tej samej specyfikacji OpenAPI 3.0.

Python + Node wydawane przy każdej tagowanej wersji silnika. Inne języki (Go, Ruby, Java) generują z openapi.yaml — PR od społeczności mile widziane.

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,});

<200mslatencja p95

99,95%dostępność SLA

3regiony (US/EU/AP)

OAPI 3format specyfikacji

Apache 2.0referencyjna impl.

WEBHOOKI

Długie sprawdzenia oddzwaniają. Retry bez utraty głowy.

Cztery typy zdarzeń. JSON jako ciało. Podpis HMAC-SHA256 w nagłówku.

check.completedRaport gotowy · pełny JSON raportu w treści

check.failedTrwała porażka · kod błędu + porada retry

check.progressCzęściowy stan · dotychczas wykryte źródła

folder.sharedFolder udostępniony współpracownikowi lub zewnętrznemu audytorowi

Wykładnicze retry przez 24 godziny. Do powtórzenia z panelu.

Krzywa retry5s, 30s, 2m, 10m, 1h, 6h, 24h — potem dead-letter

Timeout10s połączenie, 30s na próbę

Kryterium sukcesuOdpowiedź HTTP 2xx w czasie; respektujemy przekierowania

UI replayWybierz dostawę z panelu i wywołaj pod nowy URL

Sprawdź podpis. Odrzucaj, jeśli się nie zgadza.

Każda dostawa zawiera X-Noplag-Signature: t=<unix>,v1=<hex>. Oblicz HMAC-SHA256 z timestampu + body swoim sekretem webhooka i porównaj w stałym czasie.

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

ZASADY DEV

Działamy wg HTTP. To cała dokumentacja API.

POST jest idempotentny. Wersja w URL. Błędy mówią, co robić dalej. Nagłówki pokazują miejsce w oknie limitu. Paginacja po cursor, nie offset. Timestamps UTC ISO 8601. Bez własnego HATEOAS, nie zwracamy 200 OK na błędach, nie wymagamy OAuth dla połączeń serwer-serwer. Dokumentacja API to RFC 9110 i OpenAPI 3.0 — nie ma “drogi Noplag” do nauki.

Zobacz założenia projektu

ZAŁOŻENIA

IDEMPTen sam Idempotency-Key + body w ciągu 24h daje cache’owaną odpowiedź. W razie problemu z siecią — ten sam klucz, bez podwójnego liczenia, bez duplikatu.

VERWersja główna w URL (/v1, /v2). Zmiany niekompatybilne oznaczają nową ścieżkę — poprzednia wspierana jeszcze 12 miesięcy.

ERRRFC 9457 problem-details JSON dla każdego 4xx/5xx. type, title, detail, instance plus noplag.retry_strategy.

PAGNa każdej liście paginacja przez cursor. ?limit=100&cursor=… z next_cursor w zwrotce. Brak niespodzianek z offset w połowie strony przy nowym wierszu.

OBSOdpowiedzi zawierają X-Engine-Commit, X-Request-Id oraz Server-Timing. Replikacja dowolnego check po ID; raport odsyła do wersji silnika.

OPENReferencyjna implementacja Apache 2.0 dostępna na github.com/NoplagLabs/noplag-engine. Możesz uruchomić ją na własnej infrastrukturze, jeśli Twoje dane nie mogą opuszczać sieci — ten sam interfejs API.

FAQ

Pytania, które integratorzy faktycznie zadają.

Jaka jest latencja wywołania dla typowego dokumentu?: p50 to około 600 ms dla sprawdzenia 500 słów względem zaindeksowanego korpusu; p95 to około 1,8 s. Po włączeniu Layer-W (weryfikacja na żywo w internecie) należy doliczyć około 2 s — to obejmuje zapytania do Google i Brave. Długie dokumenty (przewidywany czas powyżej 8 s) zwracają check_id od razu i wywołują webhook po zakończeniu sprawdzania.
Jak rozliczane są wywołania API?: Jedno płatne wywołanie na każde /v1/checks, niezależnie od wielkości dokumentu aż do limitu słów (1 500 słów Pro, 50 000 Premium, indywidualnie Enterprise). Idempotentne retry z tym samym Idempotency-Key + body w ciągu 24h nie liczą się ponownie. Odczyty /v1/checks/{id} i dodatkowe wywołania przez SDK — bez opłat.
Czy mogę hostować API u siebie?: Tak — github.com/NoplagLabs/noplag-engine to ta sama referencyjna implementacja na licencji Apache-2.0, która działa na engine.noplag.app. Polecenie docker compose up uruchamia lokalny endpoint /v1/checks. W chmurze dostępny jest zarządzany korpus oraz klucze API do Google/Brave; do pełnego self-hostingu trzeba użyć własnych kluczy.
Czy naprawdę mogę zaufać nagłówkowi retry limitu?: Na 429 zwracamy Retry-After w sekundach. Nagłówki X-RateLimit-* w każdej odpowiedzi — można wyprzedzić limit, sprawdzając X-RateLimit-Remaining zamiast czekać na 429. Obie wartości są dokładne, nie zmieniają się po wdrożeniach.
Jaka jest częstotliwość wydawania SDK?: SDK dla Pythona i Node generują się automatycznie z openapi.yaml na każdy tag silnika. Nowe wersje silnika (v0.x → v0.y) dostają SDK tego samego dnia. Poprawki wydawane w tym samym tygodniu. Oba SDK trzymają semver; API zmienia się tylko przy /v1 → /v2.
Co jeśli korpus zmieni się w środku miesiąca?: Każde sprawdzenie ma X-Engine-Commit + timestamp korpusu. Powtórzenie starego sprawdzenia na nowym korpusie to jeden parametr (?corpus_snapshot=…). Oryginalny raport zostaje z oryginalnym snapshotem — nie zmieniamy wstecznie wyników podobieństwa.
Jak testować bez zużywania limitu miesięcznego?: Klucze testowe (nplg_test_…) trafiają do sandboxa: całość API, nic nie jest zapisywane, nie wlicza się do miesięcznych limitów ani limitów wywołań. Webhooki z sandboxa też — testy integracyjne są bez kosztów.
Jak najlepiej zrobić masowe sprawdzanie?: Wysyłać równolegle do limitu — nie ma endpointu batch (500-dokumentowy batch zatrzymany na 312. to gorzej niż 500 niezależnych wywołań). Do dużych pipeline’ów: połącz API z webhookiem — submit, natychmiastowy check_id, kolejne 200 zadań, wyniki przyjmować asynchronicznie.
Czy mogę sprawdzić tylko własne foldery?: Tak — corpora: [] plus folder_id w body dopasowuje tylko do własnych folderów. Można połączyć z corpora: ["academic"], by sprawdzać “tylko academic + własne foldery”. Ustawiane per wywołanie, bez osobnej taryfy.
Co się zmienia przy EU-residency lub instalacji lokalnej?: Tier Enterprise to osobny endpoint w UE (api.eu.noplag.com) z takim samym OpenAPI, więc dane osobowe zostają w EOG. Albo własny hosting referencyjnej implementacji w prywatnej sieci — ten sam silnik, ten sam kontrakt /v1, nic nie wychodzi na zewnątrz. (Przechodzimy na model open-core; formalne atesty typu SOC 2 są na roadmapie, aktualnie jeszcze nie — oferujemy za to audytowalny silnik.)

Uzyskaj klucz API. Wykonaj pierwsze wywołanie.

Wersja testowa to 100 wywołań API. Tier Pro 23 USD/mies. za 1 000. Referencyjna implementacja Apache 2.0 gdy wolą Państwo trzymać ruch w sieci.

Uzyskaj klucz API Przeczytaj specyfikację OpenAPI