Chordian Deep Search APIs

Chordian Deep Search APIs run multi-step AI research workflows over the web with optional live browser sessions, configurable LLM models, and support for uploading reference documents.

Overview

The Deep Search workflow lets you:

1. Start – Launch a deep search with a natural-language prompt and optional workflow fields
2. Upload – Attach reference files to an active search thread before or during the run
3. Clarifying answers – Continue the same thread by calling the same start API with thread_id and list_id
4. Stream progress – Connect to the websocket_url returned in the start response for real-time updates and results

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

Chordian Deep Search accepts legacy labels (same as Web and Research) or Browser v3 model IDs (canonical IDs sent upstream).

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 Deep Search

Start a Chordian Deep Search workflow for the given prompt.

POST /chordian-deep-search/start

Authentication: Authorization: Bearer <api-key>

Request Body

{
  "prompt": "Research top autonomous vehicle sensor manufacturers in Europe",
  "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,
  "thread_id": "536c****-****-45c5-****-0a8dfa5*****",
  "list_id": "6a3b60****2ea3a0609******",
  "websocket_url": "wss://agent.chordian.ai/api/chordian-deep-search/ws/536c****-****-45c5-****-0a8dfa5*****?api-key=<your-api-key>",
  "live_url": null,
  "workspace_id": null,
  "status": "processing"
}

Validation Error (422)

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

Example

curl -X POST https://chordian-core.chordian.ai/chordian-deep-search/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api-key>" \
  -d '{
    "prompt": "Research top autonomous vehicle sensor manufacturers in Europe",
    "llm_model": "claude-sonnet-4.6",
    "live_url": true,
    "proxy": false,
    "proxy_country_code": "",
    "thread_id": "536c****-****-45c5-****-0a8dfa5*****",
    "list_id": "6a3b60****2ea3a0609******"
  }'

Answer Clarifying Questions (Same Start API)

Use the same endpoint to answer clarifying questions in an ongoing deep search thread.

POST /chordian-deep-search/start

Include the original thread_id and list_id with the new answer in prompt.

{
  "prompt": "Include only companies with more than 100 employees",
  "thread_id": "536c****-****-45c5-****-0a8dfa5*****",
  "list_id": "6a3b60****2ea3a0609******"
}

Upload Reference File

Upload a reference document to an active deep search thread. Use this to provide context such as API documentation, reports, or data sheets that the agent should use during research.

POST /chordian-deep-search/upload

Authentication: Authorization: Bearer <api-key>

Content-Type: multipart/form-data

Form Fields

Successful Response (200 OK)

{
  "success": true,
  "workspace_id": "36912e8e-3d76-450e-b46a-df4db597792f",
  "paths": ["uploads/tmplucq1c0f.pdf"]
}

Example

curl -X POST https://chordian-core.chordian.ai/chordian-deep-search/upload \
  -H "Authorization: Bearer <api-key>" \
  -F "file=@/path/to/document.pdf" \
  -F "thread_id=536c****-****-45c5-****-0a8dfa5*****"

Connect to WebSocket

After a successful start response, open the websocket_url to receive real-time deep search updates and results.

The URL format is:

wss://agent.chordian.ai/api/chordian-deep-search/ws/<thread_id>?api-key=<your-api-key>

Use the thread_id and websocket_url from the start response. Pass your API key as the api-key query parameter.

JavaScript Example

const API_KEY = '<api-key>';
 
// 1. Start deep search
const startResponse = await fetch('https://chordian-core.chordian.ai/chordian-deep-search/start', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
body: JSON.stringify({
prompt: 'Research top autonomous vehicle sensor manufacturers in Europe',
llm_model: 'claude-sonnet-4.6',
live_url: true,
proxy: false
})
});
 
const startData = await startResponse.json();
 
// 2. Optionally upload a reference file
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('thread_id', startData.thread_id);
 
await fetch('https://chordian-core.chordian.ai/chordian-deep-search/upload', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`
},
body: formData
});
 
// 3. Connect to WebSocket
const wsUrl = startData.websocket_url.replace('<your-api-key>', API_KEY);
const ws = new WebSocket(wsUrl);
 
ws.onmessage = (event) => {
console.log('Deep search update:', JSON.parse(event.data));
};
 

import json
import requests
import websocket
 
API_KEY = '<api-key>'
headers = {
    'Authorization': f'Bearer {API_KEY}'
}
 
# 1. Start deep search
start = requests.post(
    'https://chordian-core.chordian.ai/chordian-deep-search/start',
    headers={**headers, 'Content-Type': 'application/json'},
    json={
        'prompt': 'Research top autonomous vehicle sensor manufacturers in Europe',
        'llm_model': 'claude-sonnet-4.6',
        'live_url': True,
        'proxy': False
    }
).json()
 
# 2. Optionally upload a reference file
with open('/path/to/document.pdf', 'rb') as f:
    requests.post(
        'https://chordian-core.chordian.ai/chordian-deep-search/upload',
        headers=headers,
        files={'file': f},
        data={'thread_id': start['thread_id']}
    )
 
# 3. Connect to WebSocket
ws_url = start['websocket_url'].replace('<your-api-key>', API_KEY)
 
def on_message(ws, message):
    print('Deep search update:', json.loads(message))
 
websocket.WebSocketApp(ws_url, on_message=on_message).run_forever()

Next Steps

• Explore Deep Research APIs for multi-agent research reports
• Explore Web and Research APIs for web-grounded Q&A workflows
• See Agentic Crawler APIs for open-web crawling