Quatro endpoints novos para ler e estruturar a web

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.

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.

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.

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:

{
  "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.

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.

Limites#

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.

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: é essa lista que estamos usando para decidir o que vem a seguir.