Desenvolvedores

API pública, MCP e markdown

O catálogo de 2267 rótulos que está em /vinhos também sai por máquina: uma API REST somente leitura, uma descrição OpenAPI 3.1, um servidor MCP e a versão em markdown de qualquer página deste site. Nada disso pede cadastro, chave ou contrato.

Autenticação

Não há. A API é pública, somente leitura e não tem chave para pedir: GET e pronto. Ela serve o mesmo agregado que as páginas públicas — nota média, preço mediano, safras, uvas e região — e não expõe nenhum dado de conta. A adega de uma pessoa continua saindo só em /adega/<handle>, e só depois que ela mesma liga o interruptor no app.

Endpoints

Base: https://minhaadegaonline.com. Descrição completa, com parâmetros tipados e esquemas de resposta, em /openapi.json.

Metadados e facetas

curl -s https://minhaadegaonline.com/api/v1/catalog

Devolve o tamanho do catálogo, a data do snapshot e os valores que existem para cada filtro (tipos, países e uvas, com a contagem de rótulos). Chame antes de filtrar, em vez de adivinhar o valor.

Listar e filtrar rótulos

curl -s "https://minhaadegaonline.com/api/v1/wines?q=malbec&country=Argentina&sort=rating&limit=5"

Parâmetros: q (texto livre em nome, produtor, região, país e uvas, ignorando acento), type, country (nome ou ISO de duas letras), region, grape, sort (popularity, rating, price, name), limit (1 a 100, padrão 20) e offset. A resposta traz pagination.next já montado — pagine por ele.

Ficha de um rótulo

curl -s https://minhaadegaonline.com/api/v1/wines/dv-catena-cabernet-sauvignon

Acrescenta à listagem a distribuição das notas, os quartis de preço com o tamanho da amostra e a harmonização quando cadastrada. O slug é o mesmo da página pública em /vinhos/<slug>.

Como ler os números

rating.average é a média das notas dadas por quem registrou o consumo no app, e rating.count é quantas notas entraram nela. Sem avaliação, os dois vêm null e 0 — nunca preenchidos por estimativa.
price.median é a mediana em reais dos preços que os usuários informaram ao cadastrar a garrafa, no varejo brasileiro. p25 e p75 delimitam a metade central e sampleSize diz de quantos preços saiu. Amostra pequena vem declarada em vez de escondida.
vintages são as safras que apareceram na base, da mais recente para a mais antiga — não é a lista do que o produtor já engarrafou.
popularity.users é quanta gente tem ou teve o rótulo cadastrado. É o critério do sort=popularity.

Limites de uso

120 requisições por 60 segundos, por IP. Toda resposta traz a cota em campo estruturado IETF e na forma antiga:

RateLimit: "publico";r=118;t=42
RateLimit-Policy: "publico";q=120;w=60
RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 42

Ao estourar, a resposta é 429 com Retry-After em segundos. A contagem é feita em cada ponto de presença da Cloudflare que atende você, e não num contador central: um cliente distribuído por várias regiões consegue mais que a cota no total. Preferimos dizer isso a fingir precisão que o serviço não tem — se você precisa de mais que isso de forma sustentada, escreva em vez de contornar.

Erros

Todo erro sai no formato da RFC 9457, com content-type: application/problem+json. Decida pelo campo code, que é estável; title e detail são texto e podem mudar.

{
  "type": "https://minhaadegaonline.com/docs#erro-wine-not-found",
  "title": "Rótulo não encontrado",
  "status": 404,
  "detail": "Não existe rótulo com o slug \"xyz\" no catálogo público.",
  "instance": "https://minhaadegaonline.com/api/v1/wines/xyz",
  "code": "wine_not_found",
  "resolution": "Busque pelo nome em /api/v1/wines?q=<termo>.",
  "documentation_url": "https://minhaadegaonline.com/docs#erros"
}

code	HTTP	Quando acontece	O que fazer
`invalid_limit`	400	limit não é inteiro, ou está fora de 1–100.	Corrija o valor. O padrão é 20.
`invalid_offset`	400	offset não é inteiro maior ou igual a zero.	Use o campo pagination.next da resposta em vez de montar o offset à mão.
`invalid_sort`	400	sort recebeu valor fora da lista.	Use popularity, rating, price ou name.
`invalid_slug`	400	O slug tem caractere fora de [a-z0-9-].	Obtenha o slug de uma listagem em vez de derivá-lo do nome.
`wine_not_found`	404	O slug é válido, mas não há rótulo com ele no catálogo público.	Busque pelo nome com ?q=. Rótulo sem uso real registrado não entra no catálogo público.
`unknown_endpoint`	404	O caminho abaixo de /api/v1 não existe.	Confira os caminhos publicados em /openapi.json.
`unknown_version`	404	A versão no caminho não é v1.	A única versão publicada é v1.
`method_not_allowed`	405	Verbo diferente de GET, HEAD ou OPTIONS.	A API é somente leitura. Não existe endpoint de escrita.
`rate_limited`	429	A cota da janela corrente estourou.	Espere o que disser Retry-After. Leia RateLimit antes de estourar.
`catalog_unavailable`	503	O snapshot do catálogo não pôde ser lido.	Repita em alguns segundos; o catálogo continua legível em HTML e markdown.

Servidor MCP

Endpoint Streamable HTTP em https://minhaadegaonline.com/mcp, sem autenticação, só POST. Ferramentas: search_wines (busca com os mesmos filtros da listagem), get_wine (ficha completa por slug) e get_site_guide (o que este site é e quando usá-lo). O cartão do servidor está em /.well-known/mcp/server-card.json.

claude mcp add --transport http minha-adega https://minhaadegaonline.com/mcp

Markdown

Qualquer página pública deste site responde em markdown limpo, sem layout nem script, de duas formas: pelo cabeçalho Accept: text/markdown ou acrescentando .md ao caminho. As respostas trazem Vary: Accept, então cache intermediário não mistura as duas representações.

curl -s -H "Accept: text/markdown" https://minhaadegaonline.com/vinhos
curl -s https://minhaadegaonline.com/vinhos.md

Descoberta

/llms.txt — guia do site, com quando usar e quando não usar.
/openapi.json — OpenAPI 3.1.
/.well-known/api-catalog — catálogo de APIs da RFC 9727.
/?mode=agent — a home em forma de resumo para agente.
/sitemap.xml — todas as páginas indexáveis.

Versões e depreciação

A versão corrente é v1, no caminho. Campo novo pode aparecer numa resposta a qualquer momento — trate campo desconhecido como ignorável. Remoção de campo, mudança de significado ou saída de endpoint só acontecem em uma versão nova de caminho (/api/v2/…), e a anterior continua respondendo por pelo menos seis meses depois do anúncio, com Deprecation e Sunset nos cabeçalhos. Mudanças ficam registradas aqui.

A mesma política em forma de dado está em /openapi.json, no bloco x-api-lifecycle — quem precisa decidir se pode integrar lê campos, não parágrafo.

Deprecation and sunset policy (English). The current major version is v1, carried in the URL path. Breaking changes only ship as a new major version path (/api/v2/…). When a version is deprecated it keeps answering for at least 180 days after the announcement, carrying Deprecation and Sunset response headers (RFC 9745 and RFC 8594) for the whole period. Additive fields may appear in v1 responses at any time — treat unknown fields as ignorable. Nothing is deprecated today, so no such header is being sent.

O que é permitido

O robots.txt deste site declara Content-Signal: search=yes, ai-input=yes, ai-train=no: indexar, citar e usar como fonte em resposta gerada é liberado; treinar ou ajustar modelo com este conteúdo não é. Ao citar, atribua a Minha Adega Online e prefira o link da página do rótulo. Os termos de uso valem para a API como valem para o site.