{"openapi":"3.1.0","info":{"title":"Crivum","version":"v1","description":"A Crivum mede um texto contra critérios padronizados por três modelos de referência e devolve um resultado de 0 a 100 com a decomposição por critério e a divergência entre eles. Quando o trabalho passa do piso e a autora assina, a Crivum deposita um DOI Crossref, publica uma página citável e guarda prova de anterioridade."},"servers":[{"url":"https://crivum.org"},{"url":"https://crivum.dev"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Chave de API da conta, enviada como Authorization: Bearer <chave>."}}},"paths":{"/v1/avaliacoes":{"post":{"summary":"Mede um texto contra os critérios publicados.","description":"Cria uma avaliação nova ou, com a mesma referência de uma chamada anterior da mesma chave, devolve o resultado já existente sem medir de novo. Texto acima de 60.000 caracteres é recusado com a causa texto_grande_demais.","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Crivum-Canal","in":"header","required":false,"description":"Canal de origem do pedido. Sem este header, o canal registrado é direto.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"texto":{"type":"string","minLength":1},"titulo":{"type":"string","minLength":1,"maxLength":300},"tipo":{"type":"string","enum":["pesquisa","revisao","teorico","relato","ensaio","resumo","pratica"]},"nivel":{"type":"string","enum":["T","G","E","M","D","P","auto"]},"referencia":{"type":"string","minLength":1,"maxLength":200}},"required":["texto","titulo","tipo","referencia"],"additionalProperties":false}}}},"responses":{"200":{"description":"Referência já conhecida, resultado reaproveitado.","content":{"application/json":{"example":{"ok":true,"referencia":"pedido-2026-09-0001","estado":"concluida","admissibilidade":"sim","medicao":{"criterios":[{"criterioId":1,"titulo":"Clareza e estrutura argumentativa","pontos":12,"possivel":15,"divergencia":2},{"criterioId":2,"titulo":"Originalidade da contribuição","pontos":10,"possivel":15,"divergencia":3},{"criterioId":3,"titulo":"Honestidade intelectual e reconhecimento de limitações","pontos":13,"possivel":15,"divergencia":1},{"criterioId":4,"titulo":"Ancoragem em referências e estado da arte","pontos":11,"possivel":15,"divergencia":2},{"criterioId":5,"titulo":"Transparência do contexto e dos dados do caso","pontos":15,"possivel":20,"divergencia":4},{"criterioId":6,"titulo":"Transferibilidade e lições acionáveis","pontos":13,"possivel":20,"divergencia":3}],"divergencia":15,"versoes":{"rubrica":"v1","tabela_de_tier":"v1","limiares":"v1"},"avaliadoras_reais":3,"score":74,"tier":"B","codigo":"Crivum MB74"},"sinais":[{"tipo":"borderline_score","rotulo":"pontuação na fronteira do limiar","detalhe":"Score 74 na fronteira de limiar.","sugestao":"Reforce os critérios em que a obra ficou mais fraca com dados, método e resultados explícitos antes de reenviar."}],"registro":{"elegivel":false,"motivos":["score_abaixo_do_piso","originalidade_nao_medida_em_modo_live","assinatura_da_titular_pendente"],"falta_o_que":["O score ficou abaixo do piso de 75 pontos que libera o registro.","A originalidade ainda não é medida em modo live nesta fase.","A titular ainda não assinou a publicação."]},"consumo":{"laudas":4,"escada_de_preco":{"creditos_base":4,"desconto":0,"degrau_promocional":false},"saldo":{"livres":42,"pagas":4,"total":46}},"nao_e":"Isto não é peer review. A leitura é feita por três modelos de referência contra critérios publicados, sem parecerista humano na maioria das obras, e a casa nunca usa a expressão peer review para descrever o próprio trabalho. Isto não coloca a obra em base de indexação acadêmica. O DOI torna a obra citável e localizável, e quem indexa é cada base pelos próprios critérios. Isto não é selo de instituição de ensino e não vale como título. O resultado é uma medição com versão gravada e endereço público, e quem lê decide o que fazer com ela. A casa mede texto em qualquer idioma e responde no idioma do texto, e os critérios foram calibrados em português e em inglês, então comparar resultado entre idiomas diferentes é leitura que ninguém mediu ainda.","contrato":"v1"}}}},"201":{"description":"Medição concluída.","content":{"application/json":{"example":{"ok":true,"referencia":"pedido-2026-09-0001","estado":"concluida","admissibilidade":"sim","medicao":{"criterios":[{"criterioId":1,"titulo":"Clareza e estrutura argumentativa","pontos":12,"possivel":15,"divergencia":2},{"criterioId":2,"titulo":"Originalidade da contribuição","pontos":10,"possivel":15,"divergencia":3},{"criterioId":3,"titulo":"Honestidade intelectual e reconhecimento de limitações","pontos":13,"possivel":15,"divergencia":1},{"criterioId":4,"titulo":"Ancoragem em referências e estado da arte","pontos":11,"possivel":15,"divergencia":2},{"criterioId":5,"titulo":"Transparência do contexto e dos dados do caso","pontos":15,"possivel":20,"divergencia":4},{"criterioId":6,"titulo":"Transferibilidade e lições acionáveis","pontos":13,"possivel":20,"divergencia":3}],"divergencia":15,"versoes":{"rubrica":"v1","tabela_de_tier":"v1","limiares":"v1"},"avaliadoras_reais":3,"score":74,"tier":"B","codigo":"Crivum MB74"},"sinais":[{"tipo":"borderline_score","rotulo":"pontuação na fronteira do limiar","detalhe":"Score 74 na fronteira de limiar.","sugestao":"Reforce os critérios em que a obra ficou mais fraca com dados, método e resultados explícitos antes de reenviar."}],"registro":{"elegivel":false,"motivos":["score_abaixo_do_piso","originalidade_nao_medida_em_modo_live","assinatura_da_titular_pendente"],"falta_o_que":["O score ficou abaixo do piso de 75 pontos que libera o registro.","A originalidade ainda não é medida em modo live nesta fase.","A titular ainda não assinou a publicação."]},"consumo":{"laudas":4,"escada_de_preco":{"creditos_base":4,"desconto":0,"degrau_promocional":false},"saldo":{"livres":42,"pagas":4,"total":46}},"nao_e":"Isto não é peer review. A leitura é feita por três modelos de referência contra critérios publicados, sem parecerista humano na maioria das obras, e a casa nunca usa a expressão peer review para descrever o próprio trabalho. Isto não coloca a obra em base de indexação acadêmica. O DOI torna a obra citável e localizável, e quem indexa é cada base pelos próprios critérios. Isto não é selo de instituição de ensino e não vale como título. O resultado é uma medição com versão gravada e endereço público, e quem lê decide o que fazer com ela. A casa mede texto em qualquer idioma e responde no idioma do texto, e os critérios foram calibrados em português e em inglês, então comparar resultado entre idiomas diferentes é leitura que ninguém mediu ainda.","contrato":"v1"}}}},"400":{"description":"Corpo fora do contrato desta rota.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}},"401":{"description":"Chave ausente, inválida, revogada ou vencida.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}},"402":{"description":"Saldo de laudas insuficiente para esta chamada.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de RESULTADO DE MEDIÇÃO. Nunca traz ok — não é um veredito sobre a chamada, é o que foi medido.","properties":{"referencia":{"type":"string"},"estado":{"type":"string","enum":["falhou"]},"causa":{"type":"string"},"motivo_publico":{"type":"string"},"contrato":{"type":"string"}},"required":["referencia","estado","causa","contrato"]}}}},"422":{"description":"A casa recusou o conteúdo enviado.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de RESULTADO DE MEDIÇÃO. Nunca traz ok — não é um veredito sobre a chamada, é o que foi medido.","properties":{"referencia":{"type":"string"},"estado":{"type":"string","enum":["falhou"]},"causa":{"type":"string"},"motivo_publico":{"type":"string"},"contrato":{"type":"string"}},"required":["referencia","estado","causa","contrato"]}}}},"429":{"description":"Limite de vazão ou teto de gasto da chave excedido.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}},"503":{"description":"A casa está indisponível ou fora do ar para esta chamada.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]},{"type":"object","description":"Envelope de RESULTADO DE MEDIÇÃO. Nunca traz ok — não é um veredito sobre a chamada, é o que foi medido.","properties":{"referencia":{"type":"string"},"estado":{"type":"string","enum":["falhou"]},"causa":{"type":"string"},"motivo_publico":{"type":"string"},"contrato":{"type":"string"}},"required":["referencia","estado","causa","contrato"]}]}}}}}}},"/v1/avaliacoes/{id}":{"get":{"summary":"Reconsulta uma avaliação pela referência escolhida no pedido original.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"A mesma referência enviada em POST /v1/avaliacoes.","schema":{"type":"string"}}],"responses":{"200":{"description":"Avaliação encontrada para esta chave.","content":{"application/json":{"example":{"ok":true,"referencia":"pedido-2026-09-0002","estado":"medindo","contrato":"v1"}}}},"401":{"description":"Chave ausente, inválida, revogada ou vencida.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}},"404":{"description":"Nenhuma avaliação com esta referência para esta chave.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}}}}},"/v1/saldo":{"get":{"summary":"Laudas de cortesia e pagas restantes, e o preço da próxima lauda avulsa.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Saldo atual da conta dona da chave.","content":{"application/json":{"example":{"ok":true,"livres":42,"pagas":8,"total":50,"proxima_renovacao":"2026-10-13T00:00:00.000Z","preco_proxima_lauda":12.9,"moeda":"BRL","chave":{"prefixo_visivel":"crv_live_9f3a","ambiente":"live","expira_em":"2027-09-13T00:00:00.000Z","escopos":["avaliar"]},"contrato":"v1"}}}},"401":{"description":"Chave ausente, inválida, revogada ou vencida.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}}}}},"/v1/triagem":{"post":{"summary":"Diz se um texto já está de pé, sem chave de API.","description":"Rota pública, sem chave. Um modelo barato responde se o material já tem problema, método e resultado, devolve uma leitura de prontidão de 0 a 100 e, quando falta informação, até seis perguntas objetivas. O freio é por origem, com 40 triagens por dia. Texto acima do teto de leitura é aparado, nunca recusado, e a resposta declara isso em texto_aparado e caracteres_lidos. A medição que vale, com os três modelos de referência, mora em POST /v1/avaliacoes e exige chave.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"texto":{"type":"string","minLength":20,"maxLength":400000}},"required":["texto"],"additionalProperties":false}}}},"responses":{"200":{"description":"Triagem concluída.","content":{"application/json":{"example":{"ok":true,"pronto":false,"prontidao":58,"tipo_sugerido":"relato","leitura":"O texto descreve a intervenção com clareza e ainda não apresenta os resultados medidos.","perguntas":["Quais indicadores foram medidos antes e depois da intervenção?","Qual foi o período de acompanhamento?","Que limitações o próprio autor reconhece no método?"],"texto_aparado":false,"caracteres_lidos":1200,"alcance":"Esta triagem sai de um modelo barato e responde se o texto já tem problema, método e resultado de pé. A nota que vale sai da medição pelos três modelos de referência.","medicao_completa":{"rota":"POST /v1/avaliacoes","entrega":"Nota de 0 a 100 com a decomposição por critério, a divergência entre os três modelos de referência e a elegibilidade da obra a um registro citável.","exige_chave":true},"contrato":"v1"}}}},"400":{"description":"Corpo fora do contrato desta rota.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}},"429":{"description":"As triagens gratuitas desta origem acabaram nesta janela.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}},"503":{"description":"A casa não conseguiu triar o texto agora.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}}}}},"/v1/criterios":{"get":{"summary":"Título e descrição de cada critério por tipo de obra, sem peso.","description":"Rota pública, sem chave de API. `opcoes` é o recorte que quem chama a porta pode escolher sozinho (autodeclarável); `tipos` é a rubrica completa, com os tipos que a casa não abre para autodeclaração.","responses":{"200":{"description":"Critérios da rubrica ativa.","content":{"application/json":{"example":{"ok":true,"tipos":[{"tipo":"relato","rotulo":"Relato de Caso","tem_tier":true,"criterios":[{"criterioId":1,"titulo":"Clareza e estrutura argumentativa","descricao":"O texto enuncia com clareza o que defende e organiza o argumento de forma estruturada e consistente."},{"criterioId":2,"titulo":"Originalidade da contribuição","descricao":"A contribuição é nova em relação à prática estabelecida e ao que já foi publicado no domínio."},{"criterioId":3,"titulo":"Honestidade intelectual e reconhecimento de limitações","descricao":"O trabalho declara limitações, incertezas e condições de contorno, sem inflar conclusões."},{"criterioId":4,"titulo":"Ancoragem em referências e estado da arte","descricao":"As afirmações se apoiam em referências verificáveis e dialogam com o estado da arte."},{"criterioId":5,"titulo":"Transparência do contexto e dos dados do caso","descricao":"Contexto, intervenção e resultados do caso aplicado estão descritos com dados verificáveis."},{"criterioId":6,"titulo":"Transferibilidade e lições acionáveis","descricao":"O relato extrai lições generalizáveis e indica as condições em que se aplicam a outros contextos."}]}],"opcoes":{"tipos":[{"chave":"relato","rotulo":"Relato de Caso","tem_tier":true}],"niveis":[{"chave":"M","rotulo":"Mestrado"}]},"tabela_de_tier":{"por_nivel":{"T":[{"tier":"S","min":93},{"tier":"A+","min":85},{"tier":"A","min":75},{"tier":"B","min":60},{"tier":"C","min":0}],"G":[{"tier":"S","min":93},{"tier":"A+","min":85},{"tier":"A","min":75},{"tier":"B","min":60},{"tier":"C","min":0}],"E":[{"tier":"S","min":93},{"tier":"A+","min":85},{"tier":"A","min":75},{"tier":"B","min":60},{"tier":"C","min":0}],"M":[{"tier":"S","min":93},{"tier":"A+","min":85},{"tier":"A","min":75},{"tier":"B","min":60},{"tier":"C","min":0}],"D":[{"tier":"S","min":93},{"tier":"A+","min":85},{"tier":"A","min":75},{"tier":"B","min":60},{"tier":"C","min":0}],"P":[{"tier":"S","min":93},{"tier":"A+","min":85},{"tier":"A","min":75},{"tier":"B","min":60},{"tier":"C","min":0}]}},"limiares":{"devolutiva_por_tipo":{"pesquisa":50,"revisao":50,"teorico":50,"relato":50,"ensaio":50,"resumo":50,"pratica":50},"flag_de_divergencia":40,"piso_de_registro":75},"versoes":{"rubrica":"v1","tabela_de_tier":"v1","limiares":"v1"},"contrato":"v1"}}}}}}},"/v1/records":{"get":{"summary":"Registros já publicados no acervo, paginados por cursor.","description":"Rota pública, sem chave de API. Mesmo universo que /acervo já mostra.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Cursor opaco devolvido em proximo_cursor pela página anterior.","schema":{"type":"string"}},{"name":"slug","in":"query","required":false,"description":"Restringe a resposta a um único registro, pelo slug da página pública.","schema":{"type":"string"}},{"name":"doi","in":"query","required":false,"description":"Restringe a resposta a um único registro, pelo DOI. Aceita a forma nua, a forma com prefixo doi: e a URL resolvível, e não diferencia caixa. Só encontra obra cujo DOI já foi depositado.","schema":{"type":"string"}},{"name":"codigo","in":"query","required":false,"description":"Restringe a resposta a um único registro, pelo código compacto da obra.","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de registros publicados.","content":{"application/json":{"example":{"ok":true,"registros":[{"codigo":"Crivum MB74","slug":"programa-de-eficiencia-energetica","url":"https://crivum.org/p/programa-de-eficiencia-energetica","titulo":"Programa de eficiência energética","autores":["Maria Silva"],"anonimizado":false,"publicado_em":"2026-09-01T12:00:00.000Z","doi":"10.67665/crivum.2026.0001","tier":"B","score":74}],"proximo_cursor":null,"contrato":"v1"}}}},"400":{"description":"Cursor de paginação não reconhecido.","content":{"application/json":{"schema":{"type":"object","description":"Envelope de ERRO da porta. Sempre ok:false — a chamada foi recusada antes de medir.","properties":{"ok":{"type":"boolean","enum":[false]},"codigo":{"type":"string"},"frase":{"type":"string"},"como_corrigir":{"type":"string"},"documentacao":{"type":"string"},"contrato":{"type":"string"},"cobrado":{"type":"boolean"}},"required":["ok","codigo","frase","como_corrigir","documentacao","contrato","cobrado"]}}}}}}}}}