POST/agentic-search

agentic-search: intelligent retrieval and chunks

Ask a natural-language question and get the most relevant citable literature passages.

Overview

agentic-search is designed for LLM agents and RAG. Each result includes title, text snippet, doc_id, and page/location metadata, making it useful for quickly finding citable context. When you need the full text, continue with content by using the returned doc_id.

Use cases

· RAG applications: provide citable literature evidence for LLMs.
· Agent tool calls: return linkable snippets and source locations in one response.
· Q&A systems: generate sourced answers from full text and snippets.

Not for

· Use meta-search for exact DOI/title lookup or structured metadata export.
· Use content with the returned doc_id when you need full source context.
· Use resource when you need figure, table, or attachment binaries.

Capability boundaries

· agentic-search returns semantic evidence retrieval hits and evidence chunks; it does not generate the final answer.
· query is limited to 4096 characters; top_k is 1-100; sub_queries is 0-4. Without sub_queries the effective return is capped at ~50 hits by the server-side single-path fusion pool.
· filters are semantic-search filters and differ from the FieldFilter array used by meta-search.
· Response fields may be trimmed by account permissions, so callers must tolerate missing fields.

Authentication

Use API key Bearer token authentication for all requests. Add this HTTP header:

Authorization: Bearer YOUR_API_TOKEN

Request example

curl -X POST https://api.sciverse.space/agentic-search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "graphene battery cycle stability",
    "top_k": 10,
    "filters": {
      "lang": "en",
      "publication_published_year": {"gte": 2020},
      "topics": {
        "logic": "and",
        "dimensions": {
          "primary_topic_domain": "Physical Sciences"
        }
      }
    }
  }'

Request body (JSON)

Field	Type	Required	Description
query	string	Required	The search question; must not be empty. Range Up to 4096 characters
top_k	integer	Optional	Number of snippets to return. Without sub_queries the search runs a single recall path whose server-side fusion pool keeps about 50, so expect at most ~50 hits; enabling sub_queries merges multiple paths and can exceed 50. Default 10Range 1–100
sub_queries	integer	Optional	Number of query rewrites; 0 disables rewriting. Default 0Range 0–4
filters	object	Optional	Narrows semantic search by document metadata; see the filters field table for the structure. Default {}

filters field table

Field	Type	Value	Description
Field combination	rule	AND across fields; OR across array values within one field	Omit filters or pass {} for no filtering. All fields except doc_id use soft semantics: chunks missing that metadata are NOT excluded; use doc_id when you need a hard guarantee that hits never leave a given set.
lang	string	Language codes such as en or zh	Document language.
title	string	Title string	Exact-match title filter.
author	string / string[]	Author name; an array matches any listed author	Filters by author name.
publication_venue_name_unified	string	Nature, Science, etc.	Filters by normalized publication venue name.
publication_venue_type	string	journal, conference, book series, repository, etc.	Exact-match venue type filter; values are case-insensitive.
publication_published_date	string / range	YYYY, YYYY-MM, YYYY-MM-DD, {gte,lte}, [min,max]	Filters by publication date.
publication_published_year	number / range	2024, {gte:2020,lte:2025}, [2020,2025]	Filters by publication year.
citation_count	number / range	100, {gte:100}, [100,null]	Filters by citation count.
influential_citation_count	number / range	10, {gte:10}, [10,null]	Filters by influential citation count.
topics.logic	string	and, or; defaults to or	Controls how multiple topic dimensions are combined.
topics.dimensions.primary_topic	string	Topic names such as Machine Learning	Filters by primary topic name.
topics.dimensions.primary_topic_domain	string	Physical Sciences, Social Sciences, Health Sciences, Life Sciences	Filters by primary topic domain.
doc_id	string / string[]	64-char lowercase hex (sha256), i.e. the doc_id returned by meta-search	Hard scope: hits never leave the given set; combinable with other fields (AND). Typical flow: narrow candidates with meta-search first, then run semantic search within the set. Up to 1000 deduped ids by default (400 SCOPE_TOO_LARGE beyond); an explicitly empty array returns 200 with empty hits (empty candidate set — never falls back to global search); only papers with full text carry a doc_id.

Response structure

Field	Type	Description
hits	array	Matched snippet list.
hits[].chunk_id	string	Snippet ID.
hits[].chunk	string	Snippet text content.
hits[].doc_id	string	Document ID, usable with /content to read the source text.
hits[].title	string	Document title.
hits[].abstract	string	Document abstract.
hits[].score	float	Relevance score.
hits[].source_type	string	Source type such as pdf or web.
hits[].offset	integer	Character offset in the source text (Unicode code points).
hits[].page_no	integer	Source page number (PDF only).
hits[].model_name	string	Model name used for scoring.
hits[].model_version	string	Model version.
hits[].lang	string	Document language.
hits[].metadata_type	string	Resource type, such as paper or ebook.
hits[].author	array<string>	Author list.
hits[].publication_venue_name_unified	string	Publication venue name.
hits[].publication_venue_type	string	Publication venue type.
hits[].publication_published_date	string	Publication date in YYYY-MM-DD format.
hits[].publication_published_year	integer	Publication year.
hits[].citation_count	integer	Citation count.
hits[].influential_citation_count	integer	Influential citation count.
hits[].primary_topic	string	Primary topic name.
hits[].primary_topic_domain	string	Primary topic domain.

Response example

{
  "hits": [
    {
      "chunk_id": "c_8c1f...",
      "chunk": "Graphene-based cathodes exhibit improved cycle stability ...",
      "doc_id": "d_2a91...",
      "title": "Cycle stability of graphene composite cathodes",
      "abstract": "...",
      "score": 0.873,
      "source_type": "pdf",
      "offset": 18432,
      "page_no": 4,
      "model_name": "sciverse-retriever",
      "model_version": "v2.3",
      "lang": "en",
      "metadata_type": "paper",
      "author": ["Jane Doe", "John Smith"],
      "publication_venue_name_unified": "Nature",
      "publication_venue_type": "journal",
      "publication_published_date": "2023-06-15",
      "publication_published_year": 2023,
      "citation_count": 128,
      "influential_citation_count": 12,
      "primary_topic": "Energy Storage",
      "primary_topic_domain": "Physical Sciences"
    }
  ]
}

Errors

Code	Message	Description
400	INVALID_REQUEST	Invalid request parameters; check values such as query and top_k.
400	SCOPE_TOO_LARGE	filters.doc_id exceeds the limit (default 1000); shrink the candidate set or tighten the meta-search criteria and retry.
400	EMPTY_RESULT	No results (including a doc_id set with no full-text coverage); adjust the query or candidate set and retry.
401	UNAUTHORIZED	Authentication failed; check the Authorization header.
429	RATE_LIMITED	Account quota limit reached; retry after the limit window or daily quota resets.
500	INTERNAL_ERROR	Service error; retry with exponential backoff.
502/503	UPSTREAM_UNAVAILABLE	Service temporarily unavailable; retry with exponential backoff.

See the Errors section for shared error codes.

Parameter bounds

Limit	Value
query length	≤ 4096 characters
top_k limit	100 (effectively ~50 without sub_queries)
filters.doc_id count	≤ 1000 after dedupe

Retry guidance

· Retry recommended: 500 / 502 / 503
· Do not retry: 400 / 401; for 429, wait for the limit window or daily quota reset.

FAQ

Does agentic-search generate a literature review or final answer?

No. It returns citable evidence chunks, doc_id values, and source locations. The application or agent generates the answer.

How do I read more context after an evidence chunk?

Call content with the returned doc_id and offset fields to read source text by character slices.

Can I cite the returned chunks directly?

Use them as citation evidence, but keep source fields such as doc_id, DOI, chunk_id, offset, or page for verification.

When should I choose agentic-search instead of meta-search?

Use agentic-search for natural-language research questions and evidence recall. Use meta-search for filtering, sorting, export, or DOI lookup.

Need an API key?

Create one in Console > Tokens.The same API key works for enabled Sciverse, DianShi, and Skills capabilities, with starter quota available according to account permissions.

Open console