Qual è la latenza tipica di una chiamata?

p50 circa 600 ms per un controllo di 500 parole sul corpus indicizzato; p95 circa 1,8 s. Aggiungi circa 2 s se Layer W (verifica web in tempo reale) è attivo — include una richiesta a Google + Brave. I documenti lunghi (oltre 8 s di elaborazione prevista) restituiscono subito un check_id e inviano il risultato tramite webhook.

Come viene conteggiato il pricing API?

Un addebito per ogni POST su /v1/checks, a prescindere dalla lunghezza fino al limite piano (1.500 parole Pro, 50.000 Premium, custom Enterprise). Retry idempotenti (stessa Idempotency-Key + body entro 24h) non raddoppiano niente. Letture /v1/checks/{id} e SDK di supporto sono gratuite.

Posso far girare l’API in self-host?

Sì — github.com/NoplagLabs/noplag-engine è la stessa implementazione di riferimento Apache-2.0 utilizzata su engine.noplag.app. Con docker compose up ottieni un endpoint locale /v1/checks. Il livello cloud aggiunge il corpus gestito e le API key di Google/Brave; per il self-hosting completo devi usare le tue.

C’è un header per retry dei rate limit di cui fidarsi?

Su 429 restituiamo Retry-After in secondi. Gli header X-RateLimit-* sono sempre presenti — così può pre-throttlare su X-RateLimit-Remaining senza attendere un 429. Entrambi precisi e stabili tra deploy.

Quanto spesso vengono aggiornati gli SDK?

SDK Python e Node si auto-generano da openapi.yaml ad ogni tag engine. Maggiori release engine (v0.x → v0.y) rilasciano lo stesso giorno lungo SDK. Patch minori nella stessa settimana. Entrambi seguono semver; l’API cambia solo tra /v1 → /v2.

Cosa succede se il corpus cambia a metà mese?

Ogni check salva X-Engine-Commit e una data snapshot corpus. Rieseguire un check vecchio contro corpus attuale basta un parametro (?corpus_snapshot=…). Il report originale resta archiviato con il suo corpus — non cambiamo mai silenziosamente uno score precedente.

Come posso testare senza consumare il mio traffico mensile?

Chiavi test (nplg_test_…) usano una sandbox: API completa, nessuna persistenza, nessun conteggio su traffico mensile o limiti. Anche i webhook scattano dalla sandbox — test end-to-end gratuiti.

Qual è il modo corretto per bulk check?

Mandi in parallelo, rispettando i suoi rate limit — non c’è un endpoint batch (un batch di 500 documenti che fallisce sul 312 è peggio di 500 chiamate indipendenti). Per forti volumi, usi webhooks: submit, ottenga check_id subito, faccia altri 200 submit e gestisca i risultati fuori ordine.

Posso limitare il check solo alle mie cartelle?

Sì — corpora: [] con folder_id nel body filtra sui soli documenti privati. Con corpora: ["academic"] fa “solo academic + private”. Limite a ogni chiamata; nessun piano aggiuntivo richiesto.

Cosa cambia per EU residency o on-prem?

Piano Enterprise prevede endpoint EU dedicato (api.eu.noplag.com) con stessa superficie API, così i dati restano in EEA. Oppure self-host interno nella Sua VPC — stesso motore, stesso /v1, niente esce dalla rete. (Stiamo tornando a open-core; attestati formali tipo SOC 2 sono pianificati, non ancora pronti — engine auditabile è la soluzione di oggi.)

RESTSpecifica OpenAPI 3.0 · SDK Python e Node · v0.4.2

Antiplagio API REST e OpenAPI 3.0

REST endpoint immediato per rilevare plagio e AI. Specifica OpenAPI 3.0, SDK Python e Node, implementazione di riferimento Apache 2.0. Dal primo curl al volume via webhook — stesso motore che gira su noplag.com.

REST · OpenAPI 3.0SDK Python e NodeImplementazione di riferimento Apache 2.0

LA PRIMA CHIAMATA

Da zero a uno score di similarità con un curl.

POST del testo, ritorno degli intervalli valutati. Nessun SDK richiesto, nessuna compilazione, nessun formato wire proprietario.

RICHIESTA · bashCopia

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

RISPOSTA · 200 OK · application/jsonCopia

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

GLI ENDPOINT

Quattro endpoint. Un unico contratto. Versionamento nell’URL.

La stessa specifica OpenAPI 3.0 è presente sia nel repository open source sia su engine.noplag.app. Gli SDK vengono rigenerati da essa a ogni release contrassegnata.

POST/v1/checksEsegui un checkSincrono fino a 8s; callback webhook oltre. Idempotency-Key obbligatoria.

GET/v1/checks/{id}Recupera un checkRestituisce lo stato corrente del report. Gli intervalli sono disponibili via Accept: text/event-stream.

GET/v1/sources/{id}Analizza una fonteRestituisce una fonte corrispondente per ID — URL completo, data snapshot, provenienza cache o live.

POST/v1/foldersGestisci cartelleCrea / elenca / sposta check. Limita il matching ai documenti privati per cartella.

POST/v1/webhooksRegistra un webhookInvii firmati HMAC; retry esponenziale per 24h; ripetizione di qualsiasi invio dalla dashboard.

Riferimento completo su api./docsopenapi.yaml

AUTENTICAZIONE + RATE LIMIT

Token Bearer. Idempotency Key. Header rate-limit trasparenti.

Nulla di esotico. Pattern HTTP standard — li seguiamo in modo che il Suo middleware di retry già funzioni.

AUTENTICAZIONE

Token Bearer. Un header, senza complessità di firma.

Crei una chiaveDashboard → Impostazioni → API. Chiavi con scope (lettura / scrittura / admin) e ruotabili in due clic.

Usi la chiave in ogni chiamataAuthorization: Bearer nplg_live_…. Le chiavi di test (nplg_test_) lavorano su una sandbox che non persiste le submission.

Aggiunga Idempotency-Key per i POSTQualsiasi UUID va bene. Stessa chiave + body ritorna lo stesso risultato per 24h: retry senza costi doppi o duplicati.

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

RATE LIMIT

Per chiave, per minuto. Gli header dicono lo stato.

PIANORICH./MINMENSILEBURST

Free10100 / mese20

Pro601.000 / mese120

Premium30010.000 / mese600

EnterprisePersonalizzatoConcordatoPersonalizzato

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

GLI SDK

Due SDK. Generati dalla stessa specifica OpenAPI 3.0.

Python e Node sono disponibili ogni volta che esce una release engine etichettata. Altri linguaggi (Go, Ruby, Java) si generano da openapi.yaml — PR dalla community benvenute.

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

<200mslatenza p95

99,95%SLA uptime

3regioni (US/EU/AP)

OAPI 3formato spec

Apache 2.0implementazione di riferimento

WEBHOOK

Check lunghi richiamano di ritorno. Retry gestibili.

Quattro eventi. Corpo JSON. Firma HMAC-SHA256 nell’header.

check.completedReport pronto · incluso JSON del report

check.failedErrore permanente · include codice errore + suggerimenti di retry

check.progressAvanzamento intermedio · sorgenti risolte finora

folder.sharedAccesso cartella concesso a un collega o revisore esterno

Retry esponenziale per 24 ore. Ogni invio ripetibile dalla dashboard.

Progressione retry5s, 30s, 2m, 10m, 1h, 6h, 24h — poi dead-letter

Timeout10s connessione, 30s tentativo

Criteri successoRisposta HTTP 2xx nel tempo utile; seguiamo i redirect

Replay UIRilanci qualunque invio dalla dashboard a un nuovo URL

Verifichi la firma. Rifiuti tutto ciò che non coincide.

Ogni invio porta X-Noplag-Signature: t=<unix>,v1=<hex>. Calcoli HMAC-SHA256 su timestamp + body con il Suo secret per il webhook e compari a tempo costante.

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

PRINCIPI DI SVILUPPO

Seguiamo HTTP. È tutto il documento di design API.

POST idempotenti. Versionamento nell’URL. Errori che dicono come agire. Header rate-limit espliciti. Paginazione via cursore, non offset. Timestamp UTC ISO 8601. Nessun dialetto HATEOAS custom, nessuna 200 OK su errore, nessun obbligo OAuth per chiamate server-server. Design API = RFC 9110 + OpenAPI 3.0 — non c’è niente tipo “Noplag Way” da imparare.

Legga le note di design

VINCOLI DI DESIGN

IDEMPStessa Idempotency-Key + body in 24h restituisce la risposta cache. Retry su errori di rete: nessun doppio costo/duplicato.

VERMajor version nell’URL (/v1, /v2). Breaking changes = nuovo path. Vecchia versione supportata 12 mesi dall’annuncio.

ERRJSON problem-details RFC 9457 su ogni 4xx/5xx. type, title, detail, instance, più un suggerimento noplag.retry_strategy.

PAGCursore su tutti gli endpoint di liste. ?limit=100&cursor=… restituisce next_cursor nel body. Nessuna sorpresa offset a pagina 47 se arrivano nuove righe.

OBSRisposta con X-Engine-Commit, X-Request-Id, Server-Timing per ogni fase. Può rigiocare qualunque check per ID; il report lega la release engine usata.

OPENImplementazione di riferimento Apache 2.0 su github.com/NoplagLabs/noplag-engine. Puoi eseguire il self-host se i tuoi dati non possono uscire dalla tua rete — stessa interfaccia API.

FAQ

Le domande realmente poste dagli integratori.

Qual è la latenza tipica di una chiamata?: p50 circa 600 ms per un controllo di 500 parole sul corpus indicizzato; p95 circa 1,8 s. Aggiungi circa 2 s se Layer W (verifica web in tempo reale) è attivo — include una richiesta a Google + Brave. I documenti lunghi (oltre 8 s di elaborazione prevista) restituiscono subito un check_id e inviano il risultato tramite webhook.
Come viene conteggiato il pricing API?: Un addebito per ogni POST su /v1/checks, a prescindere dalla lunghezza fino al limite piano (1.500 parole Pro, 50.000 Premium, custom Enterprise). Retry idempotenti (stessa Idempotency-Key + body entro 24h) non raddoppiano niente. Letture /v1/checks/{id} e SDK di supporto sono gratuite.
Posso far girare l’API in self-host?: Sì — github.com/NoplagLabs/noplag-engine è la stessa implementazione di riferimento Apache-2.0 utilizzata su engine.noplag.app. Con docker compose up ottieni un endpoint locale /v1/checks. Il livello cloud aggiunge il corpus gestito e le API key di Google/Brave; per il self-hosting completo devi usare le tue.
C’è un header per retry dei rate limit di cui fidarsi?: Su 429 restituiamo Retry-After in secondi. Gli header X-RateLimit-* sono sempre presenti — così può pre-throttlare su X-RateLimit-Remaining senza attendere un 429. Entrambi precisi e stabili tra deploy.
Quanto spesso vengono aggiornati gli SDK?: SDK Python e Node si auto-generano da openapi.yaml ad ogni tag engine. Maggiori release engine (v0.x → v0.y) rilasciano lo stesso giorno lungo SDK. Patch minori nella stessa settimana. Entrambi seguono semver; l’API cambia solo tra /v1 → /v2.
Cosa succede se il corpus cambia a metà mese?: Ogni check salva X-Engine-Commit e una data snapshot corpus. Rieseguire un check vecchio contro corpus attuale basta un parametro (?corpus_snapshot=…). Il report originale resta archiviato con il suo corpus — non cambiamo mai silenziosamente uno score precedente.
Come posso testare senza consumare il mio traffico mensile?: Chiavi test (nplg_test_…) usano una sandbox: API completa, nessuna persistenza, nessun conteggio su traffico mensile o limiti. Anche i webhook scattano dalla sandbox — test end-to-end gratuiti.
Qual è il modo corretto per bulk check?: Mandi in parallelo, rispettando i suoi rate limit — non c’è un endpoint batch (un batch di 500 documenti che fallisce sul 312 è peggio di 500 chiamate indipendenti). Per forti volumi, usi webhooks: submit, ottenga check_id subito, faccia altri 200 submit e gestisca i risultati fuori ordine.
Posso limitare il check solo alle mie cartelle?: Sì — corpora: [] con folder_id nel body filtra sui soli documenti privati. Con corpora: ["academic"] fa “solo academic + private”. Limite a ogni chiamata; nessun piano aggiuntivo richiesto.
Cosa cambia per EU residency o on-prem?: Piano Enterprise prevede endpoint EU dedicato (api.eu.noplag.com) con stessa superficie API, così i dati restano in EEA. Oppure self-host interno nella Sua VPC — stesso motore, stesso /v1, niente esce dalla rete. (Stiamo tornando a open-core; attestati formali tipo SOC 2 sono pianificati, non ancora pronti — engine auditabile è la soluzione di oggi.)

Ottenere una API key. Fare la prima chiamata.

Il free trial include 100 chiamate. Piano Pro 23€/mese per 1.000. Implementazione di riferimento Apache 2.0 se preferisce restare on-premise.

Ottenere una API key Leggere la OpenAPI spec