Search API

API de búsqueda web para apps y agentes: search, extract, crawl, map y pedidos en paralelo, cobrados del saldo de la empresa.

  • Categoría: Inteligencia artificial y agentes
  • Estado: Disponible
  • Requisitos: Un token de Search API de la empresa (lo crea un admin); Medio de pago activo y al menos 20 EUR de saldo para crear el token; La empresa al día con los pagos para usarlo
  • Herramientas MCP (Solo leen): listar_tokens_search_api, ver_token_search_api, ver_costos_operaciones_search_api
  • Herramientas MCP (Escriben o modifican): crear_token_search_api, revocar_token_search_api, reactivar_token_search_api

Markdown

¿Qué permite hacer?

  • search: buscar en la web y recibir resultados con título, URL, contenido y puntaje, opcionalmente con una respuesta resumida.
  • extract: traer el contenido de una o varias URL en Markdown o texto.
  • crawl: recorrer un sitio desde una URL, con profundidad y amplitud configurables, y extraer su contenido.
  • map: listar las URL de un sitio sin extraer contenido.
  • multiple: correr hasta 10 de los anteriores en paralelo y recibir las respuestas en el mismo orden.

¿Cuándo conviene usarlo?

  • Darle a un agente de IA acceso a información actual de la web.
  • Alimentar una base de conocimiento con el contenido de un sitio.
  • Pagar la búsqueda desde el saldo de la empresa sin contratar otro proveedor.

¿Cómo funciona en ArduMaker?

  1. La aplicación hace POST a https://api.ardumaker.com/api/v1/searchapi/<operación>/ con el token en el header Authorization (el valor del token, sin prefijo).
  2. ArduMaker valida el token: tiene que existir, estar activo y la empresa no tiene que estar suspendida por pagos pendientes.
  3. Se reenvía el pedido a un proveedor de búsqueda externo con los parámetros recibidos y se devuelve su respuesta.
  4. Se suma el costo de la operación al token (con la comisión de la empresa). Cuando lo acumulado sin registrar llega a 1 EUR, se descuenta del saldo de la 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}'

Cómo se calcula el costo

OperaciónUnidad de cobro
searchPor pedido; search_depth: advanced cuesta más
extractPor URL; extract_depth: advanced cuesta más
crawlPor cada 5 páginas del limit pedido (50 por defecto); advanced cuesta más
mapPor cada 10 páginas del limit pedido; con instructions, el doble

Los precios vigentes se consultan sin autenticación en GET /api/v1/searchapi/pricing/ y pueden cambiar. Un pedido que llega al proveedor se cobra aunque el proveedor responda con error; uno rechazado antes (sin query o sin url) no.

¿Qué cambia realmente?

  • En el token: contadores de pedidos y costo, totales y de las ventanas de 24 horas, 7 días y 30 días.
  • En el historial de la empresa: un consumo cada vez que lo acumulado llega a 1 EUR, y lo pendiente al revocar el token.
  • Si la empresa queda pendiente de verificación de identidad, sus tokens se pausan hasta que se verifique.

Parámetros principales

OperaciónCampo obligatorioAlgunos opcionales
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 lleva type y los campos de su operación

Los parámetros opcionales se reenvían tal cual al proveedor.

Esquema

  1. Tu app o agente: token en Authorization
  2. Search API: valida token y estado de pagos
  3. Proveedor de búsqueda: search, extract, crawl o map
  4. Costo: se suma al token; se registra cada 1 EUR
Un pedido de búsqueda

Resultado esperado

  • La respuesta es la del proveedor: results, y según la operación answer, failed_results, base_url y response_time.
  • multiple devuelve una respuesta por pedido, en el mismo orden; los que fallan van con su error.
  • ver_costos_operaciones_search_api muestra el gasto de todos los tokens activos (total y de 24 horas, 7 y 30 días) y los precios por operación.

Errores y resolución

RespuestaCausaQué hacer
403 authorization_token_requiredFalta el header AuthorizationMandar el token
403 invalid_or_inactive_tokenToken inexistente, revocado o pausadoRevisar el token o reactivarlo
402 service_suspended_due_to_pending_paymentLa empresa tiene pagos pendientesRegularizar el saldo
400 query is required / url is required / urls is requiredFalta el campo obligatorio (no se cobra)Completar el pedido
400 más de 10 pedidosmultiple acepta hasta 10Partir en varias llamadas
424 no_tavily_api_keysEl proveedor no está disponible en este momentoReintentar más tarde
proveedor_de_busqueda_falloEl proveedor falló al responderReintentar; se cobra igual

Relación con MCP

La búsqueda en sí se usa por HTTP con el token, no por MCP. Por MCP (perfiles /mcp e /mcp/infra) se administran los tokens:

  • Lectura: listar_tokens_search_api, ver_token_search_api, ver_costos_operaciones_search_api (nunca devuelven el token).
  • Escritura, solo admin: crear_token_search_api (devuelve el token una sola vez; acepta idempotency_key), reactivar_token_search_api.
  • Destructiva y reversible, solo admin: revocar_token_search_api (registra el costo pendiente).

Referencia en /mcp/docs y ejemplos en /mcp/ia.

Funciones relacionadas