Search API

Web search API for apps and agents: search, extract, crawl, map and parallel requests, charged to the company balance.

Category: AI and agents
Status: Available
Requirements: A company Search API token (created by an admin); An active payment method and at least 20 EUR of balance to create the token; The company up to date with payments to use it
MCP tools (Read only): listar_tokens_search_api, ver_token_search_api, ver_costos_operaciones_search_api
MCP tools (Write or modify): crear_token_search_api, revocar_token_search_api, reactivar_token_search_api

Markdown

What can you do with it?

search: search the web and get results with title, URL, content and score, optionally with a summarized answer.
extract: fetch the content of one or more URLs as Markdown or text.
crawl: walk a site from a URL, with configurable depth and breadth, and extract its content.
map: list a site's URLs without extracting content.
multiple: run up to 10 of the above in parallel and get the answers in the same order.

When should you use it?

Giving an AI agent access to current information from the web.
Feeding a knowledge base with a site's content.
Paying for search from the company balance without contracting another provider.

How does it work in ArduMaker?

The application sends a POST to https://api.ardumaker.com/api/v1/searchapi/<operation>/ with the token in the Authorization header (the token value, with no prefix).
ArduMaker validates the token: it must exist, be active, and the company must not be suspended for pending payments.
The request is forwarded to an external search provider with the received parameters and its answer is returned.
The operation cost is added to the token (with the company commission). When the unrecorded amount reaches 1 EUR, it is deducted from the company balance.

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}'

How the cost is computed

Operation	Billing unit
search	Per request; `search_depth: advanced` costs more
extract	Per URL; `extract_depth: advanced` costs more
crawl	Per 5 pages of the requested `limit` (50 by default); `advanced` costs more
map	Per 10 pages of the requested `limit`; with `instructions`, double

Current prices can be checked without authentication at GET /api/v1/searchapi/pricing/ and may change. A request that reaches the provider is billed even if the provider answers with an error; one rejected earlier (no query or no url) is not.

What actually changes?

On the token: request and cost counters, total and for the 24-hour, 7-day and 30-day windows.
In the company history: a consumption entry each time the accumulated amount reaches 1 EUR, and whatever is pending when the token is revoked.
If the company is pending identity verification, its tokens are paused until it is verified.

Main parameters

Operation	Required field	Some optional ones
`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`	Each item carries `type` and the fields of its operation

Optional parameters are forwarded to the provider as they are.

Diagram

Your app or agent: token in Authorization
Search API: validates token and payment status
Search provider: search, extract, crawl or map
Cost: added to the token; recorded every 1 EUR

A search request

Expected result

The answer is the provider's: results, and depending on the operation answer, failed_results, base_url and response_time.
multiple returns one answer per request, in the same order; failed ones carry their error.
ver_costos_operaciones_search_api shows the spending of all active tokens (total and for 24 hours, 7 and 30 days) and the prices per operation.

Errors and troubleshooting

Answer	Cause	What to do
403 `authorization_token_required`	Missing `Authorization` header	Send the token
403 `invalid_or_inactive_token`	Token does not exist, was revoked or is paused	Check the token or reactivate it
402 `service_suspended_due_to_pending_payment`	The company has pending payments	Settle the balance
400 `query is required` / `url is required` / `urls is required`	Missing required field (not billed)	Complete the request
400 more than 10 requests	`multiple` accepts up to 10	Split into several calls
424 `no_tavily_api_keys`	The provider is not available right now	Retry later
`proveedor_de_busqueda_fallo`	The provider failed to answer	Retry; it is billed anyway

MCP access

Search itself is used over HTTP with the token, not over MCP. Over MCP (/mcp and /mcp/infra profiles) the tokens are managed:

Read: listar_tokens_search_api, ver_token_search_api, ver_costos_operaciones_search_api (they never return the token).
Write, admin only: crear_token_search_api (returns the token only once; accepts idempotency_key), reactivar_token_search_api.
Destructive and reversible, admin only: revocar_token_search_api (records the pending cost).

Reference at /mcp/docs and examples at /mcp/ia.