API/paper-schemaBETA

paper-schema: paper structure, evidence, and citation graphs

Search structured information across a corpus currently centered on 1M+ AI conference papers, trace source evidence, and build drillable citation graphs.

Use the Paper Schema SkillUse nine intent tools for structured reading, evidence verification, Entity discovery, and bounded paper graphs.

Overview

paper-schema pre-parses papers into compact Paper, Entity, Relation, Evidence, and Citation structures with precise links back to source paragraphs. Agents can read these focused objects first and fetch only the small amount of source context needed for verification, avoiding repeated full-text loading, reducing token usage, and making multi-step discovery, comparison, and bounded graph construction more efficient.

Use cases

· Select seed papers for an AI research topic from more than one million conference papers and build a bounded paper graph.
· Let agents read structured problems, method components, experiment setups, metrics, findings, and their relations directly.
· Trace formulas, tables, results, citation semantics, and other Evidence to exact source paragraphs only when needed.
· Keep the complete citation list while drilling into resolved target papers.

Not for

· Use meta-search for broad bibliographic filtering, authors, venues, and analytics.
· Use agentic-search for open-ended full-text semantic retrieval.
· Citation Edge covers resolved references only and must not replace complete citation counts.

Capability boundaries

· Coverage is limited to schema-extracted papers and does not replace broad meta-search coverage.
· All child paths share the paper-schema quota, while each operation keeps explicit request and capacity limits.
· Complete citations and the resolved citation graph are separate layers; unresolved references are never fabricated into graph edges.

Authentication

Every /paper-schema subpath uses the shared Sciverse API token. Create a token in the console and send it in the Authorization: Bearer header. Never put tokens in URLs, request bodies, browser-side code, or logs.

Create an API token in the console

export SCIVERSE_API_TOKEN='YOUR_API_TOKEN'

curl -X POST https://api.sciverse.space/paper-schema/search \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: paper-schema-example-001" \
  -d '{"query":"large language model agent","filters":{"published_year_gte":2022},"size":5}'

· 401 means the token is missing, malformed, invalid, or the account is disabled. Fix authentication before retrying.
· 403 means the token is valid but the account lacks the capability or field permission. Request access instead of retrying.
· 429 means an account, paper-schema resource, or source quota was reached. Wait for Retry-After or retry_after.
· Clients may send X-Request-ID; the gateway also generates and returns one. Keep it for troubleshooting.
· All 18 operations share one paper-schema authentication and quota resource; separate tokens per subpath are not required.

Request example

curl -X POST https://api.sciverse.space/paper-schema/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"large language model agent","filters":{"published_year_gte":2022},"size":5}'

# Select one items[].schema_id from the response, then set:
export SCHEMA_ID='schema_xxx'

18 detailed operations

Capability

Read the public contract version, capabilities, Entity/Relation/Evidence taxonomies, and request limits.

GET/paper-schema

Capability discovery

Returns the current public contract version, supported Entity, Relation, and Evidence types, and key limits; use it for capability discovery, not health checks.

Overview

Discover the Paper Schema contract version, public resources, Entity/Relation/Evidence taxonomies, and capacity limits. This is a stable capability contract, not a health check.

Use cases

· Let an SDK or Skill verify the active contract version.
· Read public taxonomies and batch limits dynamically.

Not for

· Do not use it to monitor service health or test whether a paper exists.

Request parameters

Field	Type	Required	Description
Authorization	header string	Required	Sciverse API Token in Bearer <token> format.

Request example

curl https://api.sciverse.space/paper-schema \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

Response structure

Field	Type	Description
contract_version	string	Public API contract version.
resources	array<string>	Available public resources.
entity_taxonomy / relation_taxonomy	object	Public Entity and Relation categories.
evidence_groups	array<string>	Allowed high-value Evidence groups.
limits	object	Pagination, batch, and graph limits.

Parameter bounds

Authentication and usage: Counted under paper-schema

Notes

· Clients may cache the capability contract; use the corresponding query operation to test whether a resource exists.

Paper Discovery

Discover papers through metadata keywords, Entity semantics, or multi-signal expansion from a known paper; results are always papers.

POST/paper-schema/search

Keyword and metadata paper search

Matches public title, abstract, author, venue, topic, research-problem, contribution, and DOI fields with optional metadata filters.

Overview

The result unit is always a paper. query performs lexical relevance search over titles, abstracts, research problems, central contributions, headline results, document theses, topics, tasks, authors, and venues. It is not a natural-language QA or full-text vector search endpoint; Skills and LLMs should extract focused academic keywords from long questions first.

Use cases

· Find schema-extracted papers by research topic, method, or task.
· Locate a paper by DOI or combine keywords with year, author, venue, code, and data filters.
· Obtain schema_id values for Entity, internal Relation, Evidence, and external Citation drill-down.

Not for

· Use entities/search to find Dataset, Problem, and other structured objects.
· Use agentic-search for open-ended full-text semantic retrieval.
· Use meta-search for broad bibliographic filtering and export.

Request body (JSON)

Field	Type	Required	Description
query	string	Optional	Keywords matched against paper metadata and primary structured semantic fields. Range 1–500 characters
filters	object	Optional	Paper metadata filters. At least one of query or filters is required. Default {}
sort	array<SortItem>	Optional	Sort by year, metrics.citation_count, metrics.reference_count, or metrics.fwci. Defaults to relevance with query and stable ID order without query. Range up to 2
size	integer	Optional	Number of papers returned per page. Default 20Range 1–100
cursor	string	Optional	Opaque deep-pagination token returned by the service.

Available filter fields

Field	Type	Value	Description
schema_ids	array<string>	up to 100	Restrict results to exact Paper Schema IDs.
dois	array<string>	up to 100	Find exact normalized DOI values.
authors	array<string>	up to 20	Filter by normalized author names.
venues	array<string>	up to 50	Filter by normalized venue names.
published_year_gte / published_year_lte	integer	1800–2200	Restrict the publication year range.
has_code	boolean	true / false	Filter on code-resource signals.
has_data	boolean	true / false	Filter on data-resource signals.
is_oa	boolean	true / false	Filter on open-access status.

Request example

{
  "query": "large language model agent",
  "filters": {
    "published_year_gte": 2022,
    "has_code": true
  },
  "size": 20
}

Response structure

Field	Type	Description
total	object	Total paper hits and count relation; broad queries may use a bounded total.
items	array<object>	Paper cards; every result item is a paper.
items[].schema_id	string	Public Paper Schema ID for structured-resource drill-down.
items[].title / abstract	string	Paper title and abstract.
items[].authors / venue / year	array / string / integer	Authors, publication venue, and year.
items[].topics / tasks	array	Research topics and tasks.
items[].research_problem	string	Extracted and normalized research problem.
items[].central_contribution	string	Central paper contribution.
items[].headline_result	string	Headline result.
items[].has_code / has_data	boolean	Code and data resource signals.
next_cursor	string \| null	Cursor for the next page, or null when pagination is complete.

Response example

{
  "contract_version": "2026-07-15",
  "total": {"value": 138, "relation": "eq"},
  "items": [
    {
      "schema_id": "schema_xxx",
      "title": "Large Language Model Agents",
      "abstract": "...",
      "authors": ["Example Author"],
      "venue": "Example Conference",
      "year": 2024,
      "topics": ["Large Language Models"],
      "research_problem": "How to build reliable autonomous research agents",
      "central_contribution": "A structured agent framework",
      "headline_result": "Improved task completion",
      "has_code": true,
      "has_data": false
    }
  ],
  "next_cursor": "opaque-cursor"
}

Choose an API

Find papers by keywords, DOI, author, or year	`/paper-schema/search`
Find Dataset, Problem, and other structured objects	`/paper-schema/entities/search`
Expand papers from an Entity name	`/paper-schema/entities/related-papers`
Find papers related to a known paper	`/paper-schema/schemas/{schema_id}/related-papers`
Search text within one paper	`/paper-schema/search-in-schema`

Parameter bounds

query length: 1–500 characters
papers per page: 1–100
schema_ids / dois: up to 100 each
sort: up to 2 items

Notes

· Use filters.dois for exact DOI lookup instead of passing a sentence such as 'the DOI is ...' as query.
· Cross-paper expansion for the same Dataset or method belongs to Entity semantic discovery, not this endpoint.

POST/paper-schema/entities/related-papers

Expand papers from Entity semantics

Fuzzily matches Entity name, type, subtype, and description across papers without claiming canonical Entity identity.

Overview

Use a Dataset, Problem, Method, or Component name as a semantic clue, find similar Entities across papers, and aggregate them into paper candidates. A match means textual or semantic similarity, not globally resolved object identity.

Use cases

· Expand from a Dataset name to papers using similar data.
· Find papers around the same research problem or method component.

Not for

· Use schemas/{schema_id}/related-papers for multi-signal expansion from a known paper.
· Use entities/search when the result unit should remain an Entity.

Request parameters

Field	Type	Required	Description
query	string	Required	Entity name or short description. Range 1–500 characters
entity_types / entity_subtypes	array<string>	Optional	Public Entity type constraints.
exclude_schema_ids	array<string>	Optional	Exclude seed or already displayed papers. Range up to 100
size / cursor	integer / string	Optional	Page size and opaque cursor. Default 20 / null

Request example

{
  "query": "MMLU",
  "entity_types": ["Resource"],
  "entity_subtypes": ["Dataset"],
  "size": 20
}

Response structure

Field	Type	Description
items[].schema_id	string	Candidate paper ID.
items[].schema_paper	object	Paper metadata card.
items[].matched_entities	array<object>	Entities that produced the match.
items[].match_reasons	array<string>	Explainable match reasons.
next_cursor	string \| null	Next-page cursor.

Parameter bounds

Papers per page: 1–100
Identity: Semantic match only

Notes

· Cross-paper entity_id matching is intentionally not public because IDs are paper-local.

POST/paper-schema/schemas/{schema_id}/related-papers

Find papers related to a known paper

Combines Entity, keyword, and Citation signals into explainable candidates for a known paper.

Overview

Read topics, keywords, and key Entities from the path seed paper, optionally add resolved Citation Edges, then return deduplicated candidates. The term request value denotes the keyword signal, and each result reports per-signal contributions.

Use cases

· Continue discovery after reading one paper.
· Select one-hop candidates for a topic graph.

Not for

· Use citations for the complete reference list; citation is only one relevance signal here.

Request parameters

Field	Type	Required	Description
schema_id	path string	Required	Seed paper ID.
signals	array<term\|entity\|citation>	Optional	Signals used for candidate generation. Default all threeRange 1–3
exclude_same_work	boolean	Optional	Exclude other versions of the same work. Default true
size	integer	Optional	Candidate count. Default 20Range 1–50

Request example

{
  "signals": ["entity", "citation"],
  "exclude_same_work": true,
  "size": 20
}

Response structure

Field	Type	Description
seed	object	Seed paper summary.
items[].schema_id	string	Related paper ID.
items[].score_components	object	Score contributions from term, entity, and citation signals.
items[].reasons	array<string>	Human-readable reasons.

Parameter bounds

Candidates: 1–50
Citation: Resolved paper edges only

Notes

· Unresolved References remain available through citations but do not contribute to citation relevance.

Entity

Discover and inspect structured objects within papers.

POST/paper-schema/entities/search

Entity search

Returns matching Problem, Component, Finding, Measure, Resource, Reference, and other structured objects rather than papers.

Overview

Search structured objects across papers. The result unit is an Entity, which is useful for Dataset, Problem, Finding, Measure, Resource, and Reference discovery. Use entities/related-papers when the final result should be papers.

Use cases

· Find Dataset/Resource Entities named MMLU.
· Locate Problems or metrics inside a known set of papers.

Not for

· This is not paper search and does not merge similar Entities into one global object.

Request parameters

Field	Type	Required	Description
query	string	Optional	Matches Entity names, titles, text, and descriptions; required without schema_ids. Range 1–500 characters
filters.schema_ids	array<string>	Optional	Paper scope. Range up to 100
filters.entity_types / entity_subtypes	array<string>	Optional	Public type constraints.
filters.sections	array<string>	Optional	Source-section filter. Range up to 50
hydrate_schema_papers	boolean	Optional	Attach paper cards. Default false
size / cursor	integer / string	Optional	Pagination. Default 20 / nullRange 1–100

Request example

{
  "query": "MMLU",
  "filters": {
    "entity_types": ["Resource"],
    "entity_subtypes": ["Dataset"]
  },
  "hydrate_schema_papers": true,
  "size": 20
}

Response structure

Field	Type	Description
items[].schema_id / entity_id	string	Owning paper and paper-local Entity ID.
items[].entity_type / entity_subtype	string	Public taxonomy.
items[].name / text	string	Object name and description.
items[].provenance	array<object>	Source locators.
items[].schema_paper	object \| null	Optional paper card.

Parameter bounds

Entities per page: 1–100
Without query: schema_ids required

Notes

· entity_id is for drill-down inside its owning paper, not cross-paper identity.

GET/paper-schema/schemas/{schema_id}/entities

Entities in one paper

Paginates all Entities in one paper or filters by type, subtype, and section.

Overview

Read the complete, paginated Entity collection for one paper. This is the main answer to 'what structured objects are in this paper' and is not goal-truncated like Materials.

Use cases

· Load all nodes for a paper graph.
· Read only Problem, Resource/Dataset, or Finding Entities.

Not for

· Use entities/search across papers and materials for goal-oriented selection.

Request parameters

Field	Type	Required	Description
schema_id	path string	Required	Paper ID.
entity_types / entity_subtypes	query array<string>	Optional	Type filters.
sections	query array<string>	Optional	Section filter.
size / cursor	query integer / string	Optional	Pagination. Default 50 / nullRange 1–100

Request example

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/entities?entity_types=Resource&entity_subtypes=Dataset&size=50" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

Response structure

Field	Type	Description
schema_id	string	Current paper.
total	object	Filtered Entity total.
items	array<Entity>	Entity page.
next_cursor	string \| null	Next-page cursor.

Parameter bounds

Page size: 1–100

Notes

· Follow next_cursor for completeness; a Materials returned array is not a complete Entity set.

GET/paper-schema/schemas/{schema_id}/entities/{entity_id}

Entity detail

Reads one node in the current paper for Relation endpoint, Evidence, and provenance drill-down.

Overview

Read one paper-local Entity and optionally its adjacent internal Relations. Calls usually originate from Entity lists, Relation endpoints, or an Evidence source_entity_id.

Use cases

· Load node details after a graph click.
· Move from Evidence or Relation back to its source Entity.

Not for

· Do not reuse entity_id to identify an object in another paper.

Request parameters

Field	Type	Required	Description
schema_id / entity_id	path string	Required	Paper and paper-local Entity IDs.
include_relations	query boolean	Optional	Include adjacent internal Relations. Default false
relation_limit	query integer	Optional	Adjacent-relation limit. Default 50Range 1–100

Request example

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/entities/ENTITY_ID?include_relations=true&relation_limit=20" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

Response structure

Field	Type	Description
entity	object	Entity type, name, text, section, and provenance.
relations	array<object>	Optional adjacent Relations.
relations_truncated	boolean	Whether the relation limit was reached.

Parameter bounds

Adjacent Relations: up to 100

Notes

· An Entity missing from the given schema_id returns 404.

Internal Relations

Query within-paper structural relations in a known paper or Entity scope; paper-to-paper citations belong to Citations.

POST/paper-schema/relations/search

Internal Relation query

Queries public within-paper relation types inside specified schema_id or Entity scopes.

Overview

Query structural links between Entities inside papers, such as uses_component, evaluates, reports_metric, supports, and resolves. At least one paper, endpoint-Entity, or relation-type constraint is required.

Use cases

· Connect method components to Problems and Findings.
· Read experimental links adjacent to Dataset or Measure nodes.

Not for

· Use Citations for paper-to-paper citation relationships.

Request parameters

Field	Type	Required	Description
filters.schema_ids	array<string>	Optional	Paper scope. Range up to 100
filters.source_entity_ids / target_entity_ids	array<string>	Optional	Endpoint constraints. Range up to 100 each
filters.relation_types	array<string>	Optional	Public relation types. Range up to 50
evidence_query	string	Optional	Keyword constraint on relation evidence. Range 1–500 characters
include_context	none\|entities	Optional	Attach endpoint summaries. Default none
size / cursor	integer / string	Optional	Pagination. Default 20 / nullRange 1–100

Request example

{
  "filters": {
    "schema_ids": ["SCHEMA_ID"],
    "relation_types": ["evaluates", "reports_metric"]
  },
  "include_context": "entities",
  "size": 50
}

Response structure

Field	Type	Description
items[].relation_id / relation_type	string	Paper-local Relation ID and public type.
items[].source_entity_id / target_entity_id	string	Relation endpoints.
items[].source_entity / target_entity	object \| null	Optional endpoint summaries.
items[].provenance	array<object>	Evidence locators.

Parameter bounds

Relations per page: 1–100
Guardrail: At least one structural filter

Notes

· Use relation_taxonomy from capability discovery for supported relation categories.

GET/paper-schema/schemas/{schema_id}/relations/{relation_id}

Relation detail

Reads one logical Relation, endpoint summaries, and merged provenance.

Overview

Read one within-paper Relation, normally with source/target Entity summaries and merged evidence locators. This is the drill-down endpoint for graph-edge clicks.

Use cases

· Inspect a structural edge and both endpoint nodes.
· Trace the relation evidence back to source paragraphs.

Not for

· It does not return paper-level Citation Edges.

Request parameters

Field	Type	Required	Description
schema_id / relation_id	path string	Required	Paper and paper-local Relation IDs.
include_context	query boolean	Optional	Include endpoint and evidence context. Default true

Request example

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/relations/RELATION_ID?include_context=true" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

Response structure

Field	Type	Description
relation	object	Logical public Relation fields.
source_entity / target_entity	object \| null	Endpoint summaries.
provenance	array<object>	Deduplicated source locators.

Parameter bounds

Scope: Within one paper

Notes

· A relation_id outside the given schema_id returns 404.

External Citations

A Reference is a bibliography node inside a paper, while citations returns the complete citation list. Only resolved References become paper-level Citation Edges for citation-graph drill-down; graph edges do not equal complete reference or external citation counts.

GET/paper-schema/schemas/{schema_id}/citation-summary

Citation summary

Separates complete Reference/Citation totals, resolution coverage, and paper-level inbound/outbound edges.

Overview

Return complete reference counts, citation-Relation counts, resolved and unresolved References, corpus paper-level outbound edges, and inbound counts in one request.

Use cases

· Show reference totals and resolution coverage.
· Check graph availability before loading citation details.

Not for

· It returns counts, not individual References or edges.

Request parameters

Field	Type	Required	Description
schema_id	path string	Required	Current paper ID.

Request example

curl https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/citation-summary \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

Response structure

Field	Type	Description
outbound.reference_count_total	integer	Complete Reference Entity count.
outbound.resolved_reference_count / unresolved_reference_count	integer	Resolution counts.
outbound.resolution_coverage	number	Resolution coverage ratio.
outbound.resolved_target_schema_count	integer	Drillable target papers.
inbound.external_citation_count	integer \| null	External metadata citation total.
inbound.resolved_corpus_edge_count	integer	Resolved inbound corpus edges.

Parameter bounds

Query: One-paper aggregation

Notes

· A resolution count below the reference total is coverage, not missing citation data.

GET/paper-schema/schemas/{schema_id}/citations

Complete external citation list

Returns both resolved and unresolved citations; the original Reference remains even when no target paper is resolved.

Overview

Page complete Reference information from citation Relations. Every original citation remains; resolved items additionally expose target_schema_id and a target paper card, while unresolved items are marked explicitly.

Use cases

· Render a complete bibliography.
· Offer target-paper drill-down without hiding unresolved references.

Not for

· Use citation-graph for multi-hop paper graphs.

Request parameters

Field	Type	Required	Description
schema_id	path string	Required	Current paper ID.
size	query integer	Optional	References per page. Default 50Range 1–100
cursor	query string	Optional	Opaque next-page cursor.

Request example

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/citations?size=50" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

Response structure

Field	Type	Description
total	integer	Complete citation-Relation total.
items[].relation / reference	object	Original relation and Reference metadata.
items[].resolution.status	resolved\|unresolved\|target_unavailable	Resolution status.
items[].resolution.target_schema_id	string \| null	Drillable target paper.
items[].target_schema	object \| null	Resolved target paper card.
next_cursor	string \| null	Next-page cursor.

Parameter bounds

Page size: 1–100

Notes

· Use total/References for complete counts, not only items with target_schema_id.

GET/paper-schema/schemas/{schema_id}/citation-graph

Paper citation graph

Expands resolved paper-level Citation Edges by direction, depth, and node limits.

Overview

Expand only resolved paper-level Citation Edges for one to three hops in outbound or inbound direction. Unresolved References are never invented as graph nodes.

Use cases

· Build a bounded citation graph around a seed paper.
· Explore corpus-level inbound or outbound citation neighborhoods.

Not for

· This is not the complete bibliography or the full external citation network.

Request parameters

Field	Type	Required	Description
schema_id	path string	Required	Root paper ID.
direction	outbound\|inbound	Optional	Expansion direction. Default outbound
depth	integer	Optional	Expansion depth. Default 1Range 1–3
max_nodes / max_edges	integer	Optional	Hard graph bounds. Default 100 / 200Range nodes 2–500, edges 1–500

Request example

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/citation-graph?direction=outbound&depth=1&max_nodes=100&max_edges=200" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

Response structure

Field	Type	Description
root_schema_id / direction	string	Root and direction.
nodes	array<object>	Paper nodes and availability.
edges	array<object>	Resolved source-target Citation Edges.
levels	array<object>	Per-depth frontier statistics.
truncated	boolean	Whether graph bounds were reached.

Parameter bounds

Depth: up to 3
Nodes/edges: up to 500 each

Notes

· When truncated=true, reduce depth or continue from selected nodes in bounded requests.

Evidence & Content

Search structured formulas, tables, results, resources, and citation semantics, then trace Evidence or structured objects to source text when needed.

POST/paper-schema/evidence/search

Structured evidence search

Searches formulas, tables, results, comparisons, resources, and citation semantics by public evidence categories and keywords.

Overview

Search high-value structured Evidence retained by the hot policy. Select one to five public groups and provide at least one narrowing condition such as schema_ids, query, key, path_bucket, numeric range, or boolean value.

Use cases

· Find formulas, table results, method comparisons, and code/data resources.
· Locate citation signals or experimental results across selected papers.

Not for

· Use Entities for complete objects and search-in-schema for arbitrary paper text.

Request parameters

Field	Type	Required	Description
groups	array<string>	Required	One or more public Evidence groups. Range 1–5
group_operator	any\|all	Optional	Group combination. Default any
schema_ids	array<string>	Optional	Paper scope. Range up to 100
query / key / path_bucket	string	Optional	Text, property-key, or path constraint.
value_number_min / value_number_max / value_bool	number / boolean	Optional	Structured value filters.
hydrate_schema_papers	boolean	Optional	Attach paper cards. Default false
size / cursor	integer / string	Optional	Pagination. Default 20 / nullRange 1–100

Request example

{
  "groups": ["formula", "table_evidence"],
  "group_operator": "any",
  "schema_ids": ["SCHEMA_ID"],
  "query": "accuracy",
  "size": 20
}

Response structure

Field	Type	Description
items[].evidence_id	string	Public Evidence ID.
items[].groups / key / value_*	array / scalar	Evidence classification, property, and normalized value.
items[].source_entity_id / source_relation_id	string \| null	Source structured object.
items[].provenance	array<object>	Source locators.
next_cursor	string \| null	Next-page cursor.

Parameter bounds

Groups: 1–5
Page size: 1–100

Notes

· Evidence search returns normalized fields and source locators defined by the public Evidence contract.

GET/paper-schema/schemas/{schema_id}/evidence/{evidence_id}

Evidence detail

Reads one normalized Evidence value, its source objects, and provenance.

Overview

Read one Evidence item by schema_id and evidence_id, including normalized values, public groups, source Entity/Relation references, and provenance.

Use cases

· Open the full value from an Evidence search result.
· Continue from Evidence to its source object or paragraph.

Not for

· It does not return unprocessed extraction payloads or the full paper text.

Request parameters

Field	Type	Required	Description
schema_id / evidence_id	path string	Required	Paper and Evidence IDs.

Request example

curl https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/evidence/EVIDENCE_ID \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

Response structure

Field	Type	Description
evidence	object	Public group, key, and normalized values.
source	object	Source Entity or Relation reference.
provenance	array<object>	Marker and paragraph locators.

Parameter bounds

Scope: One Evidence in one paper

Notes

· An Evidence ID outside the given schema_id returns 404.

POST/paper-schema/resolve-provenance

Resolve source location

Locates source paragraphs and bounded neighbors by marker or paragraph_id.

Overview

Resolve locators stored on Evidence, Entity, or Relation objects into source paragraphs. Choose exactly one mode: schema_id plus marker_nums, or paragraph_ids.

Use cases

· Verify a structured claim against the source text.
· Highlight evidence paragraphs with bounded context.

Not for

· Use search-in-schema when no locator is available.

Request parameters

Field	Type	Required	Description
schema_id + marker_nums	string + array<int>	Optional	A marker is an opaque paper-local locator returned by Evidence or another structured object; send it back unchanged. Range up to 100 markers
paragraph_ids	array<string>	Optional	Global paragraph-ID mode; mutually exclusive with markers. Range up to 100
window	integer	Optional	Neighbor paragraphs around each hit. Default 0Range 0–5
max_segments	integer	Optional	Total segment limit. Default 40Range 1–100

Request example

{
  "schema_id": "SCHEMA_ID",
  "marker_nums": [12, 13],
  "window": 1,
  "max_segments": 20
}

Response structure

Field	Type	Description
segments	array<object>	Paragraph IDs, sections, text, markers, and neighbor positions.
trace.mode	marker\|paragraph_id	Resolution mode.
missing	array	Unresolved locators.

Parameter bounds

Locators: up to 100
Context window: 0–5

Notes

· Only bounded paragraph context is returned, never the full paper.

POST/paper-schema/search-in-schema

Search text within one paper

Runs keyword search over one paper and returns matching content with locations; use it when no marker or paragraph_id is available.

Overview

Run bounded keyword retrieval over one known paper. This is the fallback when provenance locators are missing and supports section hints, URL/code preference, and context windows.

Use cases

· Locate a metric or resource name in one paper.
· Find context for Evidence without a marker.

Not for

· Use agentic-search across papers and Entity/Evidence search for structured objects.

Request parameters

Field	Type	Required	Description
schema_id	string	Required	Paper ID.
query	string	Required	Paper-text keywords. Range 1–500 characters
section_hint	string	Optional	Preferred section. Range up to 300 characters
prefer_url / prefer_code	boolean	Optional	Resource-search preference. Default false
top_k / window	integer	Optional	Hit and context bounds. Default 5 / 1Range top_k 1–20, window 0–5

Request example

{
  "schema_id": "SCHEMA_ID",
  "query": "source code repository",
  "prefer_url": true,
  "top_k": 5,
  "window": 1
}

Response structure

Field	Type	Description
segments	array<object>	Matching paragraphs and bounded context.
segments[].score	number	Within-paper relevance score.
trace	object	Search method and elapsed time.

Parameter bounds

top_k: 1–20
window: 0–5

Notes

· Scores are local to the selected schema_id and not comparable across papers.

POST/paper-schema/hydrate-items

Batch source-context hydration

Adds source paragraphs for up to 50 Entity, Relation, or Evidence items.

Overview

Resolve paragraph_ids, marker_nums, or fallback queries for multiple structured items in one call. Exact locators are preferred; single-paper fallback search runs only when locators are absent.

Use cases

· Hydrate multiple Evidence items in a material pack.
· Reduce per-item provenance requests.

Not for

· This is not bulk full-text retrieval.

Request parameters

Field	Type	Required	Description
items	array<HydrateItem>	Required	Each item has schema_id plus paragraph_ids, marker_nums, or hydration_query. Range 1–50
window	integer	Optional	Context window. Default 1Range 0–5
max_segments_per_item	integer	Optional	Per-item segment limit. Default 5Range 1–20
prefer_url_or_code	boolean	Optional	Fallback search preference. Default false

Request example

{
  "items": [
    {"schema_id": "SCHEMA_ID", "paragraph_ids": ["PARAGRAPH_ID"]},
    {"schema_id": "SCHEMA_ID", "hydration_query": "training setup"}
  ],
  "window": 1,
  "max_segments_per_item": 5
}

Response structure

Field	Type	Description
items[].hydration_method	paragraph_id\|marker\|schema_local_search\|none	Method used for each item.
items[].segments	array<object>	Hydrated source paragraphs.
items[].reason	string \| null	Reason when hydration is unavailable.

Parameter bounds

Batch items: up to 50
Segments per item: up to 20

Notes

· One item can fail without discarding others; inspect hydration_method and segments per item.

Research Materials

Builds bounded, goal-oriented materials for known papers; it does not replace complete Entity, Relation, or Evidence list APIs.

POST/paper-schema/materials

Research material pack

Returns paper metadata, Entities, internal Relations, Evidence, keywords, and optional citation context for overview, survey, benchmark, method, or reproduction goals, with total, returned, and truncated counts per resource.

Overview

Build bounded, goal-oriented context for known papers. goal selects priority Entity, Relation, and Evidence types. The result is an LLM/Skill-ready selection, not a replacement for complete list endpoints.

Use cases

· Prepare paper overview, survey, benchmark, method, or reproduction context.
· Build structured summaries for up to 20 known papers.

Not for

· Use base Entity, Relation, and Evidence endpoints with pagination for complete sets.

Request parameters

Field	Type	Required	Description
schema_ids	array<string>	Required	Target papers. Range 1–20
goal	overview\|survey\|benchmark\|method\|reproduction	Optional	Selection profile. Default overview
include_relation_context	boolean	Optional	Hydrate Relation endpoints. Default false
per_schema_entity_limit	integer	Optional	Entity limit per paper. Default 40Range 0–150
per_schema_relation_limit	integer	Optional	Relation limit per paper. Default 40Range 0–150
per_schema_attribute_limit	integer	Optional	Evidence limit per paper. Default 60Range 0–200
per_schema_term_limit	integer	Optional	Internal keyword limit per paper. Default 20Range 0–100

Request example

{
  "schema_ids": ["SCHEMA_ID"],
  "goal": "reproduction",
  "include_relation_context": true,
  "per_schema_entity_limit": 60,
  "per_schema_relation_limit": 60,
  "per_schema_attribute_limit": 100
}

Response structure

Field	Type	Description
items[].schema_paper	object	Paper metadata card.
items[].entities / relations / evidence / terms	array	Goal-selected materials.
items[].counts.<resource>.total	integer	Complete resource total.
items[].counts.<resource>.returned	integer	Items returned in this pack.
items[].counts.<resource>.truncated	boolean	Whether the profile limit truncated the resource.

Parameter bounds

Papers: up to 20
Evidence per paper: up to 200

Notes

· Whenever truncated=true, the returned array is not the complete structured set for that paper.

Common request fields

These fields apply only to operations that include them; use each expanded operation contract for required fields and bounds.

Field	Type	Required	Description
schema_id	string	Optional	Canonical Paper Schema paper ID; required in paths such as /schemas/{schema_id}.
cursor	string	Optional	Opaque pagination cursor; return it unchanged only when loading the next page, and never parse or construct it.

Response structure

Field	Type	Description
schema_id	string	Canonical paper identifier.
items / nodes / edges	array	Structured objects, evidence, or graph data returned by the selected operation.
next_cursor	string \| null	Next-page cursor; null means no next page.
partial	boolean	True when one or more dependent steps failed or degraded but usable results remain; inspect warnings before deciding whether to fetch again.
truncated	boolean	True when the request completed normally but reached an item, graph, or material-pack bound.
warnings	array<string>	Explains degraded dependencies, partial results, or other conditions requiring caller action.

Errors

Code	Message	Description
400/422	INVALID_REQUEST	The request violates narrowing rules or an operation limit.
401	UNAUTHORIZED	The token is missing, invalid, or disabled.
403	FORBIDDEN	The token is valid, but the account lacks Paper Schema or requested-field access.
404	NOT_FOUND	The schema_id, Entity, Relation, or Evidence item does not exist.
429	RATE_LIMITED	An account, paper-schema resource, or source quota was reached; inspect retry_after.
502/503	UPSTREAM_UNAVAILABLE	The structured-query service is unavailable or busy; retry with the request_id.
504	PAPER_SCHEMA_TIMEOUT	The query timed out; reduce graph depth, batch size, or result bounds before retrying.

See the Errors section for shared error codes.

Parameter bounds

Limit	Value
Default rate limit	The paper-schema resource defaults to 30 requests per minute per user; account rules may override it.
Daily call quota	Shared with other public APIs; the effective quota depends on console and account permissions.
Accounting scope	Every /paper-schema/* operation counts toward paper-schema while logs preserve the concrete operation path.
Per-request capacity	Each operation defines size, depth, max_nodes, max_edges, or batch bounds in its expanded contract.

Retry guidance

· Retry 502/503/504 with jittered exponential backoff such as 1s, 2s, and 4s, for at most three attempts.
· For 429, honor Retry-After or retry_after, both expressed in seconds; do not immediately retry concurrently.
· Do not automatically retry 400/401/403/404; fix the request, token, permission, or resource ID first.
· GET and POST operations with stable request bodies are retry-safe; reuse the same X-Request-ID for one logical request and record attempt numbers separately on the client.
· HTTP 200 with partial=true is not a complete success; inspect warnings before deciding whether to fetch again.

FAQ

Why is there only one paper-schema catalog entry?

It is an independent domain API, but all structure, evidence, and graph operations share one authentication, quota, and accounting resource.

Does the citation graph include every reference?

No. citations returns complete resolved and unresolved references; citation-graph returns only edges whose targets can be connected to schema_id.

How do I run survey, benchmark, or reproduction workflows?

Use paper-schema/search or related-paper discovery to choose schema_id values, then call materials with the survey, benchmark, method, or reproduction goal; use Entity, Relation, and Evidence APIs when complete resources are required.

What is the difference between partial and truncated?

partial=true means a dependent step failed or degraded but usable results remain, so inspect warnings. truncated=true means the request completed normally but reached an item or graph bound; paginate or narrow the next request.

Notes

· The catalog and traffic accounting treat this suite as one top-level paper-schema resource.
· Survey, benchmark, method comparison, reproduction, paper brief, and topic graph flows are composed from base operations and Materials profiles without duplicate scenario endpoints.

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