API: Deep Research

Launch form with live progress and result tabs.

curl -X GET -H 'Accept: application/json' 'http://molodetz.nl/research'

const response = await fetch("/research", { method: "GET", headers: { "Accept": "application/json" } });
console.log(await response.json());

import httpx
print(httpx.request("GET", BASE + "/research", headers={"Accept": "application/json", "X-API-KEY": API_KEY}).json())

{
  "job": null
}

Not sent yet.

Queues a disposable-agent job. Signed-in accounts may launch by default; key mode needs X-API-Key header or key field instead. Answers 202 plus the job, or 200 plus X-Cache: HIT on a fresh cache hit.

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"prompt": "Summarize the state of sodium batteries"}' 'http://molodetz.nl/research'

const response = await fetch("/research", { method: "POST", headers: { "Accept": "application/json" } });
console.log(await response.json());

import httpx
print(httpx.request("POST", BASE + "/research", headers={"Accept": "application/json", "X-API-KEY": API_KEY}).json())

{
  "status": "queued",
  "uid": "..."
}

Lists the caller jobs, newest first.

curl -X GET -H 'Accept: application/json' 'http://molodetz.nl/research/mine'

const response = await fetch("/research/mine", { method: "GET", headers: { "Accept": "application/json" } });
console.log(await response.json());

import httpx
print(httpx.request("GET", BASE + "/research/mine", headers={"Accept": "application/json", "X-API-KEY": API_KEY}).json())

{
  "jobs": []
}

Not sent yet.

Result or progress state. Unknown uids 404, expired jobs 410.

curl -X GET -H 'Accept: application/json' 'http://molodetz.nl/research/{uid}'

const response = await fetch("/research/{uid}", { method: "GET", headers: { "Accept": "application/json" } });
console.log(await response.json());

import httpx
print(httpx.request("GET", BASE + "/research/{uid}", headers={"Accept": "application/json", "X-API-KEY": API_KEY}).json())

{
  "job": {
    "status": "done",
    "uid": "..."
  }
}

Not sent yet.

Small polling object: status, latest progress, error.

curl -X GET -H 'Accept: application/json' 'http://molodetz.nl/research/{uid}/status'

const response = await fetch("/research/{uid}/status", { method: "GET", headers: { "Accept": "application/json" } });
console.log(await response.json());

import httpx
print(httpx.request("GET", BASE + "/research/{uid}/status", headers={"Accept": "application/json", "X-API-KEY": API_KEY}).json())

{
  "status": "running",
  "uid": "..."
}

Not sent yet.

Server-sent stream: started, progress, artifact, then done, partial, or failed. Heartbeat every 15s, resumes on Last-Event-ID.

curl -X GET -H 'Accept: application/json' 'http://molodetz.nl/research/{uid}/events'

const response = await fetch("/research/{uid}/events", { method: "GET", headers: { "Accept": "application/json" } });
console.log(await response.json());

import httpx
print(httpx.request("GET", BASE + "/research/{uid}/events", headers={"Accept": "application/json", "X-API-KEY": API_KEY}).json())

{
  "event": "started"
}

kind is md, html, or zip. ZIP members are flat websafe names.

curl -X GET -H 'Accept: application/json' 'http://molodetz.nl/research/{uid}/download/{kind}'

const response = await fetch("/research/{uid}/download/{kind}", { method: "GET", headers: { "Accept": "application/json" } });
console.log(await response.json());

import httpx
print(httpx.request("GET", BASE + "/research/{uid}/download/{kind}", headers={"Accept": "application/json", "X-API-KEY": API_KEY}).json())

{
  "download": "result.md"
}

One published artifact. Images inline, everything else as attachment.

curl -X GET -H 'Accept: application/json' 'http://molodetz.nl/research/{uid}/files/{name}'

const response = await fetch("/research/{uid}/files/{name}", { method: "GET", headers: { "Accept": "application/json" } });
console.log(await response.json());

import httpx
print(httpx.request("GET", BASE + "/research/{uid}/files/{name}", headers={"Accept": "application/json", "X-API-KEY": API_KEY}).json())

{
  "download": "data.csv"
}