Documentação da API Jev

Visão geral

Jev avalia um state — um ticket de suporte, um log de chat, uma chamada de ferramenta, qualquer texto ou JSON — contra um conjunto de perguntas tipadas e retorna respostas estruturadas nas quais seu código pode ramificar. Não gera texto.

Uma requisição pode fazer até 8 perguntas; elas são avaliadas juntas e compartilham o custo de entrada do state. O corpo da requisição tem o mesmo formato aceito pela API SystemOne da TypeSafe — para migrar uma integração que funciona, troque a URL base e a chave Bearer.

• POST https://jevmodel.org/v1/systemone — o único endpoint de decisão.
• CORS está aberto (access-control-allow-origin: *), o endpoint responde de qualquer origem. Mantenha sua chave no servidor mesmo assim.
• O playground envia exatamente o mesmo formato de requisição pela sua sessão de navegador — o que você pré-visualiza lá é o que você envia.

Autenticação

Toda chamada de API precisa de uma chave do jevmodel.org. Crie uma em Dashboard → API keys; as chaves começam com sk- e são mostradas uma única vez na criação. Guarde-a como variável de ambiente, por exemplo JEVMODEL_API_KEY.

Authorization: Bearer $JEVMODEL_API_KEY

As chaves pertencem ao saldo de tokens da sua conta e podem ser revogadas no dashboard. Nunca exponha uma chave em código do lado do cliente nem a commite num repositório — se vazar, revogue e gere outra. O playground autentica com a sua sessão de navegador conectada e não precisa de chave.

Endpoint HTTP

Envie um corpo JSON ao endpoint de avaliação com autenticação Bearer:

POST /v1/systemone HTTP/1.1
Host: jevmodel.org
Authorization: Bearer $JEVMODEL_API_KEY
Content-Type: application/json
Idempotency-Key: ticket-4821-run-1   # optional

Idempotency-Key é opcional (até 100 caracteres). Novas tentativas com a mesma chave reutilizam o registro de cobrança original, então uma requisição repetida não é cobrada duas vezes pela mesma entrada.

curl -X POST https://jevmodel.org/v1/systemone \
  -H "Authorization: Bearer $JEVMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "The customer has been billed twice and wants a refund today.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which queue should own this ticket?",
        "criteria": {
          "billing": "Payments, refunds, invoices",
          "technical": "Product errors and usage problems",
          "sales": "Pricing, upgrades, new business"
        }
      },
      "escalate": {
        "type": "noul",
        "instructions": "Does this need a human right now?"
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this for the customer?",
        "criteria": ["routine", "soon", "urgent", "critical"]
      }
    }
  }'

Corpo da requisição

Um objeto JSON com um state e um mapa de perguntas:

{
  "model": "jev-latest",
  "state": "The customer has been billed twice and wants a refund today.",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which queue should own this ticket?",
      "criteria": {
        "billing": "Payments, refunds, invoices",
        "technical": "Product errors and usage problems",
        "sales": "Pricing, upgrades, new business"
      }
    },
    "escalate": {
      "type": "noul",
      "instructions": "Does this need a human right now?"
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this for the customer?",
      "criteria": ["routine", "soon", "urgent", "critical"]
    }
  }
}

Cada pergunta precisa de type e instructions (até 1.800 caracteres) dizendo ao modelo o que decidir. criteria fornece o espaço de resposta — obrigatório para choice e score, opcional para noul.

Tipos de pergunta

Escolha a forma de resposta que sua aplicação consegue usar.

Criteria serializados são limitados a 2.000 caracteres por pergunta. Falhas de validação retornam 422 antes de qualquer token ser reservado — requisições inválidas nunca são cobradas.

JSON de resposta

Uma resposta 200 é a saída do modelo em si: o modelo resolvido, uma resposta por nome de pergunta e o uso. Os valores abaixo são ilustrativos — execute a requisição para uma saída real.

{
  "model": "jev-latest",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.93, "technical": 0.05, "sales": 0.02 },
      "confidence": 0.93
    },
    "escalate": {
      "type": "noul",
      "noul": 0.12
    },
    "urgency": {
      "type": "score",
      "score": 1.4,
      "confidence": 0.88
    }
  },
  "usage": { "input_tokens": 136, "output_tokens": 18 }
}

• answers é indexado pelos seus nomes de pergunta — você lê os campos que pediu.
• Em choice, ramifique pelo rótulo selecionado e inspecione probabilities quando precisar da distribuição completa.
• noul é P(sim) — seu código define o limiar de ação.
• usage.input_tokens é o que esta chamada realmente cobrou; tokens de saída são grátis.

Cobrança

A API cobra apenas tokens de entrada — a saída é grátis. Cada chamada reserva uma estimativa antes e depois liquida pelos usage.input_tokens reais reportados pelo modelo. Se Jev falhar no upstream, a reserva é reembolsada integralmente e automaticamente.

• Faça login uma vez e ganhe 100.000 tokens de entrada grátis; pacotes pagos a partir de US$ 9,90 e nunca expiram.
• Saldo insuficiente retorna 402 antes de chamar o Jev.
• X-Tokens-Remaining em toda resposta 200 é o seu saldo após a liquidação.
• Estime você mesmo: ceil(JSON.stringify({state, questions}).length / 4).

Modelos e limites

jev-latest é o modelo padrão e o servido atualmente — o campo model é opcional. As variantes Laya mostradas no playground estão por vir e ainda não estão expostas neste endpoint.

Esses números descrevem o validador da API; o modelo upstream pode ter seus próprios limites de contexto.

Erros e novas tentativas

Erros retornam um envelope JSON com um type legível por máquina e um message para humanos:

{
  "error": {
    "type": "invalid_request_error",
    "message": "At most 8 questions per request."
  }
}

Tente de novo 429 e 502 com backoff exponencial — a janela de taxa é por minuto, pausas curtas costumam bastar. Envie um Idempotency-Key ao repetir para que uma requisição repetida liquide no mesmo registro de cobrança em vez de cobrar duas vezes.

Servidor MCP para agentes

jevmodel.org também roda um servidor MCP remoto via Streamable HTTP em https://jevmodel.org/mcp. Ele expõe quatro ferramentas — jev_decide (o contrato completo state-mais-questions), jev_noul, jev_choice e jev_score — para que agentes de código como Claude Code, Cursor ou Cline chamem o Jev sem escrever HTTP.

claude mcp add --transport http jev https://jevmodel.org/mcp \
  --header "Authorization: Bearer $JEVMODEL_API_KEY"

• Mesma chave Authorization: Bearer sk-… e mesmo saldo de tokens que esta API — tools/call cobra só tokens de entrada.
• initialize, ping e tools/list são sem autenticação; só tools/call usa sua chave.
• GET /mcp retorna um cartão JSON de descoberta para agentes e humanos.

Os comandos de instalação para Claude Code e Cursor, e a skill de agente correspondente (manual de julgamento), estão na página de ferramentas de agente.

Guia de ferramentas de agente →

Do playground à API

Monte o cenário primeiro no playground — a prévia da requisição mostra o corpo JSON exato que sua aplicação deve enviar, e Copy API example dá o cURL correspondente. Quando as respostas estiverem boas, crie uma chave no dashboard e troque a sessão de navegador por autenticação Bearer.

Leitura adicional: Como usar o Jev percorre uma primeira chamada do início ao fim, e Exemplos da API Jev tem padrões de produção para cada tipo de pergunta.