Core APIs

Search

Discover relevant web content and return ranked, cited passages, with an optional synthesized answer.

Overview

Search runs the full discover, read, rank, and return pipeline synchronously. You get back ranked results with clean content and scores, plus an optional cited answer.

POST/search

Request

curl https://api.ohsee.tech/search \
  -H "Authorization: Bearer ohsee-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does the model context protocol handle auth?",
    "search_depth": "advanced",
    "max_results": 5,
    "include_answer": true
  }'

Parameters

Field	Type	Default	Description
`query`required	string	-	The search query (1 to 1000 characters).
`search_depth`	string	basic	One of `ultra-fast`, `fast`, `basic`, `advanced`. Trades latency for depth.
`topic`	string	general	One of `general`, `news`, `finance`.
`time_range`	string	null	Filter by recency: `day`, `week`, `month`, or `year`.
`max_results`	int	5	Number of results to return (1 to 20).
`chunks_per_source`	int	3	Passages per source (1 to 3), used by `advanced`.
`include_answer`	bool \| string	false	Set `true` or `"advanced"` to include a cited answer. Included in the base search credit.
`include_raw_content`	bool \| string	false	Set `"markdown"` or `"text"` to include full cleaned page content.
`include_evidence`	bool	false	Return supporting citations for claims. Adds 1 credit.
`include_domains`	string[]	[]	Only return results from these domains.
`exclude_domains`	string[]	[]	Never return results from these domains.
`source_quality`	string	standard	One of `standard`, `strict`, `custom`. `strict` favors official, documentation, academic, and news sources.
`allowed_source_types`	string[]	[]	Restrict to types like `documentation`, `news`, `academic`, `official`, `forum`, `commerce`, `general_web`.
`excluded_source_types`	string[]	[]	Exclude specific source types.
`prefer_domains`	string[]	[]	Boost results from these domains without excluding others.
`cache`	string	auto	Cache behavior: `auto`, `force`, or `bypass`.
`cache_ttl`	int	900	Cache lifetime in seconds (60 to 86400).

Response

Field	Type	Description
`query`	string	The query you sent.
`answer`	string \| null	Synthesized cited answer, when include_answer is set.
`results`	object[]	Ranked results, each with `url`, `title`, `content`, `score`, `published_date`, `source_type`, `raw_content`, `citation_id`, `is_stale`.
`citations`	object[]	Supporting evidence, when include_evidence or an answer is requested.
`response_time`	float	Server processing time in seconds.
`request_id`	string	Unique ID for this request.
`credits_charged`	int	Credits deducted for this request.
`cache_status`	string \| null	`hit`, `miss`, or `bypassed`.

200 OK

{
  "query": "how does the model context protocol handle auth?",
  "answer": "MCP uses OAuth 2.1 for authorization ...",
  "results": [
    {
      "url": "https://modelcontextprotocol.io/docs/concepts/authorization",
      "title": "Authorization - Model Context Protocol",
      "content": "MCP uses OAuth 2.1 for authorization ...",
      "score": 0.97,
      "published_date": null,
      "source_type": "documentation",
      "raw_content": null,
      "citation_id": "c1",
      "is_stale": false
    }
  ],
  "citations": [],
  "response_time": 1.42,
  "request_id": "b3f1a2c4",
  "credits_charged": 3,
  "cache_status": "miss"
}

Credits

Base cost is 1 credit (2 for advanced). include_answer is free; include_evidence adds 1 credit. Cache hits cost less.

Preview the exact cost with /estimate before running large batches.

Credits & pricing

Extract