Exemplos - EnemHub API

Todos os exemplos assumem a chave em ENEMHUB_API_KEY e a base https://api.enemhub.com.br.

Filtrar questões

GET /v1/enem/questions aceita quatro filtros, todos opcionais e combináveis:

Parâmetro	Tipo	Observação
`year`	inteiro	Ano do exame, ex. `2023`.
`subjectId`	uuid	ID da matéria. Vem no campo `subject.id` de qualquer questão.
`difficulty`	`Fácil` \| `Média` \| `Difícil`	Nível de dificuldade, em português — é o valor que sai em `difficulty` na própria questão.
`page`	inteiro	Começa em `1`. Padrão `1`.
`limit`	inteiro	De `1` a `100`. Padrão `20`.

Questões difíceis de 2023

curl -G https://api.enemhub.com.br/v1/enem/questions \
  -H "X-API-Key: $ENEMHUB_API_KEY" \
  -d year=2023 \
  --data-urlencode difficulty=Difícil \
  -d limit=50

Não existe endpoint para listar matérias no produto ENEM. Para descobrir um subjectId, puxe uma página de questões e leia o subject.id — os IDs são estáveis.

Paginar até o fim

meta.total é a contagem do conjunto filtrado inteiro, então dá para calcular o número de páginas antes de começar:

const BASE = "https://api.enemhub.com.br/v1/enem/questions";
const headers = { "X-API-Key": process.env.ENEMHUB_API_KEY };

async function todasAsQuestoes(filtros = {}) {
  const limit = 100; // o máximo aceito — menos páginas, menos requisições
  const todas = [];

  for (let page = 1; ; page++) {
    const query = new URLSearchParams({ ...filtros, page, limit });
    const res = await fetch(`${BASE}?${query}`, { headers });

    if (!res.ok) throw new Error(`${res.status} ao buscar a página ${page}`);

    const { data, meta } = await res.json();
    todas.push(...data);

    if (todas.length >= meta.total || data.length === 0) return todas;
  }
}

const questoes = await todasAsQuestoes({ year: 2023 });

limit=100 é o teto. Puxar o acervo inteiro a 20 por vez custa cinco vezes mais requisições da sua cota do que a 100 por vez.

Buscar uma questão específica

Diferente da listagem, esta rota devolve a questão sem envelope:

curl https://api.enemhub.com.br/v1/enem/questions/9f3c1a2e-... \
  -H "X-API-Key: $ENEMHUB_API_KEY"

Um ID que não existe — ou que pertence a um exame fora do produto ENEM — devolve 404:

{ "error": "Questão não encontrada" }

Estrutura da resposta

Cada questão retornada contém os seguintes campos:

Exemplo completo de uma questão

{
  "id": "f1ee873f-4a2b-4c8d-9e1f-123456789abc",
  "year": 2019,
  "difficulty": "Média",
  "statement": "<p>A parábola representada a seguir intersecta os eixos coordenados nos pontos A (1, 0), B (−1, 0) e C (0, −1).</p><figure class=\"image\"><img src=\"https://img.enemhub.com.br/images/questions/411957/aHR0cHM6Ly9h.png\"></figure><p>Essa parábola é o gráfico da função quadrática f definida pela seguinte sentença:</p>",
  "correctAlternative": "A",
  "exam": {
    "id": "3b1e7c9a-5d2f-4a8b-9c3e-456789abcdef",
    "name": "ENEM 2019",
    "institution": "INEP"
  },
  "subject": {
    "id": "a1b2c3d4-5e6f-7a8b-9c0d-ef1234567890",
    "name": "Matemática",
    "area": "Matemática e suas Tecnologias"
  },
  "alternatives": [
    { "id": "...", "letter": "A", "text": "f(x) = x² − 1", "isCorrect": true },
    { "id": "...", "letter": "B", "text": "f(x) = x² + 1", "isCorrect": false },
    { "id": "...", "letter": "C", "text": "f(x) = −x² − 1", "isCorrect": false },
    { "id": "...", "letter": "D", "text": "f(x) = −x² + 1", "isCorrect": false },
    { "id": "...", "letter": "E", "text": "f(x) = x² − x − 1", "isCorrect": false }
  ]
}

Campo	Tipo	Descrição
`id`	uuid	Identificador único da questão.
`year`	inteiro	Ano da prova.
`difficulty`	`Fácil` \| `Média` \| `Difícil`	Nível de dificuldade.
`statement`	string (HTML)	Enunciado da questão. Pode conter imagens embutidas — veja a seção abaixo.
`correctAlternative`	string \| null	Letra da alternativa correta (`A`, `B`, `C`, `D` ou `E`).
`exam.id`	uuid	Identificador do exame.
`exam.name`	string	Nome do exame, ex. `ENEM 2023`.
`exam.institution`	string \| null	Instituição responsável, ex. `INEP`.
`subject`	object \| null	Matéria da questão (pode ser `null` se não categorizada).
`subject.id`	uuid	Identificador da matéria.
`subject.name`	string	Nome da matéria, ex. `Matemática`.
`subject.area`	string \| null	Área de conhecimento, ex. `Ciências da Natureza e suas Tecnologias`.
`alternatives`	array	Lista de alternativas, ordenadas por letra.
`alternatives[].id`	uuid	Identificador da alternativa.
`alternatives[].letter`	string	Letra da alternativa (`A` a `E`).
`alternatives[].text`	string	Texto da alternativa (sempre texto puro, sem imagens).
`alternatives[].isCorrect`	boolean	`true` se esta é a alternativa correta.

Na listagem (GET /v1/enem/questions), a resposta vem dentro de um envelope { "data": [...], "meta": { "page", "limit", "total" } }. Na busca por ID (GET /v1/enem/questions/:id), a questão vem diretamente, sem envelope.

`statement` é HTML, não texto puro

Cerca de 1 em cada 3 questões tem imagem — mas não existe um campo imageUrl separado para ela. A imagem vem embutida no HTML do próprio statement, como <figure><img src="..."></figure> no meio dos parágrafos:

{
  "id": "f1ee873f-...",
  "statement": "<p>A parábola representada a seguir intersecta os eixos coordenados nos pontos A (1, 0), B (−1, 0) e C (0, −1).&nbsp;</p><figure class=\"image\"><img src=\"https://img.enemhub.com.br/images/questions/411957/aHR0cHM6Ly9h.png\"></figure><p>Essa parábola é o gráfico da função quadrática f definida pela seguinte sentença:</p>",
  "correctAlternative": "A"
}

Renderize statement como HTML (sanitizado), não como texto — se você jogar o valor cru num nó de texto, o cliente mostra as tags em vez da questão. text das alternativas, por outro lado, é sempre texto puro: nenhuma alternativa tem imagem embutida.

import DOMPurify from "dompurify";

function renderEnunciado(questao) {
  // Sanitize antes de injetar — statement vem do seu próprio banco, mas é
  // HTML mesmo assim, e dangerouslySetInnerHTML/innerHTML sem sanitizar é
  // superfície de XSS por padrão.
  return DOMPurify.sanitize(questao.statement);
}

Montar uma prova

Correta e alternativas vêm juntas na resposta, então embaralhar e esconder o gabarito é trabalho do seu lado:

function paraOAluno(questao) {
  return {
    id: questao.id,
    enunciado: questao.statement, // já vem com a imagem embutida, se houver
    // `isCorrect` e `correctAlternative` ficam de fora — o gabarito não desce
    // para o cliente.
    alternativas: questao.alternatives.map(({ id, letter, text }) => ({
      id, letra: letter, texto: text,
    })),
  };
}

function corrigir(questao, alternativaId) {
  return questao.alternatives.find((a) => a.id === alternativaId)?.isCorrect ?? false;
}

Lidar com limites

Toda resposta de /v1/* traz dois headers:

Header	Significado
`X-RateLimit-Limit`	Requisições por minuto permitidas pelo seu plano.
`X-RateLimit-Remaining`	Quantas ainda cabem no minuto corrente.

Ao estourar, a resposta é 429 com Retry-After: 60. São três limites independentes:

Por minuto — definido pelo plano.
Por dia — também definido pelo plano, em torno de 3× a média diária da cota mensal.
Por mês — a cota do plano. Ao estourar, a mensagem pede upgrade.

Uma requisição recusada com 429 não consome cota mensal. Estourar o limite por minuto não queima o seu volume contratado.

Retry com backoff

async function comRetry(url, init, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;

    const espera = Number(res.headers.get("Retry-After") ?? 60);
    await new Promise((r) => setTimeout(r, espera * 1000));
  }
  throw new Error("Rate limit persistente após 3 tentativas");
}

Tratar erros

Status	`error`	Quando acontece
`401`	`Unauthorized`	Header `X-API-Key` ausente, ou chave inválida, revogada ou expirada.
`403`	`Forbidden`	A chave é de outro produto, ou a organização não tem assinatura ativa.
`404`	—	O recurso não existe, ou não pertence ao produto da sua chave.
`429`	`Too Many Requests`	Estourou o limite por minuto, por dia ou a cota mensal do plano.
`500`	—	Erro interno. Se persistir, fale com o suporte.

O corpo do erro não é uniforme em toda a API — documentamos o que existe hoje, não o que gostaríamos que existisse.As rotas de gestão devolvem { "error", "message", "statusCode" }. Os erros de autenticação e de rate limit devolvem { "error", "message" }, sem statusCode. E o 404 das rotas de questão devolve só { "error": "Questão não encontrada" }.Ou seja: trate pelo status HTTP, que é consistente, e use error / message apenas para exibir ou registrar em log.

Um wrapper que cobre o caso comum:

async function enemhub(caminho, params = {}) {
  const query = new URLSearchParams(params);
  const res = await fetch(`https://api.enemhub.com.br${caminho}?${query}`, {
    headers: { "X-API-Key": process.env.ENEMHUB_API_KEY },
  });

  if (res.ok) return res.json();

  // Trate pelo status: o corpo do erro não tem formato único na API.
  const corpo = await res.json().catch(() => ({}));
  throw Object.assign(
    new Error(corpo.message ?? corpo.error ?? `HTTP ${res.status}`),
    { status: res.status },
  );
}

​Filtrar questões

​Paginar até o fim

​Buscar uma questão específica

​Estrutura da resposta

​statement é HTML, não texto puro

​Montar uma prova

​Lidar com limites

​Tratar erros

Filtrar questões

Paginar até o fim

Buscar uma questão específica

Estrutura da resposta

`statement` é HTML, não texto puro

Montar uma prova

Lidar com limites

Tratar erros