# Search API

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

Source: https://ardumaker.com/en/docs/search-api/

- 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`

## 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?

1. 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).
2. ArduMaker validates the token: it must exist, be active, and the company must not be suspended for pending payments.
3. The request is forwarded to an external search provider with the received parameters and its answer is returned.
4. 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.

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

### 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

**A search request**

```text
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)
```

## 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](https://ardumaker.com/en/mcp/docs) and examples at [/mcp/ia](https://ardumaker.com/en/mcp/ia).

## Related features

- [Router IA](https://ardumaker.com/en/docs/router-ia/)
- [AI keys](https://ardumaker.com/en/docs/claves-ia/)
- [Balance per company](https://ardumaker.com/en/docs/saldo-por-empresa/)
- [Service usage](https://ardumaker.com/en/docs/consumo-de-servicios/)