Tools

Verified web search and safe page fetching, the same tools every codai agent uses.

Both endpoints go through the rules gate and the per-key rate limit. search returns only snippets verified against the fetched page, with domain (include_domains / exclude_domains), publish-date (published_after / published_before) and freshness filters; each result carries published_at (null when unknown, never the crawl date) and crawled_at. fetch enforces SSRF checks on every redirect hop and a 3 MB cap, and returns up to 40,000 characters (8,000 by default). Metered per call: $3 / 1,000 fast searches, $8 / 1,000 deep, $0.50 / 1,000 fetches; the first 1,000 calls a month are free and calls inside a codai agent turn are never charged. For multi-step questions use deep research. Details: tools guide.

POST

/v1/tools/search

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Request Body

application/json

body

Body of POST /v1/tools/search.

query*string

Search phrase (trimmed).

Length1 <= length <= 400

max_results?integer

Maximum number of results.

Range1 <= value <= 10

Default5

freshness?string

Only pages published within the window; pages without a known publish date are dropped.

Value in"day""week""month""year"

include_domains?array<>

Only return pages from these hosts (subdomains included, optional path prefix such as github.com/vercel). Scheme and www. are stripped.

Itemsitems <= 10

exclude_domains?array<>

Never return pages from these hosts (same matching as include_domains).

Itemsitems <= 10

published_after?string

Only pages published on or after this date (YYYY-MM-DD or YYYY-MM); undated pages are dropped.

Match^\d{4}-\d{2}(-\d{2})?$

published_before?string

Only pages published before this date (YYYY-MM-DD or YYYY-MM); undated pages are dropped.

Match^\d{4}-\d{2}(-\d{2})?$

content_chars?integer

Also return a verified excerpt of up to this many characters per result in content (omitted or 0 = snippet only).

Range0 <= value <= 2000

country?string

Two-letter market code. Omit it to let the gateway infer it from the query (ro for Romanian queries, us otherwise).

Match^[a-zA-Z]{2}$

lang?string

Language code, optionally with region (en-US). Omit it to infer it from the query; a lang:xx operator in the query wins.

Match^[a-zA-Z]{2}(-[a-zA-Z]{2})?$

mode?string

codai (default): verified-only native search (ToolSearchResponse). google: Grounding with Google Search on Vertex AI, returned as a separate ToolSearchGoogleResponse and never mixed with codai results; 404 when the gateway has not enabled it, 503 search_unavailable when Google returns no grounding. fast / deep mean codai with that depth (alias kept for clients that send codai-search's own field).

Default"codai"

Value in"codai""google""fast""deep"

depth?string

codai-search depth. fast (default): ~4.5 s budget. deep: more sources and a ~12 s budget, for research, literature and comparison queries; with fallback: auto the whole request may take ~20 s.

Default"fast"

Value in"fast""deep"

fallback?string

With mode: codai: auto (default) attaches a separate google block (Grounding with Google Search) when codai's own results are weak (none, fewer than 3, or low coverage for code/docs/general/academic/education) or the search service is down; never for currency/weather/fuel/inflation/local_poi. off disables it.

Default"auto"

Value in"auto""off"

Response Body

Verified results (or the provider-path shape on deployments without codai-search).

application/json

response

The codai-search JSON, returned verbatim by the gateway.

results*array<>

Itemsitems <= 10

provider*"codai"

Value in"codai"

took_ms*integer

Search-service latency in milliseconds (not the gateway round trip).

Range0 <= value

cached*boolean

Served from the search service's 10-minute result cache.

coverage*number

results.length / max_results, rounded to two decimals.

Range0 <= value <= 1

sources_tried*array<string>

degraded*array<string>

Real source or stage failures and timeouts only (e.g. rerank:timeout); empty when everything ran.

notes?array<string>

Informational pipeline codes (filtered rows, pending verifies, cache hints); not failures. Omitted when empty.

intent*string

Rule-based query intent used to pick sources.

Value in"currency""weather""encyclopedic""code""docs""site""news""price""local""fuel""inflation""local_poi""academic""definition""education""general"

complete?boolean

The answer is whole even with fewer than 3 results (the reference article for a definition or fact question, a curated official page at rank 1, two news-feed articles, or strict operators such as site: / filetype: / intitle:). The automatic Google fallback does not run on it.

rerank?

Present when the cross-encoder reranker ran.

google?

Present only when the automatic fallback ran (see fallback). A separate result set from Grounding with Google Search — never merged into results; show answer with search_suggestions_html and keep the attribution (Google's terms).

fallback?

Whether the automatic Google fallback was used, and why.

Example Request

curl -X POST 'https://ai.codai.ro/v1/tools/search' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "curs BNR euro azi"
}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/tools/search' \  -H 'Content-Type: application/json' \  -d '{  "query": "curs BNR euro azi"}'

Example ResponseSchema

{
  "results": [
    {
      "title": "string",
      "url": "http://example.com",
      "snippet": "string",
      "page_age": "string",
      "published_at": "2019-08-24T14:15:22Z",
      "crawled_at": "2019-08-24T14:15:22Z",
      "content": "string",
      "source": "index",
      "verified": true
    }
  ],
  "provider": "codai",
  "took_ms": 0,
  "cached": true,
  "coverage": 0,
  "sources_tried": [
    "string"
  ],
  "degraded": [
    "string"
  ],
  "notes": [
    "string"
  ],
  "intent": "currency",
  "complete": true,
  "rerank": {
    "model": "string",
    "ms": 0,
    "n": 0
  },
  "google": {
    "answer": "string",
    "sources": [
      {
        "title": "string",
        "url": "http://example.com"
      }
    ],
    "queries": [
      "string"
    ],
    "search_suggestions_html": "string",
    "attribution": "string",
    "cached": true
  },
  "fallback": {
    "used": true,
    "hedged": true,
    "reason": "few_results"
  }
}

{  "results": [    {      "title": "string",      "url": "http://example.com",      "snippet": "string",      "page_age": "string",      "published_at": "2019-08-24T14:15:22Z",      "crawled_at": "2019-08-24T14:15:22Z",      "content": "string",      "source": "index",      "verified": true    }  ],  "provider": "codai",  "took_ms": 0,  "cached": true,  "coverage": 0,  "sources_tried": [    "string"  ],  "degraded": [    "string"  ],  "notes": [    "string"  ],  "intent": "currency",  "complete": true,  "rerank": {    "model": "string",    "ms": 0,    "n": 0  },  "google": {    "answer": "string",    "sources": [      {        "title": "string",        "url": "http://example.com"      }    ],    "queries": [      "string"    ],    "search_suggestions_html": "string",    "attribution": "string",    "cached": true  },  "fallback": {    "used": true,    "hedged": true,    "reason": "few_results"  }}

POST

/v1/tools/fetch

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Request Body

application/json

body

Body of POST /v1/tools/fetch.

url*string

Public http/https URL. A bare host is prefixed with https://.

Length1 <= length <= 2048

max_chars?integer

Cap on content length; longer documents are cut at a paragraph boundary and flagged truncated.

Range200 <= value <= 40000

Default8000

focus?string

Phrase to focus on — only the most relevant paragraphs are kept, joined with […].

Lengthlength <= 300

format?string

Default"markdown"

Value in"markdown""text"

Response Body

Extracted page.

application/json

response

Extracted content plus metadata. Optional metadata keys are omitted when the page lacks them.

url*string

The URL as you sent it.

final_url*string

URL after redirects.

Formaturi

title?string

byline?string

description?string

canonical?string

Formaturi

lang?string

Document language as declared by the page.

content_type*string

Lower-cased media type without parameters.

content*string

Readable content in the requested format. JSON documents are pretty-printed.

chars*integer

Length of content.

Range0 <= value

truncated*boolean

True when max_chars, focus windowing or the 3 MB body cap dropped content.

took_ms*integer

Range0 <= value

cached*boolean

Served from the gateway's 15-minute LRU.

Example Request

curl -X POST 'https://ai.codai.ro/v1/tools/fetch' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://www.bnr.ro/Cursul-de-schimb-524.aspx"
}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/tools/fetch' \  -H 'Content-Type: application/json' \  -d '{  "url": "https://www.bnr.ro/Cursul-de-schimb-524.aspx"}'

Example ResponseSchema

{
  "url": "string",
  "final_url": "http://example.com",
  "title": "string",
  "byline": "string",
  "description": "string",
  "canonical": "http://example.com",
  "lang": "string",
  "content_type": "text/html",
  "content": "string",
  "chars": 0,
  "truncated": true,
  "took_ms": 0,
  "cached": true
}

{  "url": "string",  "final_url": "http://example.com",  "title": "string",  "byline": "string",  "description": "string",  "canonical": "http://example.com",  "lang": "string",  "content_type": "text/html",  "content": "string",  "chars": 0,  "truncated": true,  "took_ms": 0,  "cached": true}

Tools

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Header Parameters

Request Body

Response Body

Authorization

Header Parameters

Request Body

Response Body