meta-search: filter and sort metadata

Overview

meta-search returns bibliographic metadata such as title, abstract, authors, and publication year. It is suited for paper lists, filtering, and exports, but does not return passage text. You can search precisely with filters and sort without query, or use query for full-text fuzzy matching (query and sort can be combined: with sort, results are hard-sorted by the field and query degrades to a match filter; without sort, use freshness_boost to bias toward recent papers, impact_boost to favor highly-cited ones, or language_affinity to favor papers in the query's language).

Use cases

• · Filter literature lists by fields such as subject, year, journal, and language.
• · Use meta-catalog to dynamically generate UI filters.
• · Use cursor pagination for cross-page retrieval.

Not for

• · Use agentic-search for open-ended semantic evidence retrieval.
• · Use content when you need full source text.
• · Use resource when you need Figure, Table, or attachment binaries.

Capability boundaries

• · meta-search is for structured scholarly metadata retrieval and does not return evidence chunk text.
• · filters, fields, and sort names must come from meta-catalog; do not hard-code or invent field names.
• · query and sort should not be combined for relevance-ranked use cases; use cursor for deep pagination beyond page * page_size 10000.
• · Returned fields may be trimmed by account field permissions.

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/meta-search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "graphene battery cycle stability",
    "filters": [
      {"field": "publication_published_year", "operator": "FILTER_OP_GTE", "value": 2022}
    ],
    "fields": ["title", "doi", "publication_published_year", "publication_venue_name_unified"],
    "page": 1,
    "page_size": 10
  }'

Request body (JSON)

FilterItem: { field, operator?, value }. operator defaults to EQ; supported values are FILTER_OP_EQ/NE/GT/GTE/LT/LTE/IN/NIN/CONTAINS/MATCH/MATCH_PHRASE. SortItem: { field, order }. order defaults to SORT_ORDER_DESC.

Field capabilities

Field visibility depends on the current token permissions. Dotted subfields are for filters / sort only and cannot be used in fields[] projections. At runtime, prefer the meta-catalog response as the source of truth.

Response structure

Response example

{
  "results": [
    {
      "doc_id": "d_2a91...",
      "title": "Cycle stability of graphene composite cathodes",
      "doi": "10.1234/xyz",
      "language": "en",
      "publication_published_year": 2024,
      "publication_venue_name_unified": "Adv. Energy Mater.",
      "citation_count": 42,
      "fwci": 1.84
    }
  ],
  "total_count": 318,
  "page": 1,
  "page_size": 25,
  "total_pages": 13,
  "search_time_ms": 56.4,
  "next_cursor": "eyJvZmZzZXQiOjI1fQ=="
}

Errors

See the Errors section for shared error codes.

Parameter bounds

Retry guidance

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

FAQ