# Quatro endpoints novos para ler e estruturar a web

**Publicado:** 9 de agosto de 2026 | **Autores:** Cristian Correa

---

A API da Croma não responde mais só por fontes oficiais. A partir de hoje, você pode passar uma URL ou uma pergunta e receber conteúdo pronto para usar no seu produto.

São quatro endpoints, todos sob `/global`, todos com o mesmo esquema de autenticação e de erros do resto da API.

## Extrair uma página como markdown

`POST /global/extract/markdown/v1` devolve o conteúdo legível de uma página, sem navegação, sem banners e sem scripts.

```bash
curl https://api.croma.run/global/extract/markdown/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ejemplo.gov.co/resolucion-1234",
    "scope": "main"
  }'
```

`scope` aceita `main` para ficar só com o corpo do artigo, ou `full` quando você precisa da página inteira. O guia completo está em [extract](https://docs.usecroma.com/pt/guides/global/extract).

## Extrair campos com um schema

`POST /global/extract/json/v1` recebe um JSON Schema e devolve exatamente esses campos. Útil quando você já sabe do que precisa e não quer fazer parsing de texto.

```bash
curl https://api.croma.run/global/extract/json/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ejemplo.gov.co/resolucion-1234",
    "json_schema": {
      "type": "object",
      "properties": {
        "numero": { "type": "string" },
        "fecha": { "type": "string" },
        "entidad": { "type": "string" }
      },
      "required": ["numero", "fecha"]
    }
  }'
```

Se o schema não for válido, a resposta é um `400` que nomeia o campo, não um erro genérico:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param",
    "param": "json_schema",
    "message": "`json_schema` was rejected. It must be a valid JSON Schema object describing the fields you want."
  }
}
```

## Gerar dados estruturados

`POST /global/generate/json/v1` não precisa de URL. Você passa uma instrução e um schema, e ele devolve o objeto. Os detalhes estão em [generate](https://docs.usecroma.com/pt/guides/global/generate).

## Pesquisa com fontes

`POST /global/research/v1` recebe uma pergunta e devolve um relatório com as fontes que consultou e quantas páginas analisou. É o endpoint mais lento da API e tem um limite próprio, explicado em [research](https://docs.usecroma.com/pt/guides/global/research).

## Limites

| Endpoint | Limite por organização |
| --- | --- |
| `/global/extract/markdown/v1` | 60 requisições / hora |
| `/global/extract/json/v1` | 60 requisições / hora |
| `/global/generate/json/v1` | 60 requisições / hora |
| `/global/research/v1` | 10 requisições / hora |

Os quatro também estão disponíveis como ferramentas MCP, então seu assistente pode chamá-los sem que você escreva código. A referência completa está na [documentação](https://docs.usecroma.com/pt).

## Por que eles ficam na mesma API

Consultar um registro público quase nunca é o trabalho completo. Você encontra a resolução e depois ainda precisa lê-la, tirar três campos dela, resumi-la e cruzá-la com o que já tinha. Essa parte quase sempre acaba resolvida com um fornecedor à parte: outra chave, outro contrato, outro formato de erro, outra fatura.

Achamos que não precisa ser assim. Você já tem uma chave nossa e já sabe como respondemos quando algo dá errado. Esses quatro endpoints usam exatamente isso: o mesmo `Authorization`, o mesmo esquema de erros, os mesmos limites por organização. Integrá-los é ler uma página de documentação, não abrir uma avaliação de fornecedores.

Essa é a vantagem real de termos construído isso nós mesmos. Cada capacidade que adicionamos entra pela mesma porta e serve a tudo o que você já tem conectado, em vez de ser mais uma peça para manter.

Vamos seguir por esse caminho. Se existe algo que hoje você resolve com um serviço à parte e que faria sentido pedir à mesma API, [conte para a gente](/support): é essa lista que estamos usando para decidir o que vem a seguir.

---

**Mais novidades:** [Ver todas as entradas do changelog](/pt/changelog/sitemap.md) | [Croma](https://usecroma.com)