Documentação da API

Autenticação

Toda requisição exige uma chave de API no header Authorization. Peça a sua em /desenvolvedores/solicitar — no Pay as you Go o acesso é liberado na hora, sem cartão; o Empresa passa pelo time comercial antes de ativar.

Authorization: Bearer cpk_SUA_CHAVE

A chave completa (formato cpk_ + 48 caracteres) é exibida uma única vez, na criação. Guarde-a em local seguro — no painel fica visível só o prefixo. Se perdê-la, revogue e gere outra.

Exemplo mínimo:

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/marcas"

Agentes de IA (MCP)

Além da API REST abaixo, o catálogo Carpedia está disponível como um servidor MCP (Model Context Protocol) remoto — a mesma forma que agentes de IA (Claude, ChatGPT, Codex) já sabem falar nativamente, sem você escrever nenhum código de integração. Autentica por OAuth (o cliente cuida do login, sem chave) ou pela mesma chave de API da seção anterior — as duas dão o mesmo acesso e contam na mesma cota. Guia de conexão por cliente em /mcp.

Endpoint (Streamable HTTP):

https://develop.carpedia.com.br/api/mcp

A página /mcp recomenda https://mcp.carpedia.com.br/mcp pra clientes de IA — é o mesmo servidor deste endpoint, só num subdomínio dedicado (é lá que mora a descoberta OAuth). Os dois endereços aceitam a mesma autenticação e contam na mesma cota.

As ferramentas

Todas de leitura, sobre o catálogo ou sobre a SUA conta de API — espelhando os endpoints abaixo. carpedia_buscar_versoes aceita um termo de busca livre (ex.: "corolla xei"), sem precisar navegar marca→modelo primeiro — é o atalho pra chegar num fipeId.

Esta tabela reflete o servidor hoje. Depois de conectar, seu cliente MCP pode chamar tools/list — parte padrão do protocolo — pra sempre receber a lista vigente, sem depender desta página.

Conectando

Claude Code:

claude mcp add --transport http carpedia https://develop.carpedia.com.br/api/mcp \
  --header "Authorization: Bearer cpk_SUA_CHAVE"

Codex CLI (~/.codex/config.toml) — o token fica numa variável de ambiente, não no arquivo:

export CARPEDIA_API_KEY=cpk_SUA_CHAVE

# ~/.codex/config.toml
[mcp_servers.carpedia]
url = "https://develop.carpedia.com.br/api/mcp"
bearer_token_env_var = "CARPEDIA_API_KEY"

Responses API (OpenAI) — tool mcp nativa:

{
  "type": "mcp",
  "server_label": "carpedia",
  "server_url": "https://develop.carpedia.com.br/api/mcp",
  "authorization": "cpk_SUA_CHAVE",
  "require_approval": "never"
}

require_approval: "never" é seguro pra todas as ferramentas — nenhuma altera, publica, apaga ou gera cobrança nenhuma; comprar crédito continua existindo, só que pelo painel ou pela API v1, não pelo agente. Os exemplos acima usam a sintaxe vigente na doc oficial de cada cliente no momento em que foram escritos — confira --help/a doc do seu cliente se algo não bater.

Marcas

GET /api/v1/marcas

Lista as marcas do catálogo, com contagem de modelos. Paginada.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/marcas?tipo=Automóveis&pagina=1"

{
  "ref": "09-2026",
  "marcas": [
    { "slug": "jeep", "nome": "Jeep", "tipos": ["Automóveis"], "modelos": 7 }
  ],
  "paginacao": { "pagina": 1, "porPagina": 100, "total": 106, "totalPaginas": 2 }
}

Modelos da marca

GET /api/v1/marcas/{marca}/modelos

Modelos de uma marca, com contagem de versões e a imagem do modelo (foto mais recente do catálogo, ou logo/monograma da marca quando não há foto — ver seção Imagem). Paginada. Use o slug devolvido em /marcas.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/marcas/jeep/modelos"

{
  "ref": "09-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelos": [
    {
      "slug": "compass", "nome": "Compass", "tipos": ["Automóveis"], "versoes": 25,
      "imagem": {
        "tipo": "foto",
        "url": "https://develop.carpedia.com.br/fotos/jeep-compass/2026.webp",
        "ano": "2026",
        "ia": true
      }
    }
  ],
  "paginacao": { "pagina": 1, "porPagina": 100, "total": 7, "totalPaginas": 1 }
}

Versões do modelo

GET /api/v1/modelos/{marca}/{modelo}/versoes

Todas as versões do modelo, com anos-modelo disponíveis, combustíveis e preço de referência (ano mais novo). Sem paginação — o conjunto é limitado por modelo. manual: true marca lançamentos ainda sem código FIPE (id sintético negativo; o precoRef deles vem com estimado: true).

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/modelos/jeep/compass/versoes"

{
  "ref": "09-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelo": { "slug": "compass", "nome": "Compass" },
  "versoes": [
    {
      "id": 170968,
      "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
      "versao": "Black Hurricane 2.0 4x4 TB Aut.",
      "slug": "black-hurricane-2-0-4x4-tb-aut",
      "tipo": "Automóveis",
      "anos": ["0 Km", "2026", "2025"],
      "combustiveis": ["Gasolina"],
      "manual": false,
      "precoRef": { "valor": 273271, "ano": "0 Km", "estimado": false }
    }
  ]
}

Imagem do modelo

GET /api/v1/modelos/{marca}/{modelo}/imagem

Resolve a imagem do modelo com fallback previsível — sempre devolve algo renderizável: a foto do carro quando existir; senão o logo da marca; senão um monograma de 2 letras com uma cor estável, pra você montar um chip quando não houver logo. Mesma lógica exposta no campo imagem de /marcas/{marca}/modelos.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/modelos/jeep/compass/imagem"

Foto encontrada (ano mais recente do catálogo):

{
  "ref": "09-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelo": { "slug": "compass", "nome": "Compass" },
  "imagem": {
    "tipo": "foto",
    "url": "https://develop.carpedia.com.br/fotos/jeep-compass/2026.webp",
    "ano": "2026",
    "ia": true,
    "angulo": "3/4 dianteira"
  }
}

Sem foto, marca com logo cadastrado:

{
  "ref": "09-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "modelo": { "slug": "compass", "nome": "Compass" },
  "imagem": { "tipo": "logo", "url": "https://develop.carpedia.com.br/logos/brands/jeep.webp" }
}

Sem foto e sem logo — monograma pra você renderizar um chip:

{
  "imagem": { "tipo": "monograma", "monograma": "GW", "cor": "#2F5E8C" }
}

As URLs de imagem apontam pra assets públicos e estáticos (/fotos/, /logos/) — a autenticação por chave protege só o JSON da API, não o arquivo em si. ia: true marca foto gerada por IA (rotule ao exibir); quando ausente, é foto de divulgação oficial da montadora.

Preço FIPE

GET /api/v1/preco/{fipeId}

Preços FIPE vigentes da versão (ref. 09-2026), um por ano-modelo — a linha "0 Km" é o veículo novo. Com ?ano=, devolve só o ano pedido e agrega variacao: preço atual, variação mensal (mom) e de 12 meses (m12), em percentual. Versão manual (id negativo): precos: [] e variacao: null.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/preco/170968?ano=2025"

{
  "ref": "09-2026",
  "versao": {
    "id": 170968,
    "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
    "marca": "Jeep",
    "modelo": "Compass"
  },
  "precos": [
    { "ano": "2025", "combustivel": "Gasolina", "valor": 200126 }
  ],
  "variacao": { "atual": 200126, "refAtual": "09-2026", "mom": -0.87, "m12": -6.1 }
}

Histórico de preço

GET /api/v1/historico/{fipeId}/{ano}

Série histórica mensal do preço FIPE da versão×ano-modelo, variação e — quando há base estatística suficiente — projeção de depreciação. A projeção vem sempre rotulada com "estimativa": true: é modelo calculado sobre o histórico do próprio modelo, não dado FIPE.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/historico/170968/2025"

{
  "ref": "09-2026",
  "versao": {
    "id": 170968,
    "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
    "marca": "Jeep",
    "modelo": "Compass"
  },
  "ano": "2025",
  "serie": [
    { "ref": "2024-02", "valor": 259865 },
    { "ref": "2026-06", "valor": 200126 }
  ],
  "variacao": { "atual": 200126, "refAtual": "09-2026", "mom": -0.87, "m12": -6.1 },
  "projecao": {
    "estimativa": true,
    "valorBase": 200126,
    "refBase": "2026-06",
    "pontos": [
      { "ano": 2027, "valor": 186000 },
      { "ano": 2028, "valor": 174000 }
    ],
    "base": "depreciação média observada em 4 anos-modelo do próprio modelo (18 observações)"
  }
}

projecao é omitida quando não há base honesta (modelo novo, série curta). Os pontos são anos-calendário.

Ficha técnica

GET /api/v1/ficha/{fipeId}/{ano}

Ficha técnica da versão×ano em seções (motor, dimensões, equipamentos…), com a fonte do dado quando registrada e o consumo oficial PBEV/Inmetro quando há match auditado. ?resumida=1 devolve o mesmo recorte do bloco principal da página de versão do site.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/ficha/170968/2025"

{
  "ref": "09-2026",
  "versao": {
    "id": 170968,
    "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
    "marca": "Jeep",
    "modelo": "Compass"
  },
  "ano": "2025",
  "fonte": { "fonte": "montadora", "em": "2025-03-10" },
  "secoes": [
    {
      "titulo": "Motor",
      "itens": [
        { "label": "Potência", "valor": "272 cv" },
        { "label": "Torque", "valor": "40,8 kgfm" }
      ]
    }
  ],
  "consumo": {
    "kml_cidade": 9.1,
    "kml_estrada": 10.9,
    "autonomia_km": 520,
    "selo": "A",
    "fonte": "PBEV/Inmetro"
  },
  "porte": {
    "rotulo": "SUV compacto",
    "criterio": "comprimento e carroceria — critério próprio Carpedia, ver /metodologia/porte",
    "comprimento_mm": 4405,
    "carroceria": "SUV"
  },
  "anosDisponiveis": [2026, 2025]
}

fonte, consumo, porte e fotosVersao são omitidos quando não há registro. porte é a classificação PRÓPRIA do Carpedia (comprimento×carroceria) — não a categoria do Anexo D/Inmetro. anosDisponiveis lista os anos com ficha para a mesma versão. Plano de manutenção (revisões programadas) é endpoint separado, abaixo.

Itens de série e opcionais

GET /api/v1/acessorios/{fipeId}/{ano}

Equipamentos da versão×ano agrupados por categoria, na mesma ordem editorial do site. Cada item traz status: serie, opcional ou ausente.

Leia com atenção: a resposta traz apenas os itens que a fonte cobriu para aquela versão×ano. Um item que não aparece na lista é não rastreado — não é afirmação de que o veículo não o possui. Tratar ausência como negação produz informação errada no seu produto.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/acessorios/170968/2025"

{
  "ref": "09-2026",
  "versao": {
    "id": 170968,
    "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
    "versao": "Black Hurricane 2.0 4x4 TB Aut."
  },
  "ano": "2025",
  "observacao": "Só aparecem itens que a fonte cobriu para esta versão/ano. Item ausente da lista significa NÃO RASTREADO — não é afirmação de que o veículo não o possui.",
  "categorias": [
    {
      "categoria": "Segurança e proteção",
      "itens": [
        { "item": "Airbag lateral", "status": "serie" },
        { "item": "Teto solar", "status": "opcional" }
      ]
    }
  ],
  "anosDisponiveis": [2026, 2025]
}

A cobertura de acessórios é independente da ficha técnica — vêm de fontes e anos diferentes, então uma versão pode ter uma sem a outra. anosDisponiveis lista os anos com cobertura de itens.

Plano de manutenção

GET /api/v1/manutencao/{fipeId}/{ano}

Revisões programadas por km (troca/inspeção) da versão×ano — réplica fiel da tabela do manual do proprietário, em secoes: cada seção tem título, colunas de km (e meses, quando o manual imprime as duas), legenda de símbolo e as linhas. Domínio independente da ficha técnica — vem do manual, não do catálogo comercial.

Leia com atenção: dentro de uma linha, um km sem símbolo marcado em acao é não rastreado para aquele km — não é afirmação de que a revisão não é necessária. Rótulo, símbolo e legenda são exatamente como o manual imprime, sem vocabulário próprio do Carpedia.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/manutencao/170968/2025"

{
  "ref": "09-2026",
  "versao": {
    "id": 170968,
    "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut.",
    "versao": "Black Hurricane 2.0 4x4 TB Aut."
  },
  "ano": "2025",
  "observacao": "Réplica fiel da tabela de manutenção programada do manual do proprietário — rótulos, símbolos e legenda tal como o documento imprime, sem vocabulário/dicionário próprio do Carpedia. Km sem marca numa linha do grid (campo `acao`) é NÃO RASTREADO para aquele km, não uma afirmação de que a revisão não é necessária.",
  "secoes": [
    {
      "titulo": "Plano de manutenção normal",
      "colunasKm": [10000, 20000, 30000],
      "legenda": { "S": "Substituir", "I": "Inspecionar" },
      "linhas": [
        { "rotulo": "Óleo do motor", "acao": { "10000": "S", "20000": "S", "30000": "S" } },
        { "rotulo": "Filtro de ar", "acao": { "20000": "I", "30000": "S" } }
      ]
    }
  ],
  "anosDisponiveis": [2025]
}

anosDisponiveis lista os anos com plano de manutenção declarado para a mesma versão.

Resumos editoriais

GET /api/v1/…/resumo

O mesmo texto editorial publicado no site, em três recursos: resumo do modelo, resumo da versão e o verbete da marca. É conteúdo redacional — para especificações use a ficha técnica.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/marcas/jeep"

{
  "ref": "09-2026",
  "marca": { "slug": "jeep", "nome": "Jeep" },
  "fundacao": 1941,
  "origem": "Estados Unidos",
  "chegadaBrasil": 1954,
  "operacao": "Fábrica em Goiana (PE) desde 2015",
  "resumo": "Marca americana nascida do utilitário militar…",
  "confianca": "alta",
  "fontes": ["https://…"]
}

fundacao e chegadaBrasil podem vir null de propósito: ano não confirmado em fonte, ou marca que nunca teve operação oficial no Brasil. É o fato, não dado faltando.

Custo anual de uso

GET /api/v1/custo/{fipeId}/{ano}

Estimativa do custo de um ano de uso: depreciação projetada + IPVA da UF + combustível (ou energia elétrica, em veículo 100% elétrico). Premissa de rodagem: 12.000 km/ano.

Leia o campo rotulo antes de exibir: quando ele vier "ipva_apenas", só o IPVA pôde ser calculado — sem projeção de depreciação e sem consumo. Nesse caso o número não é custo de posse: falta justamente o maior componente, e apresentá-lo como total engana o seu usuário.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/custo/170968/2025?uf=SP"

{
  "ref": "09-2026",
  "versao": { "id": 170968, "nome": "COMPASS Black Hurricane 2.0 4x4 TB Aut." },
  "ano": "2025",
  "uf": "SP",
  "rotulo": "custo_anual",
  "total": 28450.5,
  "componentes": {
    "depreciacao": 18200,
    "ipva": 6150.5,
    "combustivel": 4100,
    "energia": null
  },
  "premissas": {
    "kmAno": 12000,
    "kml": 9.1,
    "kmlOrigem": "pbev",
    "precoLitro": 6.12,
    "combustivel": "gasolina"
  },
  "estimativa": true
}

Componente null significa não foi possível calcular, nunca zero — zero afirmaria que aquele custo não existe. estimativa: true é sempre verdadeiro: a depreciação é projeção estatística do Carpedia, não tabela FIPE oficial.

Vendas 0km (emplacamentos)

GET /api/v1/vendas

Emplacamentos de veículos 0km no mês de referência: ranking dos modelos mais vendidos, ou o recorte de uma marca/modelo específico.

Cuidado com duas leituras: o share e os totais têm como denominador o recorte de veículos leves (automóveis + comerciais leves) do mês — não o mercado inteiro; o campo denominador traz o texto exato para você citar. E o vínculo com o catálogo é por modelo, nunca por versão: modelo: null significa que aquela família não casou com nenhum modelo do catálogo.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/vendas?grupo=autos&porPagina=2"

{
  "ref": "2026-07",
  "mes": {
    "total": 198432,
    "denominador": "emplacamentos de veículos leves (automóveis + comerciais leves) no mês",
    "autos": 168210,
    "eletrificados": 21044
  },
  "limiteRanking": 500,
  "modelos": [
    {
      "fabricante": "FIAT",
      "familia": "STRADA",
      "segmento": "CL - Picape pequena",
      "emplacamentos": 9214,
      "mesAnterior": 8877,
      "modelo": { "marca": "fiat", "modelo": "strada" }
    }
  ],
  "paginacao": { "pagina": 1, "porPagina": 2, "total": 500 }
}

limiteRanking é o teto de famílias consideradas antes da paginação — declarado porque corte silencioso se lê como “isto é tudo”. posicaoNoSegmento, no recorte de modelo, é a posição dentro do segmento dele, com deSegmento dando a base da comparação.

Consumo do mês

GET /api/v1/consumo

Uso e quota da sua própria chave no mês corrente — mesmo número dos headers X-RateLimit-*, como endpoint dedicado pra consultar gasto sem precisar inspecionar headers de outra chamada. Sem parâmetros.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/consumo"

{
  "ref": "09-2026",
  "plano": "pro",
  "requisicoes_usadas": 1284,
  "requisicoes_limite": 5000,
  "requisicoes_restantes": 3716,
  "reseta_em": "2026-09-01T00:00:00.000Z"
}

requisicoes_usadas/restantes vêm null só se a medição estiver momentaneamente indisponível (a chamada em si nunca falha por isso).

Relatório de consumo por período

GET /api/v1/relatorio-consumo

Uso agregado por dia e por rota num período livre (não só o mês corrente) — pra reconciliar consumo com o seu próprio controle de gasto.

curl -H "Authorization: Bearer cpk_SUA_CHAVE" \
  "https://develop.carpedia.com.br/api/v1/relatorio-consumo?inicio=2026-08-01&fim=2026-08-31"

{
  "periodo": { "inicio": "2026-08-01", "fim": "2026-08-31" },
  "total_requisicoes": 842,
  "por_dia": [
    { "dia": "2026-08-01", "rota": "v1/marcas", "requisicoes": 12 },
    { "dia": "2026-08-01", "rota": "v1/preco", "requisicoes": 40 }
  ]
}

Erros

Toda resposta de erro tem o mesmo corpo, com um código estável para tratar por programa (a mensagem pode mudar; o código não):

{
  "erro": {
    "codigo": "quota_mensal",
    "mensagem": "Quota mensal do plano excedida. Renova em 2026-08-01.",
    "status": 429
  }
}

Limites e planos

Cada plano tem uma quota mensal (teto duro) e um preço de excedente por consulta acima dela, cobrado do seu saldo de crédito avulso. Toda resposta de sucesso traz o estado da quota mensal nos headers:

X-RateLimit-Limit: 100         # limite mensal do plano
X-RateLimit-Remaining: 87      # restante no mês (pode atrasar até 60 s)
X-RateLimit-Reset: 1754006400  # epoch UTC do dia 1º do mês seguinte

Além da quota mensal, existe um teto técnico de proteção de 300 requisições por minuto, igual para todos os planos — não é um diferencial comercial, é proteção contra picos e abuso. Ao estourá-lo, a resposta 429 (limite_minuto) inclui Retry-After: 60.

Estourou a quota e não tem saldo? A resposta é 402 saldo_insuficiente — compre crédito avulso (R$ 20, R$ 50, R$ 100, R$ 500, R$ 1.000 ou R$ 2.000 — Pix ou cartão) a qualquer momento pelo painel. Também dá para comprar por Pix diretamente pela API (POST /api/v1/creditosdevolve o código copia-e-cola; GET /api/v1/creditos/{id} acompanha o pagamento). Essas rotas não consomem a franquia mensal, mas respeitam o teto de 300 requisições por minuto e o limite de 5 cobranças por hora; enquanto a compra self-service não estiver liberada no ambiente, respondem 503 indisponivel. Pelo MCP, só carpedia_status_credito existe — consulta uma cobrança já criada pelo painel ou pela API v1; não há ferramenta MCP para criar uma nova (o servidor MCP é 100% leitura).

Para assinar ou trocar de plano pago, veja os planos.