Wie hoch ist die Latenz für einen typischen Check?

p50 liegt bei etwa 600 ms für eine 500-Wörter-Prüfung gegen das indizierte Korpus; p95 bei ca. 1,8 s. Bei aktivierter Layer W (Live-Web-Überprüfung) kommen ca. 2 s hinzu – dabei erfolgt eine Rückfrage an Google + Brave. Lange Dokumente (über 8 s erwartete Bearbeitungszeit) liefern sofort eine check_id und melden das Ergebnis per Webhook zurück.

Wie wird die API abgerechnet?

Eine berechnete Anfrage pro /v1/checks-Abgabe, unabhängig von der Dokumentgröße bis zum jeweiligen Wortlimit (1.500 Pro, 50.000 Premium, individuell Enterprise). Idempotente Retrys mit gleichem Idempotency-Key + Body innerhalb 24h werden nicht doppelt gezählt. /v1/checks/{id}-Lesevorgänge und Hilfs-Calls über das SDK sind gratis.

Kann ich die API selbst hosten?

Ja – github.com/NoplagLabs/noplag-engine ist die gleiche Apache-2.0-Referenzimplementierung wie auf engine.noplag.app. Mit docker compose up erhalten Sie einen lokalen /v1/checks-Endpunkt. Die Cloud-Variante bietet das verwaltete Korpus und die Google/Brave-API-Keys; für vollständiges Self-Hosting müssen Sie eigene Keys bereitstellen.

Gibt es einen Rate-Limit-Retry-Header, auf den ich mich verlassen kann?

Bei 429 kommt Retry-After in Sekunden. Die X-RateLimit-*-Header gibt es bei jeder Antwort — mit X-RateLimit-Remaining können Sie vorab drosseln, statt bis zum 429 zu warten. Beide sind verlässlich, beide bleiben stabil über Deployments hinweg.

Wie häufig werden die SDKs veröffentlicht?

Python- und Node-SDKs regenerieren automatisch aus openapi.yaml bei jedem Engine-Tag. Major Engine Releases (v0.x → v0.y) bringen am gleichen Tag neue SDKs. Patchfixes kommen in der gleichen Woche. Beide SDKs folgen semver; die API bricht nur bei /v1 → /v2.

Was passiert, wenn sich das Corpus mitten im Monat ändert?

Jeder Check versieht X-Engine-Commit und einen Corpus-Snapshot-Timestamp. Einen alten Check gegen das aktuelle Corpus erneut prüfen? Ein Query-Parameter (?corpus_snapshot=…). Der Originalbericht bleibt erhalten — ein zurückgegebener Ähnlichkeitsscore wird nicht nachträglich geändert.

Wie kann ich testen, ohne mein Kontingent zu verbrauchen?

Test-Keys (nplg_test_…) gehen auf eine Sandbox: volle API-Oberfläche, speichert nie, zählt nie gegen mein Limit. Webhooks aus der Sandbox — End-to-End-Integrationstests sind kostenfrei.

Was ist der beste Weg für Bulk-Checks?

Parallel einreichen bis ans Rate-Limit — es gibt absichtlich keinen Batch-Endpoint (500-Dokument-Batch, Fehlschlag bei Dokument 312, ist schlechter als 500 Einzelanfragen). Für hohe Volumina: API kombinieren mit Webhooks — Einreichen, check_id sofort zurück, die nächsten 200 abschicken, Ergebnisse behandeln sobald sie eintrudeln.

Kann ich einen Check nur auf meine eigenen Ordner beschränken?

Ja — corpora: [] mit folder_id im Body vergleicht nur gegen private Ordner. Mit corpora: ["academic"] für „nur akademisch + eigene Ordner“. Pro-Call möglich, kein eigenes Preismodell nötig.

Was ändert sich für EU-Residenz oder On-Prem-Setup?

Enterprise bietet ein eigenes EU-Endpoint (api.eu.noplag.com) mit gleicher OpenAPI-Oberfläche — personenbezogene Daten bleiben im EWR. Oder die Referenzimplementierung komplett selbst auf eigener Infrastruktur hosten — gleiche Engine, gleicher /v1 Vertrag, nichts verlässt Ihr Netz. (Wir starten als Open-Core-Firma neu; formelle Nachweise wie SOC 2 sind geplant, aber noch nicht vorhanden — bis dahin gibt es die prüfbare Engine.)

RESTOpenAPI 3.0 Spezifikation · Python + Node SDKs · v0.4.2

Plagiatsprüfung API – REST und SDKs

Drop-in REST Endpoint für Plagiats- und KI-Erkennung. OpenAPI 3.0 Spezifikation, Python- und Node-SDKs, Apache 2.0-Referenzimplementierung. Vom ersten curl bis zu webhook-gesteuertem Volumen — gleiche Engine wie auf noplag.com.

REST · OpenAPI 3.0Python + Node SDKsApache 2.0 Referenzimpl

DER ERSTE CALL

Von null zu einem Ähnlichkeitsscore in einem curl.

POST-Text, Score-Intervalle als Antwort. Kein SDK nötig, kein Kompilieren, kein proprietäres Datenformat.

REQUEST · bashKopieren

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

RESPONSE · 200 OK · application/jsonKopieren

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

DIE ENDPOINTS

Vier Endpoints. Ein Vertrag. Versioniert in der URL.

Die gleiche OpenAPI-3.0-Spezifikation befindet sich sowohl im Open-Source-Repository als auch auf engine.noplag.app. Die SDKs werden bei jedem getaggten Release daraus neu generiert.

POST/v1/checksCheck absendenSynchron bis 8s; darüber Callback per Webhook. Idempotency-Key erforderlich.

GET/v1/checks/{id}Check abrufenGibt den aktuellen Berichtszustand zurück. Streaming-Intervalle via Accept: text/event-stream.

GET/v1/sources/{id}Quelle prüfenLöst eine gefundene Quelle per ID auf — vollständige URL, Snapshot-Datum, aus Cache abgerufen vs live.

POST/v1/foldersOrdner verwaltenPrüfungen anlegen / auflisten / verschieben. Corpus-Matching auf private Dokumente pro Ordner beschränkbar.

POST/v1/webhooksWebhook registrierenHMAC-signierte Zustellung; exponentielles Retry über 24h; jede Zustellung im Dashboard erneut abspielen.

Vollständige Referenz unter api./docsopenapi.yaml

AUTH + RATE-LIMITS

Bearer-Token. Idempotency-Keys. Ehrliche Rate-Limit-Header.

Nichts Exotisches. Standard-HTTP-Konzepte — wir halten uns daran, damit Ihre Retry-Middleware funktioniert.

AUTHENTIFIZIERUNG

Bearer-Token. Ein Header, kein Signatur-Prozess.

Key erstellenDashboard → Einstellungen → API. Keys sind (read / write / admin) scoped und in zwei Klicks drehbar.

Bei jedem Aufruf mitsendenAuthorization: Bearer nplg_live_…. Test-Keys (nplg_test_) gehen auf eine Sandbox, die Einreichungen nie speichert.

Idempotency-Key bei POST hinzufügenBeliebige UUID. Gleicher Key + Body liefert 24h lang dieselbe gecachte Antwort zurück — keine Doppelzahlungen oder doppelten Prüfungen bei Retrys.

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

RATE-LIMITS

Pro Key, pro Minute. Header zeigen Ihnen genau, wo Sie stehen.

STUFEREQ/MINMONATLICHBURST

Free10100 / Monat20

Pro601.000 / Monat120

Premium30010.000 / Monat600

EnterpriseIndividuellVerhandeltIndividuell

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

DIE SDKS

Zwei SDKs. Generiert aus derselben OpenAPI 3.0 Spezifikation.

Python + Node erscheinen bei jedem getaggten Engine-Release. Andere Sprachen (Go, Ruby, Java) werden aus openapi.yaml generiert — Community-PRs willkommen.

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 Latenz

99,95%Uptime-SLA

3Regionen (US/EU/AP)

OAPI 3Spezifikationsformat

Apache 2.0Referenzimpl

WEBHOOKS

Lang laufende Prüfungen melden sich zurück. Mit Retries, die nicht nerven.

Vier Eventtypen. JSON-Body. HMAC-SHA256-Signatur im Header.

check.completedBericht fertig · enthält vollständiges Bericht-JSON

check.failedPermanenter Fehler · enthält Fehlercode + Retry-Hinweis

check.progressZwischenstand · bisher gefundene Quellen

folder.sharedOrdnerzugriff an Teammitglied oder externen Prüfer vergeben

Exponentielle Retries über 24 Stunden. Im Dashboard erneut abspielbar.

Retry-Kurve5s, 30s, 2m, 10m, 1h, 6h, 24h — danach Dead-Letter

Timeout10s connect, 30s gesamt pro Versuch

ErfolgskriteriumHTTP 2xx Antwort im Zeitfenster; wir folgen Redirects

Replay-UIJede Zustellung aus dem Dashboard an eine andere URL erneut auslösen

Signatur prüfen. Alles ablehnen, was nicht passt.

Jede Zustellung trägt X-Noplag-Signature: t=<unix>,v1=<hex>. HMAC-SHA256 über Zeitstempel + Body mit Ihrem Webhook-Secret berechnen; in konstanter Zeit mit compare_digest prüfen.

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

DEV-GRUNDSÄTZE

Wir halten uns an HTTP. Das ist das gesamte API-Design-Dokument.

Idempotent bei POST. Versioniert in der URL. Fehler sagen, wie es weitergeht. Header zeigen Ihnen, wo Sie im Rate-Limit-Fenster stehen. Paginierung per Cursor, nicht Offset. Timestamps in UTC ISO 8601. Keine eigene HATEOAS-Variante, kein 200 OK bei Fehlern, keine OAuth-Implementierung für Server-zu-Server-Calls. Das API-Designdokument ist RFC 9110 plus OpenAPI 3.0 — keinen separaten „Noplag-Weg“.

Design-Notizen lesen

DESIGN-GRENZEN

IDEMPGleicher Idempotency-Key + Body innerhalb von 24h gibt dieselbe gecachte Antwort zurück. Retrys bei Netzausfall mit gleichem Key — keine Doppelzahlung oder doppelten Check.

VERHauptversion in der URL (/v1, /v2). Breaking Changes bedeuten neuen Versionspfad — alte Version 12 Monate nach Ankündigung unterstützt.

ERRRFC 9457 problem-details JSON bei jedem 4xx/5xx. type, title, detail, instance, plus noplag.retry_strategy-Hinweis.

PAGCursor-basiert auf allen List-Endpunkten. ?limit=100&cursor=… gibt next_cursor im Body aus. Kein Offset-Problem ab Seite 47 bei neuen Zeilen im Durchlauf.

OBSAntwort enthält X-Engine-Commit, X-Request-Id und Server-Timing je Stufe. Jeden Check per ID erneut abspielen; Bericht verlinkt den genauen Engine-Release.

OPENReferenzimplementierung unter Apache 2.0 auf github.com/NoplagLabs/noplag-engine. Eigene Infrastruktur möglich, falls Ihre Daten das Netzwerk nicht verlassen dürfen — identische API.

FAQ

Die Fragen, die unsere Integrationsingenieure wirklich stellen.

Wie hoch ist die Latenz für einen typischen Check?: p50 liegt bei etwa 600 ms für eine 500-Wörter-Prüfung gegen das indizierte Korpus; p95 bei ca. 1,8 s. Bei aktivierter Layer W (Live-Web-Überprüfung) kommen ca. 2 s hinzu – dabei erfolgt eine Rückfrage an Google + Brave. Lange Dokumente (über 8 s erwartete Bearbeitungszeit) liefern sofort eine check_id und melden das Ergebnis per Webhook zurück.
Wie wird die API abgerechnet?: Eine berechnete Anfrage pro /v1/checks-Abgabe, unabhängig von der Dokumentgröße bis zum jeweiligen Wortlimit (1.500 Pro, 50.000 Premium, individuell Enterprise). Idempotente Retrys mit gleichem Idempotency-Key + Body innerhalb 24h werden nicht doppelt gezählt. /v1/checks/{id}-Lesevorgänge und Hilfs-Calls über das SDK sind gratis.
Kann ich die API selbst hosten?: Ja – github.com/NoplagLabs/noplag-engine ist die gleiche Apache-2.0-Referenzimplementierung wie auf engine.noplag.app. Mit docker compose up erhalten Sie einen lokalen /v1/checks-Endpunkt. Die Cloud-Variante bietet das verwaltete Korpus und die Google/Brave-API-Keys; für vollständiges Self-Hosting müssen Sie eigene Keys bereitstellen.
Gibt es einen Rate-Limit-Retry-Header, auf den ich mich verlassen kann?: Bei 429 kommt Retry-After in Sekunden. Die X-RateLimit-*-Header gibt es bei jeder Antwort — mit X-RateLimit-Remaining können Sie vorab drosseln, statt bis zum 429 zu warten. Beide sind verlässlich, beide bleiben stabil über Deployments hinweg.
Wie häufig werden die SDKs veröffentlicht?: Python- und Node-SDKs regenerieren automatisch aus openapi.yaml bei jedem Engine-Tag. Major Engine Releases (v0.x → v0.y) bringen am gleichen Tag neue SDKs. Patchfixes kommen in der gleichen Woche. Beide SDKs folgen semver; die API bricht nur bei /v1 → /v2.
Was passiert, wenn sich das Corpus mitten im Monat ändert?: Jeder Check versieht X-Engine-Commit und einen Corpus-Snapshot-Timestamp. Einen alten Check gegen das aktuelle Corpus erneut prüfen? Ein Query-Parameter (?corpus_snapshot=…). Der Originalbericht bleibt erhalten — ein zurückgegebener Ähnlichkeitsscore wird nicht nachträglich geändert.
Wie kann ich testen, ohne mein Kontingent zu verbrauchen?: Test-Keys (nplg_test_…) gehen auf eine Sandbox: volle API-Oberfläche, speichert nie, zählt nie gegen mein Limit. Webhooks aus der Sandbox — End-to-End-Integrationstests sind kostenfrei.
Was ist der beste Weg für Bulk-Checks?: Parallel einreichen bis ans Rate-Limit — es gibt absichtlich keinen Batch-Endpoint (500-Dokument-Batch, Fehlschlag bei Dokument 312, ist schlechter als 500 Einzelanfragen). Für hohe Volumina: API kombinieren mit Webhooks — Einreichen, check_id sofort zurück, die nächsten 200 abschicken, Ergebnisse behandeln sobald sie eintrudeln.
Kann ich einen Check nur auf meine eigenen Ordner beschränken?: Ja — corpora: [] mit folder_id im Body vergleicht nur gegen private Ordner. Mit corpora: ["academic"] für „nur akademisch + eigene Ordner“. Pro-Call möglich, kein eigenes Preismodell nötig.
Was ändert sich für EU-Residenz oder On-Prem-Setup?: Enterprise bietet ein eigenes EU-Endpoint (api.eu.noplag.com) mit gleicher OpenAPI-Oberfläche — personenbezogene Daten bleiben im EWR. Oder die Referenzimplementierung komplett selbst auf eigener Infrastruktur hosten — gleiche Engine, gleicher /v1 Vertrag, nichts verlässt Ihr Netz. (Wir starten als Open-Core-Firma neu; formelle Nachweise wie SOC 2 sind geplant, aber noch nicht vorhanden — bis dahin gibt es die prüfbare Engine.)

API-Key holen. Ersten Call machen.

Kostenlose Testphase umfasst 100 API-Calls. Pro-Tarif 23 $/Monat für 1.000. Apache 2.0-Referenzimplementierung, falls Sie lieber intern prüfen.

API-Key holen OpenAPI-Spezifikation lesen