Advanced APIs

Research

Run a multi-step research job across many sources and get back a cited answer, key findings, and a source list.

Overview

Research is asynchronous. Submitting returns a job_id immediately; poll GET /jobs/{id} until the status is succeeded.

POST/research

Request

curl https://api.ohsee.tech/research \
  -H "Authorization: Bearer ohsee-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "compare the leading vector databases for RAG",
    "research_depth": "standard",
    "output_format": "comparison_table"
  }'

Parameters

Field	Type	Default	Description
`query`required	string	-	The research question (1 to 2000 characters).
`research_depth`	string	standard	One of `standard` or `deep`.
`output_format`	string	brief	One of `brief`, `detailed`, `comparison_table`, `timeline`, `bullet_report`, `json`.
`max_sources`	int	8	Maximum sources to consult (1 to 30).
`include_evidence`	bool	true	Return citations backing key claims. Adds 1 credit.

Job & result

Submitting returns a job acceptance:

202 Accepted

{
  "request_id": "d4e5f6a7",
  "job_id": "9b8c7d6e-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "status": "queued",
  "credits": { "estimated": 15, "reserved": 15 },
  "response_time": 0.06
}

When the job finishes, the result is available on the job:

GET /jobs/{id}

{
  "job_id": "9b8c7d6e-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "kind": "research",
  "status": "succeeded",
  "credits": { "reserved": 15, "charged": 15, "refunded": 0 },
  "result": {
    "query": "compare the leading vector databases for RAG",
    "answer": "...",
    "key_findings": ["...", "..."],
    "citations": [],
    "source_list": [{ "url": "...", "title": "...", "source_type": "documentation" }],
    "confidence": 0.88,
    "output_format": "comparison_table"
  }
}

Field	Type	Description
`result.answer`	string \| null	The synthesized research answer.
`result.key_findings`	string[]	Bullet-point findings.
`result.citations`	object[]	Evidence for claims, when include_evidence is set.
`result.source_list`	object[]	Sources consulted, each with `url`, `title`, `source_type`.
`result.confidence`	float	Overall confidence score.

Credits

standard costs 10 and deep costs 25, plus 5 for detailed, comparison_table, or timeline, plus 1 for evidence.

Credits are reserved when the job starts and settled when it finishes; any unused reservation is refunded.

Structured extraction

Map & Crawl