Qual a latência da chamada num documento típico?

p50 em torno de 600ms para uma verificação de 500 palavras contra o corpus indexado; p95 ~1,8s. Adicione ~2s quando o Layer W (verificação web em tempo real) estiver ativado — isso faz ida e volta pelo Google + Brave. Documentos longos (trabalho esperado acima de 8s) retornam um check_id imediatamente e fazem callback via webhook.

Como a cobrança funciona na API?

Uma cobrança por envio em /v1/checks, independente do tamanho (até limites por plano: 1.500 palavras Pro, 50.000 Premium, Enterprise customizável). Retries idempotentes igual Idempotency-Key + corpo em 24h não contam de novo. Leituras em /v1/checks/{id} e auxiliares do SDK não são cobradas.

Posso rodar a API auto-hospedada?

Sim — github.com/NoplagLabs/noplag-engine é a mesma implementação de referência Apache 2.0 usada em engine.noplag.app. docker compose up disponibiliza um endpoint local /v1/checks. A camada em nuvem inclui o corpus gerenciado + as chaves de API do Google/Brave; para self-host completo, use suas próprias chaves.

Existe um header de retry de rate-limit confiável?

No 429 retornamos Retry-After em segundos. Headers X-RateLimit-* em toda resposta — pode se antecipar com X-RateLimit-Remaining sem esperar um 429. Ambos são precisos e consistentes.

Qual a frequência de release dos SDKs?

SDKs Python e Node são auto-gerados pelo openapi.yaml a cada tag do motor. Grandes releases (v0.x → v0.y) têm SDK no mesmo dia. Patches vão em até uma semana. Ambos seguem semver; a API só quebra de /v1 para /v2.

O que muda se o corpus alterar no mês?

Cada check grava X-Engine-Commit e um timestamp do corpus. Repetir um check antigo no corpus novo exige só um parâmetro (?corpus_snapshot=…). O relatório original permanece com seu snapshot — nunca mudamos retroativamente uma pontuação já entregue.

Como testar sem gastar a cota mensal?

Chaves de teste (nplg_test_…) usam sandbox: acesso completo, sem gravar envios, não contam na cota ou limites. Webhooks também disparam no sandbox, assim o teste de integração ponta a ponta é gratuito.

Como fazer verificações em lote?

Submeta em paralelo até o limite do rate. Não há endpoint de lote por design (um lote de 500 documentos falha em 312 gera mais problema que 500 envios individuais). Para pipelines de alto volume, use a API com webhooks: submeta, receba o check_id na hora, envie as próximas 200 requisições, gerencie os resultados fora de ordem conforme chegam.

Posso limitar a verificação só às minhas pastas?

Sim — corpora: [] com folder_id no corpo limita à pasta privada do usuário. Combine com corpora: ["academic"] para 'só acadêmico + minhas pastas'. Escopo por chamada, sem plano separado.

O que muda se preciso residência UE ou on-premises?

Enterprise oferece endpoint exclusivo EU (api.eu.noplag.com), mesmo OpenAPI, dados só no EEE. Ou rode a referência totalmente no seu VPC — mesmo motor, mesmo /v1, sem tráfego externo. (Estamos migrando para open-core; atestados formais como SOC 2 em planejamento, não prontos — nesse meio-tempo entregamos o motor auditável.)

RESTEspecificação OpenAPI 3.0 · SDKs Python + Node · v0.4.2

Detector de plágio API para integração

Endpoint REST pronto para detecção de plágio e IA. Especificação OpenAPI 3.0, SDKs Python e Node, implementação de referência Apache 2.0. Do seu primeiro curl ao volume controlado por webhook — mesmo motor que opera em noplag.com.

REST · OpenAPI 3.0SDKs Python + NodeImpl. referência Apache 2.0

A PRIMEIRA CHAMADA

Do zero a uma pontuação de similaridade em um curl.

POST com texto, recebe intervalos pontuados. Não precisa de SDK, nem compilação, nem protocolo proprietário.

REQUISIÇÃO · bashCopiar

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

RESPOSTA · 200 OK · application/jsonCopiar

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

OS ENDPOINTS

Quatro endpoints. Um contrato. Versionados na URL.

A mesma especificação OpenAPI 3.0 está disponível no repositório open source e em engine.noplag.app. Os SDKs são regenerados a partir dela a cada release marcado.

POST/v1/checksSubmeter verificaçãoSíncrono até 8s; callback via webhook acima desse limite. Idempotency-Key obrigatória.

GET/v1/checks/{id}Buscar verificaçãoRetorna o estado mais recente do relatório. Interva-los via Accept: text/event-stream.

GET/v1/sources/{id}Inspecionar fonteResolve uma fonte encontrada por ID — URL completa, data do snapshot, origem cache vs live.

POST/v1/foldersGerenciar pastasCriar / listar / mover verificações. Limita a correspondência do corpus a documentos privados por pasta.

POST/v1/webhooksRegistrar webhookEntregas HMAC-assinadas; retentativa exponencial por 24h; reenvie qualquer entrega via painel.

Referência completa em api./docsopenapi.yaml

AUTENTICAÇÃO + LIMITES

Bearer tokens. Chaves de idempotência. Cabeçalhos de limite honestos.

Nada exótico. Usamos padrões HTTP — assim seu middleware de retry já funciona.

AUTENTICAÇÃO

Tokens Bearer. Um cabeçalho, sem dança de assinatura.

Crie uma chaveDashboard → Configurações → API. Chaves com escopo (leitura / escrita / admin) e rotativas em dois cliques.

Inclua em todas as chamadasAuthorization: Bearer nplg_live_…. Chaves de teste (nplg_test_) usam sandbox sem persistir envios.

Adicione Idempotency-Key nos POSTsQualquer UUID serve. Mesma chave + corpo retorna a resposta em cache por 24h, evitando duplicidade em retries.

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

LIMITES

Por chave, por minuto. Cabeçalhos mostram exatamente onde está.

PLANOREQ/MINMENSALBURST

Grátis10100 / mês20

Pro601.000 / mês120

Premium30010.000 / mês600

EnterprisePersonalizadoNegociadoPersonalizado

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

OS SDKS

Dois SDKs. Gerados da mesma OpenAPI 3.0.

Python + Node lançados a cada release do motor. Outros (Go, Ruby, Java) geram a partir do openapi.yaml — PRs da comunidade são bem-vindos.

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

<200mslatência p95

99,95%SLA de uptime

3regiões (US/EU/AP)

OAPI 3formato da spec

Apache 2.0impl. referência

WEBHOOKS

Verificações longas retornam para o seu endpoint. Retentativas sem surpresas.

Quatro tipos de evento. Corpo JSON. Assinatura HMAC-SHA256 no header.

check.completedRelatório pronto · inclui JSON completo

check.failedFalha permanente · inclui código de erro + dica para retry

check.progressProgresso intermediário · fontes resolvidas até o momento

folder.sharedAcesso à pasta concedido a colega ou auditor externo

Retentativas exponenciais por 24 horas. Replay a partir do painel.

Curva de retry5s, 30s, 2m, 10m, 1h, 6h, 24h — depois dead-letter

Timeout10s connect, 30s total por tentativa

Critério de sucessoResposta HTTP 2xx dentro do prazo; seguimos redirects

Replay UIEscolha qualquer entrega no painel e reenvie para outro URL

Verifique a assinatura. Rejeite tudo que falhar no cálculo.

Cada entrega vem com X-Noplag-Signature: t=<unix>,v1=<hex>. Calcule HMAC-SHA256 sobre timestamp + corpo usando seu segredo do webhook e compare em tempo constante.

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

PRINCÍPIOS DEV

Seguimos HTTP. Esse é todo nosso design de API.

Idempotente em POST. Versionado na URL. Erros explicam o próximo passo. Cabeçalhos trazem rate-limit. Paginação por cursor, nunca offset. Timestamps em UTC ISO 8601. Não há HATEOAS proprietário, não devolvemos 200 OK em erros, nem forçamos OAuth para servidor-servidor. O design é RFC 9110 + OpenAPI 3.0 — não existe um 'jeito Noplag' diferente para aprender.

Leia as notas de design

LIMITAÇÕES DE DESIGN

IDEMPIdempotency-Key + corpo iguais em 24h retornam resposta cacheada. Tente novamente a mesma chave em falha de rede — sem cobrança duplicada nem verificação repetida.

VERVersão principal na URL (/v1, /v2). Mudança breaking implica novo caminho — a anterior tem 12 meses de suporte após aviso.

ERRJSON RFC 9457 problem-details para todo 4xx/5xx. type, title, detail, instance, mais strategia noplag.retry.

PAGSempre cursor nos endpoints de lista. ?limit=100&cursor=… traz next_cursor no corpo. Nunca surpresa de offset na página 47 se chegarem linhas novas.

OBSResposta inclui X-Engine-Commit, X-Request-Id e Server-Timing por etapa. Refaça qualquer check por ID; o relatório aponta para o release exato do motor.

OPENImplementação de referência Apache 2.0 em github.com/NoplagLabs/noplag-engine. Faça a autohospedagem se seus dados não puderem sair da sua rede — mesma interface de API.

FAQ

As perguntas feitas pelos engenheiros de integração.

Qual a latência da chamada num documento típico?: p50 em torno de 600ms para uma verificação de 500 palavras contra o corpus indexado; p95 ~1,8s. Adicione ~2s quando o Layer W (verificação web em tempo real) estiver ativado — isso faz ida e volta pelo Google + Brave. Documentos longos (trabalho esperado acima de 8s) retornam um check_id imediatamente e fazem callback via webhook.
Como a cobrança funciona na API?: Uma cobrança por envio em /v1/checks, independente do tamanho (até limites por plano: 1.500 palavras Pro, 50.000 Premium, Enterprise customizável). Retries idempotentes igual Idempotency-Key + corpo em 24h não contam de novo. Leituras em /v1/checks/{id} e auxiliares do SDK não são cobradas.
Posso rodar a API auto-hospedada?: Sim — github.com/NoplagLabs/noplag-engine é a mesma implementação de referência Apache 2.0 usada em engine.noplag.app. docker compose up disponibiliza um endpoint local /v1/checks. A camada em nuvem inclui o corpus gerenciado + as chaves de API do Google/Brave; para self-host completo, use suas próprias chaves.
Existe um header de retry de rate-limit confiável?: No 429 retornamos Retry-After em segundos. Headers X-RateLimit-* em toda resposta — pode se antecipar com X-RateLimit-Remaining sem esperar um 429. Ambos são precisos e consistentes.
Qual a frequência de release dos SDKs?: SDKs Python e Node são auto-gerados pelo openapi.yaml a cada tag do motor. Grandes releases (v0.x → v0.y) têm SDK no mesmo dia. Patches vão em até uma semana. Ambos seguem semver; a API só quebra de /v1 para /v2.
O que muda se o corpus alterar no mês?: Cada check grava X-Engine-Commit e um timestamp do corpus. Repetir um check antigo no corpus novo exige só um parâmetro (?corpus_snapshot=…). O relatório original permanece com seu snapshot — nunca mudamos retroativamente uma pontuação já entregue.
Como testar sem gastar a cota mensal?: Chaves de teste (nplg_test_…) usam sandbox: acesso completo, sem gravar envios, não contam na cota ou limites. Webhooks também disparam no sandbox, assim o teste de integração ponta a ponta é gratuito.
Como fazer verificações em lote?: Submeta em paralelo até o limite do rate. Não há endpoint de lote por design (um lote de 500 documentos falha em 312 gera mais problema que 500 envios individuais). Para pipelines de alto volume, use a API com webhooks: submeta, receba o check_id na hora, envie as próximas 200 requisições, gerencie os resultados fora de ordem conforme chegam.
Posso limitar a verificação só às minhas pastas?: Sim — corpora: [] com folder_id no corpo limita à pasta privada do usuário. Combine com corpora: ["academic"] para 'só acadêmico + minhas pastas'. Escopo por chamada, sem plano separado.
O que muda se preciso residência UE ou on-premises?: Enterprise oferece endpoint exclusivo EU (api.eu.noplag.com), mesmo OpenAPI, dados só no EEE. Ou rode a referência totalmente no seu VPC — mesmo motor, mesmo /v1, sem tráfego externo. (Estamos migrando para open-core; atestados formais como SOC 2 em planejamento, não prontos — nesse meio-tempo entregamos o motor auditável.)

Obtenha uma chave de API. Faça sua primeira chamada.

Teste grátis inclui 100 chamadas. Plano Pro R$23/mês por 1.000. Use Apache 2.0 referência se preferir manter tudo em sua rede.

Obter chave de API Leia a OpenAPI spec