Referência da API do Jenova Agent

URL Base: https://api.jenova.ai/v1

Autenticação: Token Bearer no cabeçalho Authorization

Sumário

• Visão Geral
• Início Rápido
• Conceitos Fundamentais
• Autenticação
• Pontos de Extremidade da API
  • Mensagens
  • Sessões
  • Operações
  • Créditos
  • Agentes
  • Modelos
  • Documentação
• Transmissão (SSE)
• Integração com Servidor MCP
• Faturamento
• Limites de Taxa
• Tratamento de Erros
• Paginação
• Localização
• Privacidade e Dados
• Suporte

Visão Geral

Execute agentes personalizados no seu produto ou fluxo de trabalho em minutos. Configure seus agentes para qualquer tarefa, escolha qualquer modelo e ferramenta e deixe a Jenova cuidar do harness de agentes, do banco de dados e da escala.

A pilha completa de agentes:

• Harness de agentes gerenciado: Uma chamada entra, trabalho pronto sai. Seu agente pesquisa, raciocina, chama ferramentas e gera os arquivos — exatamente como você instrui.
• Contexto e memória sem limites: O gerenciamento de contexto com tecnologia RAG e o rastreamento proprietário do estado da sessão permitem memória ilimitada dentro de cada conversa.
• Biblioteca de ferramentas e MCP: Conecte-se à nossa biblioteca com 30+ ferramentas e servidores MCP, como busca, geração de imagens, e-mail e muito mais — ou adicione seus próprios servidores MCP.
• Alterne para qualquer modelo sem esforço: Implante modelos da OpenAI, da Anthropic, do Google, da xAI ou dos principais provedores de código aberto, e alterne entre os modelos com um único parâmetro.
• Conhecimento e RAG gerenciados: A Jenova cuida do pipeline de RAG de ponta a ponta — chunking, indexação, armazenamento e recuperação.
• Comprovado em escala: Implante em uma infraestrutura testada em campo que já executa centenas de agentes ativos em produção. Zero clusters para provisionar, escalar ou manter.

Início Rápido

1. Obtenha Sua Chave de API

Gere uma chave de API no painel do desenvolvedor em www.jenova.ai/platform. As chaves seguem o formato jnv_sk_* e são passadas como tokens Bearer.

2. Escolha ou Crie um Agente

Escolha um agente pré-construído na plataforma ou crie um agente personalizado no painel com instruções, configurações de modelo, arquivos de base de conhecimento, ferramentas e servidores MCP.

3. Envie Sua Primeira Mensagem

Crie uma sessão e envie uma mensagem em uma única chamada:

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

A resposta é transmitida de volta como Server-Sent Events:

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Capture o session_id de stream_started para solicitações subsequentes. Para respostas JSON síncronas, consulte Enviar Mensagem.

Conceitos Fundamentais

Agente

Um agente de IA com o qual você interage por meio da API. Cada agente possui um slug único (por exemplo, my-support-agent) usado como o valor de agent nas chamadas da API.

• Pré-construído: Selecione entre os agentes existentes na plataforma.
• Personalizado: Configure o seu próprio no painel com instruções, modelo, base de conhecimento, ferramentas e servidores MCP.

Sessão

Uma linha de conversação independente entre um usuário final e um agente.

• Identificador: ID com prefixo (por exemplo, ses_abc123).
• Escopo: Podem existir múltiplas sessões para o mesmo agente e usuário final, cada uma com estado de conversação independente.
• Ciclo de vida: As sessões persistem indefinidamente até serem excluídas por meio da API. Para tarefas pontuais que não precisam de uma sessão, use POST /messages com ephemeral: true.
• Isolamento de plataforma: As sessões da API são separadas das conversas no aplicativo web do Jenova. Usuários finais, histórico de sessões e faturamento são independentes entre a API e o aplicativo web.

Mensagem

Uma única entrada no histórico de conversação de uma sessão, retornada pelos pontos de extremidade de Mensagens. Cada mensagem inclui um objeto from estruturado com type (user ou agent) e name, além de um type de mensagem:

• external - uma mensagem de conversação destinada a ser exibida como conteúdo de chat.
• internal - uma mensagem opcional que representa etapas de trabalho do agente durante uma execução, como chamadas de ferramentas ou recuperação.

Execução

Uma única execução de agente criada ao enviar uma mensagem. Uma execução possui um run_id, pode transmitir eventos enquanto estiver ativa e pode produzir uma ou mais mensagens concluídas. Cada sessão pode ter apenas uma execução ativa por vez.

Usuário Final

O campo user associa sessões a um usuário final em seu aplicativo. Use um ID opaco estável, como seu ID de usuário interno ou UUID. Evite e-mails ou outras informações pessoais identificáveis, a menos que seu aplicativo exija isso. Sessões criadas com o mesmo valor de user são agrupadas, permitindo a listagem de sessões por usuário.

Se user for omitido, a sessão fica associada à sua conta de desenvolvedor e não poderá ser filtrada por usuário final posteriormente. Informe user em produção.

Para solicitações a uma sessão existente (qualquer ponto de extremidade com {session_id} no caminho), user é uma proteção de propriedade opcional. Se você o fornecer, ele deve corresponder ao valor de user usado quando a sessão foi criada; caso contrário, a API retorna 404 session_not_owned. Envie-o como parâmetro de consulta em solicitações GET e DELETE, e no corpo JSON em solicitações POST e PATCH. Um parâmetro de consulta user em solicitações POST ou PATCH retorna 400 bad_request.

Autenticação

Autentique cada solicitação com um token Bearer no cabeçalho Authorization:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

As chaves de API são geradas no painel do desenvolvedor.

User-Agent é opcional. Os SDKs podem defini-lo para fins de diagnóstico, mas a API não exige isso.

Formato da chave: As chaves começam com o prefixo jnv_sk_ seguido por uma string aleatória codificada em base62.

Limites: Cada conta de desenvolvedor pode ter até 10 chaves de API ativas.

Pontos de Extremidade da API

Mensagens

O envio de mensagens é o caminho principal da API. Use POST /messages para a primeira mensagem; isso cria a sessão e inicia a execução em uma única solicitação. Use POST /sessions/{session_id}/messages ao continuar um session_id já capturado.

Enviar Mensagem

POST /messages

Cria uma sessão persistente e envia a primeira mensagem em uma única solicitação. Defina ephemeral: true para uma solicitação avulsa com transmissão que não retorna ID de sessão e não pode ser continuada. Seus dados são excluídos pouco depois da conclusão da solicitação.

Corpo da Solicitação

Exemplo - Transmissão (padrão)

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

A resposta é um fluxo SSE (consulte Transmissão (SSE) para o formato dos eventos). Solicitações persistentes incluem o novo session_id; solicitações com ephemeral: true omitem session_id e devem usar transmissão.

Exemplo - JSON (sem transmissão)

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

Resposta

As respostas com transmissão emitem os eventos SSE documentados em Transmissão (SSE). As respostas sem transmissão retornam o objeto de mensagem com stop_reason e usage da solicitação, conforme mostrado em Continuar Sessão. stop_reason é end_run, ou user_cancelled se a execução foi cancelada depois que o agente produziu uma mensagem.

Se a execução for cancelada antes de o agente produzir uma mensagem, a API retorna 200 OK com status: "cancelled", session_id, run_id, stop_reason: "user_cancelled" e usage.

Se uma execução sem transmissão ainda estiver em processamento após 90 segundos, a API retorna 202 Accepted com status: "processing", session_id, run_id e uma message legível por humanos. A execução continua após a resposta ou a desconexão do cliente; verifique as mensagens da sessão ou use transmissão para fluxos de trabalho mais longos.

Erros

Continuar Sessão

POST /sessions/{session_id}/messages

Envia uma Mensagem para uma Sessão persistente existente e recebe a resposta do agente. As respostas são transmitidas via SSE por padrão; defina stream: false para JSON.

Corpo da Solicitação

Exemplo - Transmissão (padrão)

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

Exemplo - JSON (sem transmissão)

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

Resposta 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

Se a Sessão já tiver uma Execução ativa ou Mensagens na fila, a API retorna JSON 202 Accepted com status: "queued", session_id, run_id e message_id. A Mensagem do usuário é processada pela Execução ativa. Solicitações com additional_context retornam 409 busy em vez disso.

As respostas sem transmissão seguem as mesmas regras de Enviar Mensagem, incluindo a resposta status: "cancelled" quando a Execução é cancelada antes de o Agente produzir uma Mensagem.

Erros

Idempotência

POST /messages, POST /sessions/{session_id}/messages e POST /invoke aceitam um cabeçalho Idempotency-Key opcional (máx. 255 caracteres). Use uma chave exclusiva para cada envio lógico do usuário para que novas tentativas de rede ou envios duplicados não criem execuções duplicadas. As chaves são mantidas por 24 horas.

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

Sem transmissão: Uma nova tentativa retorna a resposta salva com o cabeçalho Idempotent-Replayed: true, incluindo erros retornados depois que a solicitação começou a ser processada. Uma resposta 202 Accepted salva é reproduzida sem alterações; use Obter Status da Execução ou Listar Mensagens para verificar o resultado. Solicitações rejeitadas antes do início do processamento, como erros de validação ou de créditos, não são salvas, portanto uma nova tentativa é avaliada novamente.

Com transmissão: O stream não é reproduzido novamente. Para POST /messages e POST /sessions/{session_id}/messages, tentar novamente durante a execução ou após a conclusão retorna um erro de idempotência com o run_id original e, para solicitações persistentes, o session_id. Para solicitações persistentes, use Obter Status da Execução para verificar uma execução ativa, ou Listar Mensagens para buscar os resultados persistidos. Resultados de POST /invoke com transmissão não podem ser recuperados depois que o stream é fechado. Novas tentativas de POST /invoke retornam o id original em vez de run_id e session_id.

Exemplo de nova tentativa em uma transmissão já concluída:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

Erros de idempotência

Listar Mensagens

GET /sessions/{session_id}/messages

Retorna uma lista paginada das mensagens da sessão. Por padrão, apenas as mensagens de conversa external são retornadas. A primeira página contém as mensagens mais recentes; dentro de cada página, as mensagens estão em ordem cronológica (as mais antigas primeiro). sequence é o número de ordenação da mensagem dentro da sessão.

Parâmetros de Consulta

Exemplo

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

Resposta 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "stop_reason": "end_run"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Objeto de mensagem

Objeto de arquivo

Erros

Obter Mensagem

GET /sessions/{session_id}/messages/{message_id}

Recupera uma única mensagem pelo ID.

Parâmetros de Consulta

Resposta 200 OK

Retorna um único objeto de mensagem com a mesma estrutura da resposta de listagem.

Erros

Anexos de Arquivo

Informe URLs em HTTPS publicamente acessíveis no campo file_urls.

Formatos suportados

• Imagens: JPG, JPEG, PNG, WebP
• Documentos: PDF, DOCX, XLSX, PPTX, TXT, CSV, RTF, MD, HTML, XML, JSON, LOG
• Código: JS, TS, TSX, JSX, PY, Java, Go, C, CPP, H, HPP, CS, RB, PHP, RS, Swift, KT, Scala, SQL, CSS, YAML, YML

As URLs de arquivo são buscadas quando o agente as lê durante a execução, não quando a solicitação é aceita. Uma URL que não pode ser buscada, ou um arquivo com mais de 20 MB, não é lido; a solicitação em si não é rejeitada.

Ao listar mensagens, os arquivos anexados aparecem no array files da mensagem.

Contexto Adicional

Passe contexto nomeado para uma única Mensagem em additional_context, como detalhes da conta do usuário final. Ele não é salvo no histórico de mensagens.

Use um nome descritivo, como customer_profile ou order_details.

Um item com name ou content ausente ou que não seja string retorna 400 invalid_payload. Outros itens inválidos retornam 400 bad_request.

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "additional_context": [
      {
        "name": "customer_profile",
        "content": "Plan: Pro. Last login: 2026-05-18."
      }
    ]
  }'

Sessões

Sessões são conversas persistentes entre um usuário final e um agente. A maioria das integrações pode criá-las implicitamente com POST /messages.

Criar Sessão

POST /sessions

Cria uma sessão persistente vazia vinculada a um agente específico. Use isso quando precisar de um ID de sessão antes da primeira mensagem; caso contrário, prefira POST /messages.

Nota: ephemeral não é aceito em POST /sessions; use POST /messages com ephemeral: true para solicitações pontuais.

Corpo da Solicitação

Exemplo

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

Resposta 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

Objeto de sessão

Erros

Listar Sessões

GET /sessions

Retorna uma lista paginada de suas sessões, ordenadas pela mais recentemente atualizada.

Parâmetros de Consulta

Exemplo

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

Resposta 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

Erros

Obter Sessão

GET /sessions/{session_id}

Recupera uma única sessão pelo ID.

Parâmetros de Consulta

Resposta 200 OK

Retorna um objeto de sessão.

Erros

Renomear Sessão

PATCH /sessions/{session_id}

Atualiza o nome de exibição de uma sessão.

Corpo da Solicitação

Resposta 200 OK

Retorna o objeto de sessão atualizado.

Erros

Excluir Sessão

DELETE /sessions/{session_id}

Exclui permanentemente uma sessão e todas as suas mensagens. A sessão não pode ter uma execução ativa.

Resposta 204 No Content

Erros

Operações

Esses pontos de extremidade são controles de recuperação e edição para sessões persistentes. A maioria das integrações precisa apenas de Cancelar Execução Ativa; use as demais operações quando você quiser intencionalmente alterar ou recuperar o estado da sessão. Todas as operações suportam a proteção de propriedade opcional user descrita em Usuário Final.

Cancelar Execução Ativa

POST /sessions/{session_id}/cancel

Cancela a execução ativa do agente. Isso não exclui as mensagens que já foram concluídas antes do cancelamento.

Corpo da Solicitação

Resposta 204 No Content

Erros

Desfazer Execução Ativa

POST /sessions/{session_id}/undo

Cancela a execução ativa, espera que ela seja interrompida e, em seguida, remove todas as mensagens que ela já havia adicionado. Nenhuma saída adicional é persistida após a solicitação de desfazer.

Corpo da Solicitação

Resposta 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

Se a execução for cancelada antes de qualquer mensagem ser concluída, deleted é um array vazio.

Erros

Excluir Mensagens Recentes

POST /sessions/{session_id}/messages/delete

Remove as count mensagens mais recentes de uma sessão inativa, incluindo mensagens internal. Use include=all em Listar Mensagens para vê-las. A sessão não deve ter uma execução ativa.

Corpo da Solicitação

Resposta 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

Erros

Bifurcar Sessão

POST /sessions/{session_id}/fork

Cria uma nova sessão copiando a sessão de origem até uma mensagem específica. A sessão de origem não deve ter uma execução ativa.

Corpo da Solicitação (opcional)

Resposta 201 Created

Retorna o objeto de sessão recém-criado com a mesma estrutura da criação de sessão.

Erros

Obter Status da Execução

GET /sessions/{session_id}/runs/{run_id}

Retorna o estado atual de uma execução ativa. Use este endpoint após uma conexão SSE interrompida ou uma resposta de idempotência que retornou um run_id. Após a conclusão de uma execução, obtenha os resultados com GET /sessions/{session_id}/messages.

Resposta 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

status é running enquanto o agente está trabalhando, streaming quando o texto da resposta está sendo produzido, ou ended brevemente após o término da execução. A resposta também pode incluir progress_events com atividades recentes, no mesmo formato de stream_progress. Quando status for ended ou a solicitação retornar 404 not_found, busque as mensagens da sessão.

Erros

Créditos

Obter Saldo

GET /credits/balance

Retorna seu saldo de créditos atual.

Resposta 200 OK

{
  "balance": "123.45"
}

Agentes

Crie e edite agentes personalizados no painel. O suporte da API para criação e edição de agentes chegará em breve.

Fluxos de trabalho agendados/em segundo plano não são atualmente compatíveis através da API. O suporte chegará em breve.

Listar Agentes

GET /agents

Retorna os agentes disponíveis para sua conta. Use o valor agent ao criar sessões ou enviar mensagens.

Resposta 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

Modelos

Listar Modelos

GET /models

Retorna todos os Modelos disponíveis para uso no Campo model ao enviar mensagens ou chamar POST /invoke.

Resposta 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "claude-sonnet-5",
      "name": "Claude Sonnet 5",
      "thinking_variant": "claude-sonnet-5-thinking"
    }
  ]
}

Modelos com um thinking_variant suportam raciocínio estendido. Use o ID da variante diretamente no Campo model para habilitá-lo.

Se nenhum model for especificado ao enviar uma Mensagem, o model da sessão é utilizado. Ele é definido como o Modelo padrão do Agente quando a sessão é criada.

Invocar Modelo

POST /invoke

Envia um prompt diretamente a um Modelo, sem agente, Sessão ou ferramentas. As respostas são transmitidas via SSE por padrão; defina stream: false para JSON.

Corpo da Solicitação

Exemplo

curl -X POST https://api.jenova.ai/v1/invoke \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "content": "Describe a forest in one sentence.",
    "stream": false
  }'

Resposta 200 OK

{
  "id": "inv_abc123",
  "model": "claude-sonnet-5",
  "content": "Sunlight filters through tall pines onto a quiet, mossy floor.",
  "usage": {
    "cost": "0.0004"
  }
}

Respostas com transmissão enviam stream_started, depois eventos stream_delta à medida que o modelo gera o texto, e terminam com stream_ended, que inclui usage. Concatene os valores de chunk_content na ordem de seq para construir a resposta transmitida. Se a solicitação falhar, stream_error é enviado antes de stream_ended. Os eventos trazem id no lugar de session_id e run_id.

usage.cost é null quando o custo não está disponível. Se uma solicitação sem transmissão falhar depois que a chamada ao modelo começar, a resposta de erro inclui os campos id e usage de nível superior.

Solicitações com transmissão são limitadas a 120 minutos. Solicitações sem transmissão aguardam o resultado por até 30 minutos em vez de retornar 202 Accepted, e retornam um erro se o resultado não estiver pronto até lá.

Erros

Documentação

GET /docs?lang=en
GET /doc?lang=en

Retorna esta referência em Markdown. Use lang para selecionar o idioma.

Transmissão (SSE)

Quando stream é omitido ou é true (o padrão), as respostas de Mensagem são entregues como Server-Sent Events. Use os Eventos message_completed para identificar Mensagens prontas para serem buscadas ou renderizadas.

Tempo Limite: as conexões SSE permanecem abertas até o fim da Execução. As Execuções são limitadas a 120 minutos. Solicitações de mensagem sem transmissão aguardam até 90 segundos e, em seguida, retornam 202 Accepted enquanto a Execução continua. Para POST /invoke sem transmissão, consulte Invocar Modelo.

Cabeçalhos de Conexão

Os fluxos de mensagens definem estes cabeçalhos:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id está disponível antes do primeiro Evento SSE. Os fluxos de POST /invoke não definem X-Run-Id; use o id em stream_started.

Reconexão e Recuperação

Os fluxos SSE não são reproduzidos novamente. Se a conexão cair em uma solicitação persistente, use o session_id e o run_id capturados para recuperar o estado:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

Se a Execução ainda estiver ativa, isso retorna o status atual, o texto parcial e o progresso recente. Se retornar status: "ended" ou 404 not_found, a Execução não está mais ativa; busque as Mensagens da Sessão para reconciliar a saída concluída:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

Formato do Quadro

Cada quadro SSE segue o formato padrão:

event: <event_type>
data: <json_payload>

Duas quebras de linha encerram cada quadro.

Tipos de Evento

Os streams incluem eventos de ciclo de vida, delta de texto, pensamento, progresso, aviso, conclusão de mensagem, conexão MCP, erro, final e ping. Alguns tipos de evento são enviados apenas quando relevantes.

Para solicitações efêmeras (ephemeral: true), todo evento SSE omite session_id. Use run_id apenas para correlacionar eventos dentro dessa única transmissão.

Para a reconciliação final em solicitações persistentes, aguarde o evento stream_ended e, em seguida, chame Listar Mensagens.

Campos comuns em eventos com escopo de execução:

stream_started

Enviado uma vez quando a execução é iniciada.

stream_delta

Enviado repetidamente à medida que o agente gera o texto de resposta visível. Concatene os valores de chunk_content na ordem de seq para construir a resposta transmitida.

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

Enviado repetidamente enquanto o agente emite a saída de pensamento. Use-o para um indicador de pensamento separado ou uma visualização de rastreamento; não o concatene ao texto final da resposta.

stream_progress

Relata atividade visível ao usuário durante a geração, como ler um documento, pesquisar na web ou aguardar uma ação do usuário. Esses eventos destinam-se a uma exibição temporária na interface; ignore campos desconhecidos. Use mensagens concluídas como o histórico de mensagens autoritativo.

Defina include_progress: false em uma solicitação de mensagem para omitir apenas stream_progress. Eventos de ciclo de vida, ping, message_completed, erros e eventos terminais ainda são enviados quando relevantes.

Alguns eventos de progresso podem incluir url, file_name ou server_name como dicas de exibição opcionais.

message_completed

Enviado sempre que uma mensagem é concluída e está pronta para ser buscada ou renderizada.

Este é um marcador de limite, não o objeto completo da mensagem. Busque a mensagem se precisar do conteúdo ou dos metadados.

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"my-support-agent"},"type":"external"}

mcp_connection

Enviado quando o agente precisa que o usuário final conecte ou autorize um ou mais servidores MCP antes de continuar. Este evento está disponível apenas no modo streaming.

mcp_connection_resolved

Enviado quando a ação do usuário de conexão MCP foi resolvida ou expirou.

Nenhum campo adicional além dos campos comuns com escopo de execução.

warning

Enviado para avisos não fatais durante uma execução.

stream_error

Enviado quando uma execução falha. Um evento final stream_ended pode ser enviado a seguir com success: false e stop_reason: "error".

stream_ended

Enviado uma vez quando a execução termina. Este é o evento final do stream.

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Exemplo de execução cancelada:

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

Quadros de manutenção de conexão enviados a cada 15 segundos para evitar tempos limite de proxy/CDN. Ignore-os no seu cliente.

Integração com Servidor MCP

Conecte seus agentes a ferramentas externas por meio do Model Context Protocol (MCP):

• Servidores MCP gerenciados pela Jenova: servidores hospedados pela Jenova para busca, recuperação de conteúdo, geração de documentos e outras capacidades integradas
• Servidores MCP remotos: outros servidores MCP remotos configurados para seu Agente

Os servidores MCP devem ser configurados no painel ao criar ou editar seu Agente. Para usar seu próprio servidor MCP, adicione-o a um Agente personalizado e, em seguida, chame esse Agente pela API. A API executa as Ferramentas habilitadas na configuração do Agente; nenhuma configuração adicional é necessária nas solicitações da API.

Quando um Agente usa Ferramentas MCP durante uma resposta, Eventos de progresso são enviados no stream conforme ocorrem:

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

Se o agente precisar que o usuário final conecte ou autorize um servidor MCP durante a execução, as respostas em streaming podem incluir os eventos mcp_connection e mcp_connection_resolved. Apresente a lista de servidores de conexão ao usuário final e abra a auth_url fornecida quando presente. Mantenha o stream SSE aberto enquanto o usuário final conecta ou autoriza o servidor.

Após a autorização, a Jenova armazena o token, a janela de autorização exibe uma página de conclusão, e a mesma Execução continua automaticamente. O Usuário Final não precisa reenviar a Mensagem.

Se o usuário final não conectar, autorizar ou ignorar ou silenciar antes de user_action_deadline_unix, a execução termina com stop_reason: "user_action_timeout". Você também pode cancelar a execução ativa com POST /sessions/{session_id}/cancel.

Armazene a auth_url no lado do cliente. Se o cliente se desconectar durante a autorização, a URL permanece válida até user_action_deadline_unix. Para solicitações persistentes, verifique a execução com Obter Status da Execução ou busque as mensagens após a execução terminar.

Solicitações sem streaming (stream: false) não oferecem suporte a ações do usuário de conexão MCP; use streaming para agentes que possam precisar dessa interação.

Ignorar Conexão MCP

POST /sessions/{session_id}/mcp/connection/skip

Dispensa uma ação do usuário de conexão MCP pendente e permite que a execução continue sem essa conexão.

Para silenciar futuros prompts de conexão para um servidor para o mesmo usuário final e agente, inclua mcp_server_id e mute. mute aceita uma duração como 30m, 24h ou 7d, ou forever.

Corpo da Solicitação

Resposta 204 No Content

O stream emite mcp_connection_resolved, e então a execução continua com o mesmo run_id.

Erros

Faturamento

Todos os custos são deduzidos do seu saldo de Créditos de desenvolvedor. Veja o uso e adicione Créditos em www.jenova.ai/platform.

Preços

O custo da Mensagem depende de:

• Modelo - Modelos diferentes têm custos por token diferentes
• Tamanho do contexto - Sessões mais longas consomem mais tokens de entrada por solicitação
• Complexidade do fluxo de trabalho - fluxos de trabalho mais longos e uso intenso de Ferramentas (busca na web, geração de arquivos, análise de documentos) aumentam o consumo total de tokens

O custo real é retornado como stream_ended.usage.cost para solicitações em Transmissão e usage.cost para solicitações JSON não transmitidas.

Retenções de Créditos

Cada solicitação POST /messages, POST /sessions/{session_id}/messages e POST /invoke coloca uma retenção de $0,50 no seu saldo de Créditos antes do início da execução. Isso reserva fundos para a solicitação. Uma Mensagem colocada na fila de uma Execução ativa (202 Accepted com status: "queued") não cria uma retenção adicional; o uso da Execução ativa é verificado em relação ao seu saldo restante.

Quando a solicitação é concluída, a retenção é liquidada pelo custo real e a diferença é liberada. Se o custo real exceder a retenção, a diferença também é cobrada, portanto seu saldo pode ficar abaixo de zero. Solicitações canceladas ou com falha são cobradas apenas pelo uso já incorrido. Se uma solicitação falhar antes de chegar ao Modelo, toda a retenção é liberada.

Por causa das retenções, seu saldo disponível pode parecer temporariamente menor durante solicitações em andamento. Você precisa de pelo menos $0,50 em saldo disponível para uma solicitação POST /sessions/{session_id}/messages, POST /messages efêmera ou POST /invoke. Uma solicitação persistente POST /messages também cria uma Sessão e requer pelo menos $0,51 para cobrir a retenção mais a taxa de criação de Sessão.

Limites de Taxa

Toda conta de desenvolvedor está sujeita a três dimensões de Limite de Taxa:

Uma execução mantém seu slot concorrente até terminar, mesmo após uma resposta 202 Accepted ou a desconexão do cliente. Uma solicitação POST /invoke mantém seu slot até ser concluída, mesmo se o cliente se desconectar.

Solicitações GET e HEAD não consomem slots concorrentes. cancel, undo e mcp/connection/skip também não consomem slots concorrentes, portanto essas operações permanecem disponíveis quando todos os slots estão em uso. Essas solicitações ainda contam para RPM e RPD.

Um limite separado por IP de 1.200 solicitações a cada 60 segundos também se aplica a todas as solicitações e retorna o mesmo erro 429 rate_limit_exceeded.

Cabeçalhos de Resposta

As respostas autenticadas da API incluem cabeçalhos de limite de taxa:

Quando o limite diário é excedido, X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset descrevem a janela diária.

Quando um limite é excedido, a API retorna 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Tratamento de Erros

Erros HTTP imediatos e erros de execução sem transmissão seguem um envelope consistente:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

As mensagens de erro são localizadas com base em lang ou Accept-Language (veja Localização).

Erros de execução em transmissão são entregues como Eventos stream_error. Uma execução com falha ainda pode enviar um Evento final stream_ended com success: false e stop_reason definido. Erros de execução sem transmissão incluem um objeto usage de nível superior; cost é null quando o custo não está disponível.

Estes erros podem ocorrer em qualquer ponto de extremidade:

Erros específicos de cada ponto de extremidade são documentados junto à descrição de cada ponto de extremidade.

Erros de Execução Após o Início

Erros de execução surgem depois que uma solicitação de mensagem foi aceita. No modo de transmissão, eles aparecem como Eventos stream_error e podem ser seguidos por stream_ended com success: false. No modo sem transmissão, eles são retornados como uma resposta de erro em JSON com o Código de Status HTTP abaixo.

Paginação

Listar Sessões e Listar Mensagens usam paginação baseada em cursor:

{
  "items": [],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

Passe next_cursor como o parâmetro de consulta cursor para buscar a próxima página, codificando o valor para URL. Quando has_more for false, não há mais resultados. Um limit fora do intervalo 1-100 ou um cursor inválido retorna 400 bad_request.

Localização

Todos os pontos de extremidade aceitam um parâmetro de consulta opcional lang para controlar o idioma das mensagens de erro e de qualquer conteúdo localizado.

Você pode anexar ?lang=xx a qualquer URL de solicitação:

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

Idiomas suportados: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Privacidade e Dados

A Jenova não usa prompts da API, saídas, histórico de conversas, arquivos enviados, instruções de Agentes ou Bases de Conhecimento para treinar os Modelos da Jenova.

Para provedores de Modelos de terceiros, a Jenova utiliza canais comerciais de API, configurações de conta, compromissos contratuais ou opções de exclusão destinados a impedir que o conteúdo do cliente seja usado para treinar os Modelos do provedor.

A Jenova armazena e processa dados da API usando infraestrutura dos EUA. Provedores terceiros podem processar dados em outras jurisdições, conforme descrito na Política de Privacidade e nos Termos de Uso.

Para mais detalhes, consulte os Termos de Uso, a Política de Privacidade e a Política de Uso.

Suporte

• Painel: www.jenova.ai/platform
• E-mail: [email protected]