---
title: API e recursos para desenvolvedores — agrolider.app
description: Documentação da API do agrolider.app: autenticação, endpoints, especificação OpenAPI, llms.txt e versões em markdown das páginas públicas.
canonical: https://agrolider.app/docs/api
---

# API do agrolider.app — recursos para desenvolvedores e agentes

**Especificação:** [openapi.json](/openapi.json) (OpenAPI 3.1) · **Índice para agentes:** [llms.txt](/llms.txt) · **Mapa do site:** [sitemap.xml](/sitemap.xml)

O agrolider.app é uma plataforma de gestão agronômica: propriedades e glebas georreferenciadas, análise de solo interpretada, calagem e receituários técnicos em PDF. Esta página descreve a superfície HTTP pública em https://agrolider.app. Ainda não há chaves de API para terceiros: os endpoints de dados usam a sessão do usuário e os de integração usam segredos próprios.

## Autenticação

| Mecanismo | Endpoints | Como |
| --- | --- | --- |
| Sessão (cookies do Supabase Auth) | `/api/properties`, `/api/search` | Faça login em [/login](/login) por e-mail/senha ou Google; o navegador envia os cookies `sb-*`. Sem sessão: `401 {"error":"não autenticado"}`. |
| Token do webhook | `/api/webhooks/asaas` | Header `asaas-access-token`, configurado no painel do Asaas. |
| Bearer do cron | `/api/cron/news` | `Authorization: Bearer <CRON_SECRET>`, enviado pelo GitHub Actions. |
| Nenhuma | `/api/health` | Monitor de disponibilidade. |

## Endpoints

| Método | Caminho | Auth | O que faz |
| --- | --- | --- | --- |
| GET | `/api/health` | nenhuma | `{"ok":true}` quando função e banco respondem; `503 {"ok":false}` se o banco cair. |
| GET | `/api/properties` | sessão | Lista as propriedades ativas da organização, mais recentes primeiro. |
| POST | `/api/properties` | sessão | Cria uma propriedade (`name`, `stateUf`; opcionais `city`, `lat`, `lon`, `areaHa`). `201 {"id"}`; `400` no limite do plano. |
| GET | `/api/search?q=` | sessão | Busca propriedades, glebas e análises pelo termo (2 a 100 caracteres). `429` acima de 20 buscas em 10 s. |
| POST | `/api/webhooks/asaas` | token | Recebe eventos de pagamento; responde `{"status":"processed"\|"duplicate"\|"ignored"}`. |
| POST | `/api/cron/news` | bearer | Roda o pipeline de notícias do blog; `500` em falha total. |

Tipos, exemplos e códigos de resposta completos estão no [openapi.json](/openapi.json).

## Exemplos

```bash
curl https://agrolider.app/api/health
# {"ok":true}

# Com a sessão salva pelo navegador (cookies sb-*):
curl -b cookies.txt "https://agrolider.app/api/search?q=fazenda"
```

## Conteúdo em markdown para agentes

Toda página pública responde em markdown quando o cliente prefere `text/markdown` (acceptmarkdown.com) e também pelo sufixo `.md`:

```bash
curl -H "Accept: text/markdown" https://agrolider.app/blog
curl https://agrolider.app/blog.md
```

As respostas trazem `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept` e um header `Link` com a URL canônica em HTML. Caminhos inexistentes respondem `404` (em HTML ou markdown, conforme o `Accept`) com um corpo curto apontando os índices; um `Accept` sem tipo servível responde `406`. Páginas com versão em markdown: início (`/index.md`), `/blog.md`, cada post (`/blog/<slug>.md`), `/termos.md`, `/privacidade.md` e `/docs/api.md`.

## Limites e erros

Toda rota que limita devolve os headers `RateLimit-*` do RFC em **todas** as respostas, não só no `429` — dá para ler o teto antes de bater nele:

```http
RateLimit-Limit: 60
RateLimit-Remaining: 59
RateLimit-Reset: 60
RateLimit-Policy: 60;w=60
```

`RateLimit-Reset` conta os segundos até a vaga mais antiga sair da janela (é deslizante, não um bloco fixo). No `429` vem também `Retry-After` com o mesmo número.

| Rota | Teto | Chave |
| --- | --- | --- |
| `/api/mcp` | 60 por minuto | IP |
| `/api/search` | 20 por 10 s | usuário |
| `/api/health` | 120 por minuto | IP |

Rota sem limite não manda os headers: anunciar teto onde não existe é mentir para o cliente.

**Erros.** Toda resposta `4xx`/`5xx` tem forma declarada no [openapi.json](/openapi.json). Os endpoints REST usam `{"error": "..."}`; o `/api/mcp` usa o envelope do próprio JSON-RPC (`{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"...","data":{...}}}`), para o cliente reaproveitar a leitura que já faz.

- Propriedades: limite por plano — `400` com `"Property limit reached (atual/máximo)"`. Planos e preços estão na [página inicial](/#planos).
- Erros nunca ecoam detalhes internos; a mensagem é a mesma para humanos e agentes.

## Servidor MCP

`POST https://agrolider.app/api/mcp` — Model Context Protocol sobre Streamable
HTTP, stateless e **sem autenticação**: só leitura, e só de dado público.
Quatro ferramentas:

| Ferramenta | Faz |
| --- | --- |
| `interpretar_analise_solo` | SB, CTC a pH 7, V% e classe de fertilidade a partir dos valores do laudo |
| `calcular_calagem` | necessidade de calcário (t/ha) pela saturação por bases |
| `calcular_gesso` | necessidade de gesso (kg/ha) pelo teor de argila, com o fator do ciclo |
| `listar_noticias` | as manchetes publicadas em /blog, com link e data |

As três calculadoras são funções puras — sem banco, sem custo e sem dado de
usuário — e devolvem a fórmula aplicada e a fonte citada junto do número.
Propriedades, glebas, laudos salvos e a busca no acervo técnico **não** estão
expostos: exigem sessão, e a busca no acervo gasta uma chamada paga por consulta.

Para configurar num cliente MCP:

```json
{ "mcpServers": { "agrolider": { "type": "streamable-http", "url": "https://agrolider.app/api/mcp" } } }
```

Uma mensagem JSON-RPC 2.0 por requisição (`initialize`, `ping`, `tools/list`,
`tools/call`). `GET` responde `405`: não há stream SSE. Notificação (mensagem
sem `id`) responde `202` sem corpo. Limite de 60 chamadas por minuto por IP.

```bash
curl -s https://agrolider.app/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Descoberta

- [llms.txt](/llms.txt) — índice curado para agentes, com as versões `.md`.
- [sitemap.xml](/sitemap.xml) — todas as URLs públicas, incluindo cada post do blog.
- [robots.txt](/robots.txt) — o que pode ser rastreado.
- [openapi.json](/openapi.json) — esta API em formato de máquina.
- [.well-known/ard.json](/.well-known/ard.json) — catálogo ARD: os recursos acima e o servidor MCP.

## Contato

Dúvidas sobre a API ou este site: `suporte@agrolider.app`.