Web and Research APIs

Web and Research APIs run AI agents that answer questions and conduct research using live web data, with optional browser sessions and configurable LLM models.

Overview

The Web and Research workflow uses a two-step flow: the start endpoint prepares a session and returns a WebSocket URL; the agent does not run until you connect to that WebSocket with your API key.

Important: Calling POST /webandreasearch/start alone does not start the research. You must open the returned websocket_url, replace the <your-api-key> placeholder with your real API key, and successfully connect. The agent begins processing only after the WebSocket connection is established.

The workflow includes:

1. Start – Submit a required prompt with optional workflow fields. The API returns a thread_id, list_id, and websocket_url with status ready.
2. Connect WebSocket – Replace <your-api-key> in websocket_url with your API key and open the connection. This step triggers the agent.
3. Clarifying answers – Send follow-up answers over WebSocket using prompt, thread_id, and list_id.
4. Stream progress – Receive real-time research updates and results over the WebSocket.

Base URL: https://chordian-core.chordian.ai

Authentication: Bearer token. Send your API key in the header: Authorization: Bearer <api-key>.

Supported configuration values

Use the values below when setting llm_model and proxy_country_code in the start request.

llm_model

proxy_country_code

Required when proxy is true. Use a lowercase ISO 3166-1 alpha-2 country code from the list below.

ad, ae, af, ag, ai, al, am, an, ao, aq, ar, as, at, au, aw, az, ba, bb, bd, be, bf, bg, bh, bi, bj, bl, bm, bn, bo, bq, br, bs, bt, bv, bw, by, bz, ca, cc, cd, cf, cg, ch, ck, cl, cm, co, cr, cs, cu, cv, cw, cx, cy, cz, de, dj, dk, dm, do, dz, ec, ee, eg, eh, er, es, et, fi, fj, fk, fm, fo, fr, ga, gd, ge, gf, gg, gh, gi, gl, gm, gn, gp, gq, gr, gs, gt, gu, gw, gy, hk, hm, hn, hr, ht, hu, id, ie, il, im, in, iq, ir, is, it, je, jm, jo, jp, ke, kg, kh, ki, km, kn, kp, kr, kw, ky, kz, la, lb, lc, li, lk, lr, ls, lt, lu, lv, ly, ma, mc, md, me, mf, mg, mh, mk, ml, mm, mn, mo, mp, mq, mr, ms, mt, mu, mv, mw, mx, my, mz, na, nc, ne, nf, ng, ni, nl, no, np, nr, nu, nz, om, pa, pe, pf, pg, ph, pk, pl, pm, pn, pr, ps, pt, pw, py, qa, re, ro, rs, ru, rw, sa, sb, sc, sd, se, sg, sh, si, sj, sk, sl, sm, sn, so, sr, ss, st, sv, sx, sy, sz, tc, td, tf, tg, th, tj, tk, tl, tm, tn, to, tr, tt, tv, tw, tz, ua, ug, uk, us, uy, uz, va, vc, ve, vg, vi, vn, vu, wf, ws, xk, ye, yt, za, zm, zw

Start Web and Research

Prepare a web and research session for the given prompt. This endpoint registers the workflow and returns a WebSocket URL — it does not start the agent until you connect to that URL.

POST /webandreasearch/start

Authentication: Authorization: Bearer <api-key>

Request Body

{
  "prompt": "What are the main trends in enterprise AI adoption for healthcare in 2026?",
  "llm_model": "claude sonnet 4.6",
  "live_url": true,
  "proxy": false,
  "proxy_country_code": "",
  "thread_id": "536c****-****-45c5-****-0a8dfa5*****",
  "list_id": "6a3b60****2ea3a0609******"
}

Successful Response (200 OK)

{
  "success": true,
  "message": "Connect to websocket_url to start the search",
  "thread_id": "536c****-****-45c5-****-0a8dfa5*****",
  "list_id": "6a3b60****2ea3a0609******",
  "websocket_url": "wss://agent.chordian.ai/api/agent/web-and-research?api-key=<your-api-key>&thread_id=536c****-****-45c5-****-0a8dfa5*****",
  "status": "ready"
}

Important: The status value ready means the session is prepared but research has not begun. Connect to websocket_url (with your API key substituted for <your-api-key>) to trigger the agent.

Validation Error (422)

{
  "detail": [
    {
      "loc": ["string", 0],
      "msg": "string",
      "type": "string"
    }
  ]
}

Example

curl -X POST https://chordian-core.chordian.ai/webandreasearch/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api-key>" \
  -d '{
    "prompt": "What are the main trends in enterprise AI adoption for healthcare in 2026?",
    "llm_model": "claude sonnet 4.6",
    "live_url": true,
    "proxy": false,
    "proxy_country_code": "",
    "thread_id": "536c****-****-45c5-****-0a8dfa5*****",
    "list_id": "6a3b60****2ea3a0609******"
  }'

Connect to WebSocket

This step triggers the agent. After a successful start response, open the websocket_url with your API key in place of the <your-api-key> placeholder. Research begins only when the WebSocket connection is successfully established.

The URL format is:

wss://agent.chordian.ai/api/agent/web-and-research?api-key=<your-api-key>&thread_id=<thread_id>

1. Take websocket_url from the start response.
2. Replace <your-api-key> with your actual API key.
3. Open the WebSocket connection — the agent starts on successful connect.
4. Listen for messages to receive progress and results.

If you do not connect, or if you leave the placeholder unchanged, the workflow will not run.

Clarifying Question Payload (WebSocket)

For clarifying-question answers, send this JSON shape over the connected WebSocket:

{
  "prompt": "Focus on hospitals and clinics, not pharmaceutical companies",
  "thread_id": "536c****-****-45c5-****-0a8dfa5*****",
  "list_id": "6a3b60****2ea3a0609******"
}

JavaScript Example

const response = await fetch('https://chordian-core.chordian.ai/webandreasearch/start', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <api-key>'
  },
  body: JSON.stringify({
    prompt: 'What are the main trends in enterprise AI adoption for healthcare in 2026?',
    live_url: true,
    proxy: false,
    llm_model: 'claude sonnet 4.6'
  })
});
 
const data = await response.json();
const ws = new WebSocket(data.websocket_url.replace('<your-api-key>', '<api-key>'));
 
ws.onmessage = (event) => {
console.log('Research update:', JSON.parse(event.data));
};
 
ws.onopen = () => console.log('Connected — agent workflow is now running');
ws.onerror = (error) => console.error('WebSocket error:', error);
 

import json
import requests
import websocket
 
response = requests.post(
    'https://chordian-core.chordian.ai/webandreasearch/start',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <api-key>'
    },
    json={
        'prompt': 'What are the main trends in enterprise AI adoption for healthcare in 2026?',
        'live_url': True,
        'proxy': False,
        'llm_model': 'claude sonnet 4.6'
    }
)
data = response.json()
 
ws_url = data['websocket_url'].replace('<your-api-key>', '<api-key>')
 
def on_message(ws, message):
    print('Research update:', json.loads(message))
 
ws = websocket.WebSocketApp(ws_url, on_message=on_message)
ws.run_forever()

Next Steps

• Explore Chordian Deep Search APIs for deep research with file uploads
• Explore Deep Research APIs for multi-agent research reports
• See Agentic Crawler APIs for open-web crawling workflows