# Search API

API de pesquisa web para apps e agentes: search, extract, crawl, map e pedidos em paralelo, cobrados do saldo da empresa.

Fonte: https://ardumaker.com/pt/docs/search-api/

- Categoria: Inteligência artificial e agentes
- Estado: Disponível
- Requisitos: Um token Search API da empresa (criado por um admin); Meio de pagamento ativo e pelo menos 20 EUR de saldo para criar o token; A empresa em dia com os pagamentos para o usar
- Ferramentas MCP (Só leem): `listar_tokens_search_api`, `ver_token_search_api`, `ver_costos_operaciones_search_api`
- Ferramentas MCP (Escrevem ou modificam): `crear_token_search_api`, `revocar_token_search_api`, `reactivar_token_search_api`

## O que permite fazer?

- **search**: pesquisar na web e receber resultados com título, URL, conteúdo e pontuação, opcionalmente com uma resposta resumida.
- **extract**: obter o conteúdo de um ou vários URL em Markdown ou texto.
- **crawl**: percorrer um site a partir de um URL, com profundidade e amplitude configuráveis, e extrair o conteúdo.
- **map**: listar os URL de um site sem extrair conteúdo.
- **multiple**: correr até 10 dos anteriores em paralelo e receber as respostas na mesma ordem.

## Quando convém usar?

- Dar a um agente de IA acesso a informação atual da web.
- Alimentar uma base de conhecimento com o conteúdo de um site.
- Pagar a pesquisa a partir do saldo da empresa sem contratar outro fornecedor.

## Como funciona na ArduMaker?

1. A aplicação faz `POST` para `https://api.ardumaker.com/api/v1/searchapi/<operação>/` com o token no header `Authorization` (o valor do token, sem prefixo).
2. A ArduMaker valida o token: tem de existir, estar ativo e a empresa não pode estar suspensa por pagamentos pendentes.
3. O pedido é reencaminhado para um fornecedor de pesquisa externo com os parâmetros recebidos e devolve-se a sua resposta.
4. Soma-se o custo da operação ao token (com a comissão da empresa). Quando o acumulado por registrar chega a 1 EUR, é descontado do saldo da empresa.

```bash
curl -X POST https://api.ardumaker.com/api/v1/searchapi/search/ \
  -H "Authorization: $SEARCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "novedades de energía solar", "max_results": 5, "include_answer": true}'
```

### Como se calcula o custo

| Operação | Unidade de cobrança |
| --- | --- |
| search | Por pedido; `search_depth: advanced` custa mais |
| extract | Por URL; `extract_depth: advanced` custa mais |
| crawl | Por cada 5 páginas do `limit` pedido (50 por padrão); `advanced` custa mais |
| map | Por cada 10 páginas do `limit` pedido; com `instructions`, o dobro |

Os preços em vigor consultam-se sem autenticação em `GET /api/v1/searchapi/pricing/` e podem mudar. Um pedido que chega ao fornecedor é cobrado mesmo que o fornecedor responda com erro; um rejeitado antes (sem `query` ou sem `url`) não.

## O que muda realmente?

- No token: contadores de pedidos e custo, totais e das janelas de 24 horas, 7 dias e 30 dias.
- No histórico da empresa: um consumo sempre que o acumulado chega a 1 EUR, e o pendente ao revogar o token.
- Se a empresa ficar pendente de verificação de identidade, os seus tokens são pausados até ser verificada.

## Parâmetros principais

| Operação | Campo obrigatório | Alguns opcionais |
| --- | --- | --- |
| `search` | `query` | `search_depth`, `max_results`, `topic`, `time_range`, `include_answer`, `include_raw_content`, `include_domains`, `exclude_domains` |
| `extract` | `urls` | `query`, `extract_depth`, `format`, `include_images` |
| `crawl` | `url` | `instructions`, `max_depth`, `max_breadth`, `limit`, `select_paths`, `exclude_paths`, `allow_external` |
| `map` | `url` | `instructions`, `max_depth`, `max_breadth`, `limit`, `allow_external` |
| `multiple` | `requests` | Cada elemento leva `type` e os campos da sua operação |

Os parâmetros opcionais são reencaminhados tal como estão para o fornecedor.

## Esquema

**Um pedido de pesquisa**

```text
A sua app ou agente (token em Authorization)
  ↓
Search API (valida token e estado de pagamentos)
  ↓
Fornecedor de pesquisa (search, extract, crawl ou map)
  ↓
Custo (soma-se ao token; registra-se a cada 1 EUR)
```

## Resultado esperado

- A resposta é a do fornecedor: `results`, e conforme a operação `answer`, `failed_results`, `base_url` e `response_time`.
- `multiple` devolve uma resposta por pedido, na mesma ordem; os que falham vão com o seu erro.
- `ver_costos_operaciones_search_api` mostra o gasto de todos os tokens ativos (total e de 24 horas, 7 e 30 dias) e os preços por operação.

## Erros e resolução

| Resposta | Causa | O que fazer |
| --- | --- | --- |
| 403 `authorization_token_required` | Falta o header `Authorization` | Enviar o token |
| 403 `invalid_or_inactive_token` | Token inexistente, revogado ou pausado | Rever o token ou reativá-lo |
| 402 `service_suspended_due_to_pending_payment` | A empresa tem pagamentos pendentes | Regularizar o saldo |
| 400 `query is required` / `url is required` / `urls is required` | Falta o campo obrigatório (não é cobrado) | Completar o pedido |
| 400 mais de 10 pedidos | `multiple` aceita até 10 | Dividir em várias chamadas |
| 424 `no_tavily_api_keys` | O fornecedor não está disponível neste momento | Tentar mais tarde |
| `proveedor_de_busqueda_fallo` | O fornecedor falhou ao responder | Tentar de novo; é cobrado na mesma |

## Relação com MCP

A pesquisa em si usa-se por HTTP com o token, não por MCP. Por MCP (perfis `/mcp` e `/mcp/infra`) gerenciam-se os tokens:

- Leitura: `listar_tokens_search_api`, `ver_token_search_api`, `ver_costos_operaciones_search_api` (nunca devolvem o token).
- Escrita, só admin: `crear_token_search_api` (devolve o token uma única vez; aceita `idempotency_key`), `reactivar_token_search_api`.
- Destrutiva e reversível, só admin: `revocar_token_search_api` (registra o custo pendente).

Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e exemplos em [/mcp/ia](https://ardumaker.com/pt/mcp/ia).

## Funcionalidades relacionadas

- [Router IA](https://ardumaker.com/pt/docs/router-ia/)
- [Chaves de IA](https://ardumaker.com/pt/docs/claves-ia/)
- [Saldo por empresa](https://ardumaker.com/pt/docs/saldo-por-empresa/)
- [Consumo de serviços](https://ardumaker.com/pt/docs/consumo-de-servicios/)