Unelte

Căutare web verificată și fetch sigur de pagini, aceleași unelte pe care le folosește fiecare agent codai.

Ambele endpoint-uri trec prin gate-ul de reguli și prin limita de rată per cheie. search returnează doar snippet-uri verificate față de pagina descărcată, cu filtre de domeniu (include_domains / exclude_domains), de dată de publicare (published_after / published_before) și freshness; fiecare rezultat are published_at (null când nu se cunoaște, niciodată data descărcării) și crawled_at. fetch aplică verificări SSRF la fiecare hop de redirect și o limită de 3 MB și returnează până la 40.000 de caractere (implicit 8.000). Contorizare per apel: 3 $ la 1.000 de căutări rapide, 8 $ la 1.000 aprofundate, 0,50 $ la 1.000 de fetch-uri; primele 1.000 de apeluri pe lună sunt gratuite, iar apelurile din cadrul unei ture de agent codai nu se taxează niciodată. Pentru întrebări în mai mulți pași folosește cercetarea aprofundată. Detalii: ghidul de unelte.

POST

/v1/tools/search

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

Corpul cererii

application/json

body

Corpul lui POST /v1/tools/search.

query*string

Fraza de căutare (cu spațiile de la capete eliminate).

Lungime1 <= length <= 400

max_results?integer

Numărul maxim de rezultate.

Interval1 <= value <= 10

Implicit5

freshness?string

Doar pagini publicate în fereastra dată; paginile fără dată de publicare cunoscută sunt eliminate.

Valoare din"day""week""month""year"

include_domains?array<>

Întoarce doar pagini de pe aceste host-uri (inclusiv subdomenii, cu prefix de cale opțional, de ex. github.com/vercel). Schema și www. sunt eliminate.

Elementeitems <= 10

exclude_domains?array<>

Nu întoarce niciodată pagini de pe aceste host-uri (aceeași potrivire ca la include_domains).

Elementeitems <= 10

published_after?string

Doar pagini publicate la sau după această dată (YYYY-MM-DD sau YYYY-MM); paginile nedatate sunt eliminate.

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

published_before?string

Doar pagini publicate înainte de această dată (YYYY-MM-DD sau YYYY-MM); paginile nedatate sunt eliminate.

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

content_chars?integer

Întoarce și un extras verificat de cel mult atâtea caractere per rezultat, în content (absent sau 0 = doar snippet).

Interval0 <= value <= 2000

country?string

Cod de piață din două litere. Dacă lipsește, gateway-ul îl deduce din interogare (ro pentru interogări în română, us în rest).

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

lang?string

Cod de limbă, opțional cu regiune (en-US). Dacă lipsește, se deduce din interogare; un operator lang:xx în interogare are prioritate.

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

mode?string

codai (implicit): căutarea nativă doar cu rezultate verificate (ToolSearchResponse). google: Grounding with Google Search pe Vertex AI, întors separat ca ToolSearchGoogleResponse și niciodată amestecat cu rezultatele codai; 404 când gateway-ul nu îl are activat, 503 search_unavailable când Google nu întoarce surse. fast / deep înseamnă codai cu acel depth (alias păstrat pentru clienții care trimit câmpul codai-search).

Implicit"codai"

Valoare din"codai""google""fast""deep"

depth?string

Adâncimea codai-search. fast (implicit): buget ~4,5 s. deep: mai multe surse și buget ~12 s, pentru cercetare, literatură și comparații; cu fallback: auto cererea întreagă poate dura ~20 s.

Implicit"fast"

Valoare din"fast""deep"

fallback?string

Cu mode: codai: auto (implicit) atașează un bloc separat google (Grounding with Google Search) când rezultatele codai sunt slabe (niciunul, sub 3 sau acoperire mică pentru code/docs/general/academic/education) sau serviciul de căutare e indisponibil; niciodată pentru currency/weather/fuel/inflation/local_poi. off îl dezactivează.

Implicit"auto"

Valoare din"auto""off"

Corpul răspunsului

Rezultate verificate (sau forma căii de furnizor, pe instalările fără codai-search).

application/json

response

JSON-ul codai-search, întors neschimbat de gateway.

results*array<>

Elementeitems <= 10

provider*"codai"

Valoare din"codai"

took_ms*integer

Latența serviciului de căutare în milisecunde (nu întregul dus-întors prin gateway).

Interval0 <= value

cached*boolean

Servit din cache-ul de rezultate de 10 minute al serviciului de căutare.

coverage*number

results.length / max_results, rotunjit la două decimale.

Interval0 <= value <= 1

sources_tried*array<string>

degraded*array<string>

Doar eșecurile și expirările reale ale surselor sau etapelor (de ex. rerank:timeout); gol când totul a rulat.

notes?array<string>

Coduri informative ale pipeline-ului (rânduri filtrate, verificări în curs, indicii de cache); nu sunt eșecuri. Lipsește când e gol.

intent*string

Intenția interogării, stabilită pe reguli, folosită la alegerea surselor.

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

complete?boolean

Răspunsul este complet chiar cu mai puțin de 3 rezultate (articolul de referință pentru o definiție sau o întrebare factuală, o pagină oficială selectată pe locul 1, două articole din fluxurile de știri sau operatori stricți precum site: / filetype: / intitle:). Fallback-ul automat Google nu rulează în acest caz.

rerank?

Prezent când a rulat reranker-ul cross-encoder.

google?

Prezent doar când a rulat fallback-ul automat (vezi fallback). Set de rezultate separat din Grounding with Google Search — niciodată amestecat în results; afișați answer împreună cu search_suggestions_html și păstrați attribution (termenii Google).

fallback?

Dacă a fost folosit fallback-ul automat Google și de ce.

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

{
  "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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

Corpul cererii

application/json

body

Corpul lui POST /v1/tools/fetch.

url*string

URL public http/https. Un host fără schemă primește prefixul https://.

Lungime1 <= length <= 2048

max_chars?integer

Plafon pentru lungimea lui content; documentele mai lungi sunt tăiate la limită de paragraf și marcate truncated.

Interval200 <= value <= 40000

Implicit8000

focus?string

Fraza pe care te concentrezi — se păstrează doar paragrafele cele mai relevante, unite cu […].

Lungimelength <= 300

format?string

Implicit"markdown"

Valoare din"markdown""text"

Corpul răspunsului

Pagina extrasă.

application/json

response

Conținutul extras plus metadate. Cheile de metadate opționale lipsesc când pagina nu le are.

url*string

URL-ul exact așa cum l-ai trimis.

final_url*string

URL-ul după redirecturi.

Formaturi

title?string

byline?string

description?string

canonical?string

Formaturi

lang?string

Limba documentului, așa cum o declară pagina.

content_type*string

Tipul media cu litere mici, fără parametri.

content*string

Conținut lizibil în format-ul cerut. Documentele JSON sunt formatate lizibil.

chars*integer

Lungimea lui content.

Interval0 <= value

truncated*boolean

True când max_chars, fereastra focus sau plafonul de 3 MB pe corp au eliminat conținut.

took_ms*integer

Interval0 <= value

cached*boolean

Servit din LRU-ul de 15 minute al gateway-ului.

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

{
  "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}

Unelte

AutorizareCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

Autorizare

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri header

Corpul cererii

Corpul răspunsului