Search API

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

  • 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

Markdown

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.
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çãoUnidade de cobrança
searchPor pedido; search_depth: advanced custa mais
extractPor URL; extract_depth: advanced custa mais
crawlPor cada 5 páginas do limit pedido (50 por padrão); advanced custa mais
mapPor 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çãoCampo obrigatórioAlguns opcionais
searchquerysearch_depth, max_results, topic, time_range, include_answer, include_raw_content, include_domains, exclude_domains
extracturlsquery, extract_depth, format, include_images
crawlurlinstructions, max_depth, max_breadth, limit, select_paths, exclude_paths, allow_external
mapurlinstructions, max_depth, max_breadth, limit, allow_external
multiplerequestsCada 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

  1. A sua app ou agente: token em Authorization
  2. Search API: valida token e estado de pagamentos
  3. Fornecedor de pesquisa: search, extract, crawl ou map
  4. Custo: soma-se ao token; registra-se a cada 1 EUR
Um pedido de pesquisa

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

RespostaCausaO que fazer
403 authorization_token_requiredFalta o header AuthorizationEnviar o token
403 invalid_or_inactive_tokenToken inexistente, revogado ou pausadoRever o token ou reativá-lo
402 service_suspended_due_to_pending_paymentA empresa tem pagamentos pendentesRegularizar o saldo
400 query is required / url is required / urls is requiredFalta o campo obrigatório (não é cobrado)Completar o pedido
400 mais de 10 pedidosmultiple aceita até 10Dividir em várias chamadas
424 no_tavily_api_keysO fornecedor não está disponível neste momentoTentar mais tarde
proveedor_de_busqueda_falloO fornecedor falhou ao responderTentar 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 e exemplos em /mcp/ia.

Funcionalidades relacionadas