Care este latența tipică la apel pentru un document normal?

p50 aproximativ 600ms pentru o verificare de 500 de cuvinte față de corpusul indexat; p95 ~1,8s. Se adaugă ~2s când Layer-W (verificare web în timp real) este activat — implică interogări la Google + Brave. Documentele lungi (cu timp estimat peste 8s) returnează imediat un check_id și transmit rezultatul prin webhook.

Cum se măsoară costul pentru API?

Un apel facturat per trimitere /v1/checks, indiferent de dimensiunea documentului până la plafonul de cuvinte (1.500 Pro, 50.000 Premium, Enterprise personalizat). Retry idempotent cu aceeași Idempotency-Key + body în 24h nu dublează costul. Citirile /v1/checks/{id} și apelurile auxiliare SDK sunt gratuite.

Pot rula API-ul self-hosted?

Da — github.com/NoplagLabs/noplag-engine este aceeași implementare de referință Apache-2.0 care rulează la engine.noplag.app. Cu docker compose up obțineți un endpoint local /v1/checks. Varianta cloud adaugă corpusul gestionat + cheile API Google/Brave; pentru self-host complet, folosiți propriile chei.

Există un header de retry rate-limit de încredere?

La 429 răspundem cu Retry-After în secunde. Header-ele X-RateLimit-* apar la fiecare răspuns — puteți pre-throttle bazat pe X-RateLimit-Remaining fără să așteptați un 429. Ambele sunt corecte și stabile la upgrade.

Care e frecvența release-ului pentru SDK-uri?

SDK-urile Python și Node se regenerează automat din openapi.yaml la fiecare tag engine. Release-urile majore engine (v0.x → v0.y) au SDK în aceeași zi. Patch-urile tehnice se livrează în acea săptămână. Ambele SDK-uri respectă semver; API-ul de bază se schimbă doar la /v1 → /v2.

Ce se întâmplă dacă corpusul se schimbă la mijlocul lunii?

Orice check marchează X-Engine-Commit și un timestamp de snapshot corpus. Reluarea unui check vechi pe corpusul actual se face cu un parametru de query (?corpus_snapshot=…). Raportul inițial se păstrează cu snapshotul original — nu modificăm niciodată silențios scorul de similaritate returnat.

Cum testez fără să consum cota lunară?

Cheile de test (nplg_test_…) merg pe un sandbox: toată suprafața API, nu persistă uploadurile, nu afectează limita lunară sau rate-limit-ul. Webhook-urile pornesc și din sandbox, deci testele end-to-end nu costă.

Cum fac bulk check-uri corect?

Trimiteți în paralel până la plafonul rate-limit — nu există endpoint batch (un batch de 500 care eșuează la doc 312 e mai rău decât 500 apeluri independente). Pentru volum mare, folosiți webhooks: trimiteți, primiți check_id imediat, lansați următoarele 200, preluați rezultate pe măsură ce sosesc, indiferent de ordine.

Pot limita check-ul doar la folderele mele?

Da — corpora: [] cu folder_id în body se limitează la foldere private user. Combinați cu corpora: ["academic"] pentru „doar academic + folderele mele”. Per apel; nu există nivel separat de tarifare.

Ce se schimbă dacă vreau rezidență UE sau instalare on-prem?

Enterprise oferă endpoint UE dedicat (api.eu.noplag.com) cu aceeași suprafață OpenAPI, deci datele rămân în EEA. Sau self-host implementarea de referință complet în VPC-ul propriu — același engine, același contract /v1, nimic iese din rețea. (Ne relansăm pe model open-core; atestări formale ca SOC 2 sunt planificate, nu livrate încă — engine-ul auditat e ceea ce oferim acum.)

RESTSpec OpenAPI 3.0 · SDK-uri Python + Node · v0.4.2

Verificare plagiat API pentru integrare rapidă

Endpoint REST gata de integrat pentru detecție de plagiat + AI. Spec OpenAPI 3.0, SDK-uri Python și Node, implementare de referință Apache 2.0. De la primul curl la volum cu webhook — același engine folosit pe noplag.com.

REST · OpenAPI 3.0SDK-uri Python + NodeReferință Apache 2.0

PRIMUL APEL

De la zero la un scor de similaritate dintr-un singur curl.

POST text, primiți intervale notate la retur. Fără SDK, fără compilare, fără format propietar de date.

CERERE · bashCopiați

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

RĂSPUNS · 200 OK · application/jsonCopiați

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

ENDPOINT-URILE

Patru endpoint-uri. Un singur contract. Versiunea în URL.

Aceeași specificație OpenAPI 3.0 se găsește atât în depozitul open source, cât și pe engine.noplag.app. SDK-urile sunt regenerate din aceasta la fiecare versiune marcată.

POST/v1/checksTrimiteți un checkSincron până la 8s; deasupra, callback prin webhook. Idempotency-Key obligatoriu.

GET/v1/checks/{id}Preluați un checkReturnează cel mai recent status al raportului. Intervalele pot fi transmise stream cu Accept: text/event-stream.

GET/v1/sources/{id}Inspectați o sursăRezolvă o sursă identică după ID — URL complet, dată snapshot, cache vs live.

POST/v1/foldersGestionați foldereCreați / listați / mutați check-uri. Limitează matching-ul la documente private per-folder.

POST/v1/webhooksÎnregistrați un webhookLivrări semnate HMAC; retry exponențial pe 24h; re-trimiteți orice livrare din dashboard.

Documentația completă este disponibilă la api./docsopenapi.yaml

AUTENTIFICARE + LIMITĂRI DE RATĂ

Bearer tokens. Idempotency keys. Header-e de rate-limit oneste.

Nimic exotic. Folosim idiomuri HTTP standard — urmate pentru ca middleware-ul existent să funcționeze fără traume.

AUTENTIFICARE

Bearer tokens. Un singur header, fără pași suplimentari.

Creați o cheieDashboard → Settings → API. Cheile au scope (read / write / admin) și pot fi rotite din două clickuri.

Trimiteți la fiecare apelAuthorization: Bearer nplg_live_…. Cheile de test (nplg_test_) merg pe un sandbox care nu persistă trimiterile.

Adăugați Idempotency-Key la POST-uriOrice UUID funcționează. Aceeași cheie + body returnează răspunsul cache timp de 24h; retry fără dublu-cost sau duplicate.

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

RATE LIMITS

Pe cheie, pe minut. Header-ele arată exact unde sunteți.

TIERCERERI/MINLUNARBURST

Free10100 / lună20

Pro601.000 / lună120

Premium30010.000 / lună600

EnterprisePersonalizatNegociatPersonalizat

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

SDK-URILE

Două SDK-uri. Generate din aceeași spec OpenAPI 3.0.

Python + Node apar la fiecare release cu tag pe engine. Alte limbi (Go, Ruby, Java) generate din openapi.yaml — PR-uri din comunitate binevenite.

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

<200mslatenta p95

99,95%SLA uptime

3regiuni (US/EU/AP)

OAPI 3format spec

Apache 2.0implementare de referință

WEBHOOKS

Check-urile de durată lungă vă apelează ei. Cu retry-uri fără dureri de cap.

Patru tipuri de evenimente. Body JSON. Semnătură HMAC-SHA256 în header.

check.completedRaport gata · include tot JSON-ul raportului

check.failedEșec permanent · conține cod eroare + recomandare de retry

check.progressProgres intermediar · surse rezolvate până acum

folder.sharedAcces folder acordat unui coleg sau auditor extern

Retry exponențial pe 24 ore. Rejucabil din dashboard.

Curbă retry5s, 30s, 2m, 10m, 1h, 6h, 24h — apoi dead-letter

Timeout10s conectare, 30s total per încercare

Criterii de succesRăspuns HTTP 2xx în fereastră; urmăm redirecționări

Replay UISelectați orice livrare din dashboard și relansați către alt URL

Verificați semnătura. Respingeți orice nu corespunde.

Fiecare livrare are X-Noplag-Signature: t=<unix>,v1=<hex>. Calculați HMAC-SHA256 peste timestamp + body folosind secretul webhook și comparație în timp constant.

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

PRINCIPII DEV

Urmăm HTTP. Acesta este intregul design al API-ului.

POST-urile sunt idempotente. Versiunea apare în URL. Erorile spun ce urmează de făcut. Header-ele arată exact unde sunteți față de limita de rată. Paginare prin cursor, nu offset. Data/timp în UTC ISO 8601. Nu avem dialect HATEOAS personalizat, nu returnăm 200 OK la erori, nu cerem implementare OAuth pentru apeluri server-la-server. Documentația de design este RFC 9110 și spec OpenAPI 3.0 — nu există un “Noplag Way” suplimentar de învățat.

Citiți notele de design

CONSTRÂNGERI DE DESIGN

IDEMPAceeași Idempotency-Key + body în 24h returnează răspuns cache. Retry pe erori de rețea cu aceeași cheie — fără dublu-cost, fără duplicate.

VERVersiunea majoră în URL (/v1, /v2). Schimbări majore aduc un nou path de versiune — versiunea veche rămâne 12 luni după anunț.

ERRJSON RFC 9457 problem-details pentru orice 4xx/5xx. type, title, detail, instance, plus un indiciu noplag.retry_strategy.

PAGCursor-based pe orice endpoint de listare. ?limit=100&cursor=… returnează next_cursor în body. Fără surprize de offset la pagina 47 când apar rânduri noi între timp.

OBSRăspunsul include X-Engine-Commit, X-Request-Id și Server-Timing pe etapă. Refaceți oricând orice check după ID; raportul leagă de release-ul engine exact.

OPENImplementare de referință Apache 2.0 la github.com/NoplagLabs/noplag-engine. Poți instala local dacă datele nu pot părăsi infrastructura ta — aceeași interfață API.

ÎNTREBĂRI FRECVENTE

Întrebările pe care le pun efectiv inginerii noștri de integrare.

Care este latența tipică la apel pentru un document normal?: p50 aproximativ 600ms pentru o verificare de 500 de cuvinte față de corpusul indexat; p95 ~1,8s. Se adaugă ~2s când Layer-W (verificare web în timp real) este activat — implică interogări la Google + Brave. Documentele lungi (cu timp estimat peste 8s) returnează imediat un check_id și transmit rezultatul prin webhook.
Cum se măsoară costul pentru API?: Un apel facturat per trimitere /v1/checks, indiferent de dimensiunea documentului până la plafonul de cuvinte (1.500 Pro, 50.000 Premium, Enterprise personalizat). Retry idempotent cu aceeași Idempotency-Key + body în 24h nu dublează costul. Citirile /v1/checks/{id} și apelurile auxiliare SDK sunt gratuite.
Pot rula API-ul self-hosted?: Da — github.com/NoplagLabs/noplag-engine este aceeași implementare de referință Apache-2.0 care rulează la engine.noplag.app. Cu docker compose up obțineți un endpoint local /v1/checks. Varianta cloud adaugă corpusul gestionat + cheile API Google/Brave; pentru self-host complet, folosiți propriile chei.
Există un header de retry rate-limit de încredere?: La 429 răspundem cu Retry-After în secunde. Header-ele X-RateLimit-* apar la fiecare răspuns — puteți pre-throttle bazat pe X-RateLimit-Remaining fără să așteptați un 429. Ambele sunt corecte și stabile la upgrade.
Care e frecvența release-ului pentru SDK-uri?: SDK-urile Python și Node se regenerează automat din openapi.yaml la fiecare tag engine. Release-urile majore engine (v0.x → v0.y) au SDK în aceeași zi. Patch-urile tehnice se livrează în acea săptămână. Ambele SDK-uri respectă semver; API-ul de bază se schimbă doar la /v1 → /v2.
Ce se întâmplă dacă corpusul se schimbă la mijlocul lunii?: Orice check marchează X-Engine-Commit și un timestamp de snapshot corpus. Reluarea unui check vechi pe corpusul actual se face cu un parametru de query (?corpus_snapshot=…). Raportul inițial se păstrează cu snapshotul original — nu modificăm niciodată silențios scorul de similaritate returnat.
Cum testez fără să consum cota lunară?: Cheile de test (nplg_test_…) merg pe un sandbox: toată suprafața API, nu persistă uploadurile, nu afectează limita lunară sau rate-limit-ul. Webhook-urile pornesc și din sandbox, deci testele end-to-end nu costă.
Cum fac bulk check-uri corect?: Trimiteți în paralel până la plafonul rate-limit — nu există endpoint batch (un batch de 500 care eșuează la doc 312 e mai rău decât 500 apeluri independente). Pentru volum mare, folosiți webhooks: trimiteți, primiți check_id imediat, lansați următoarele 200, preluați rezultate pe măsură ce sosesc, indiferent de ordine.
Pot limita check-ul doar la folderele mele?: Da — corpora: [] cu folder_id în body se limitează la foldere private user. Combinați cu corpora: ["academic"] pentru „doar academic + folderele mele”. Per apel; nu există nivel separat de tarifare.
Ce se schimbă dacă vreau rezidență UE sau instalare on-prem?: Enterprise oferă endpoint UE dedicat (api.eu.noplag.com) cu aceeași suprafață OpenAPI, deci datele rămân în EEA. Sau self-host implementarea de referință complet în VPC-ul propriu — același engine, același contract /v1, nimic iese din rețea. (Ne relansăm pe model open-core; atestări formale ca SOC 2 sunt planificate, nu livrate încă — engine-ul auditat e ceea ce oferim acum.)

Obțineți o cheie API. Faceți primul apel.

Trial gratuit cu 100 de apeluri API. Pro de la $23/lună pentru 1.000. Implementarea Apache 2.0 dacă preferați să rămână totul în rețea.

Obțineți cheie API Citiți spec OpenAPI