API Reference
Server-rendered REST and MCP contract summary for agents, SDKs, and operator workflows.
This page is intentionally useful without client JavaScript. Use it to verify the current OpenAPI version, auth model, machine-readable routes, and the key endpoint groups before you hand the surface to ChatGPT, Cursor, Claude, or your own runtime.
OpenAPI version
2.2.0
Primary server
https://sciencetostartup.com
Auth schemes
ApiKeyAuth, BearerAuth
Documented operations
125
Surface health
building / /docs/api
`/docs/api`, `/developers`, `/proof/freshness`, and the machine routes now read from the same surface-health manifest, so the OpenAPI version and trust state stay aligned.
The API reference matches the augmented OpenAPI document.
OpenAPI JSON
Canonical REST contract and surfaced examples.
Capability index
Developer routes, install guides, flows, and product graph.
MCP guide
Human-readable guide for the hosted MCP transport and setup flow.
MCP descriptor
Raw MCP transport descriptor and machine-readable endpoint metadata.
Public freshness ledger
Receipt-style freshness state for public proof surfaces.
AI plugin manifest
Additional agent discovery manifest for external clients.
Surface health manifest
Canonical route health, discovery version, and OpenAPI version from one shared source.
Surface health hub
Human-readable route and contract health mirrored from the manifest.
llms.txt
Use the same `s2s_...` developer key for REST, `whoami`, and remote MCP. The server binds workspace-native actions to the authenticated actor, so clients should verify identity first and never inject arbitrary user IDs.
The REST surface covers discovery, proof retrieval, dashboard, research, workspace, and sidekick routes. The MCP surface exposes the same core objects as agent tools and resources.
Core
Paper discovery, search, and export
Signal Fusion
Composite viability rankings combining multiple signals
Research
Semantic search, deep search, consensus, and extraction
Dashboard
Canonical dashboard snapshot, action rail, and bundle routes
Terminal
Sector, lab, author analytics, and diligence reports
Resources
Outcomes tracking and calibration
Verify key and docs
curl -H "Authorization: Bearer s2s_YOUR_KEY" \ "https://sciencetostartup.com/api/developers/whoami" curl -H "Authorization: Bearer s2s_YOUR_KEY" \ "https://sciencetostartup.com/api/openapi.json"
Initialize remote MCP
curl -X POST "https://sciencetostartup.com/api/mcp" \
-H "Authorization: Bearer s2s_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"clientInfo": { "name": "developer-docs", "version": "1.0.0" },
"capabilities": {}
}
}'Paper discovery, search, and export
/api/papers/{paperRef}Get canonical opportunity kernel for a paper
/api/surface-health.jsonFetch the canonical surface-health manifest
Returns route freshness, discovery version, OpenAPI version, and release policy from the shared public trust builder.
/api/v1/exportExport papers as CSV or JSON
Bulk export of papers matching filters. Use format=csv for spreadsheet import.
/api/v1/free/paper/{arxivId}Get a single paper (free tier)
Free-tier paper detail with reduced fields. Use Bearer s2s_ token.
Short routing file for agents and retrieval systems.
/api/v1/free/papersSearch papers (free tier)
Limited free-tier paper search. Returns basic fields only. Max 10 results. Use Bearer s2s_ token.
/api/v1/meGet current API key info and quota
Returns institution, permissions, and remaining rate-limit for the authenticated key. Use to verify credentials and check quota before batch operations.
/api/v1/metrics/sparklinesGet sparkline metrics for papers
Daily score/view/vote time-series for a set of papers. Use to render inline sparkline charts.
/api/v1/paper/{arxivId}Get a single paper by arXiv ID
Full paper detail including scores, analysis, evidence, and benchmarks. Use include_evidence or include_benchmarks to expand nested data.
/api/v1/paper/{arxivId}/relatedGet papers related to a given paper
Returns semantically similar papers based on embedding distance. Use to build citation graphs or recommendation feeds.
/api/v1/papersSearch and filter papers
General paper search with date range, score range, topic, and full-text filters. Use include_analysis=true for deep-dive analysis blob. Paginated.
/api/v1/sandbox/top-papersTop papers for sandbox/demo use
Unauthenticated endpoint returning curated top-scored papers. Use for demos and onboarding.
/api/v1/top-papersGet highest-scored papers
Papers ranked by viability score or date. Simpler than /papers, optimized for dashboards and daily digests.
/api/v1/topicsList canonical topics for authenticated clients
Returns the authenticated topic index plus a backward-compatible topics array derived from the shared public topic builder.
/api/v1/topics/publicFetch the public canonical topic index
Returns the lightweight public topic discovery index used by /topics, llms discovery files, and MCP topic enumeration.
/api/v1/trendsGet topic trend data over time
Time-series of paper counts and average scores by topic. Use for trend charts and momentum analysis.
Composite viability rankings combining multiple signals
/api/signal-fusion/paper/{paperRef}Get signal fusion paper bundle
/api/v1/signal-fusionGet Signal Fusion composite rankings
Proprietary composite score combining viability scoring, community predictions, vote momentum, and GitHub star velocity. The primary ranking endpoint.
Semantic search, deep search, consensus, and extraction
/api/v1/research/consensusGet scientific consensus on a claim
Analyzes the corpus to determine agreement/disagreement on a scientific claim. Returns supporting and opposing evidence.
/api/v1/research/deep-searchStart an async deep research search
Multi-step research workflow cross-referencing papers, patents, and external sources. Returns a run_id to poll.
/api/v1/research/deep-search/{runId}Poll deep search results
Check status and retrieve results of an async deep search run. Poll until status is completed or failed.
/api/v1/research/deep-search/{runId}/reportCompile a canonical report from a completed deep-search run
/api/v1/research/extractExtract structured data from papers
Extract specific fields (methods, datasets, metrics, findings) from papers using LLM-powered extraction.
/api/v1/research/paper/{arxivId}/documentFetch the canonical paper document graph with visual citations
Returns the paper document graph, parse metadata, source artifacts, and visual_citations[] proof anchors with normalized page bounding boxes and crop image URLs when available.
/api/v1/research/paper/{arxivId}/visual-citations/{citationId}/imageFetch a visual citation crop image
Streams the stored PNG crop for a paper visual citation, or a PNG missing-crop sentinel with x-s2s-crop-status when the page and bbox exist but the crop is not materialized yet.
/api/v1/research/report/{runId}Fetch a canonical research report bundle
/api/v1/research/report/{runId}/artifacts/{kind}Fetch a stored artifact from the canonical research report store
/api/v1/research/report/{runId}/diffFetch the deterministic diff for a canonical report rerun
/api/v1/research/report/{runId}/shareUpdate canonical report visibility
/api/v1/research/searchSemantic search across the paper corpus
Vector-similarity search using natural language queries. Returns ranked results with relevance scores.
Canonical dashboard snapshot, action rail, and bundle routes
/api/dashboard/action-railGet authenticated dashboard action rail
Returns the authenticated DashboardActionRailContract derived from bookmarks and workspace history for the selected snapshot date.
/api/dashboard/snapshotGet canonical dashboard snapshot
Returns the server-built DashboardSnapshotContract used by the homepage, including freshness, provenance, anomalies, trend points, and ranked paper cards.
/api/v1/dashboardGet bundled dashboard payload
Returns the canonical dashboard snapshot plus top paper cards and optional pulse or action-rail data in one agent-friendly response. Use format=markdown for CLI or LLM-oriented text output.
Sector, lab, author analytics, and diligence reports
/api/talent/paper/{paperRef}Get talent paper bundle
/api/terminal/paper/{paperRef}Get terminal paper bundle
/api/v1/terminal/alertsGet active alert notifications
Triggered alerts for saved searches, score thresholds, and new papers in tracked topics.
/api/v1/terminal/authors/{authorId}Get author profile and analytics
Author profile with publication history, h-index proxy, commercial signal density, and collaboration network.
/api/v1/terminal/diligenceRun a diligence report on a target
Comprehensive diligence report for a paper, lab, or author combining publication analysis, patent landscape, and competitive positioning.
/api/v1/terminal/labsList lab/institution analytics
Lab-level analytics: publication velocity, avg scores, top papers. Use for institutional scouting.
/api/v1/terminal/sectorsList sector analytics
Sector-level aggregates: paper count, avg viability, trend direction, top papers. Use for portfolio-level views.
Outcomes tracking and calibration
/api/v1/outcomesList paper outcomes (startups, OSS, acquisitions)
Track which papers led to real-world outcomes. Pass calibration=true for score-bucket accuracy metrics instead.
/api/v1/resources/alternativesFetch Alternatives resource data
Alternatives machine-readable public resource route.
/api/v1/resources/alternatives/{slug}Fetch Alternatives resource data
Alternatives machine-readable public resource route.
/api/v1/resources/benchmarkGet published benchmark artifact metadata
Returns the current and recent benchmark snapshots plus truthful export URLs, immutable artifact receipts, checksums, and schema version metadata.
/api/v1/resources/benchmark/exportDownload the current published benchmark artifact
Stable export route for the current published benchmark artifact. The PDF, JSON, and CSV variants all resolve from the same artifact receipt.
/api/v1/resources/comparisonsFetch Comparison Hubs resource data
Comparison Hubs machine-readable public resource route.
/api/v1/resources/comparisons/{slug}Fetch Comparison Hubs resource data
Comparison Hubs machine-readable public resource route.
/api/v1/resources/databaseQuery the public papers database
Returns production-backed paper rows, freshness metadata, applied filters, facets, and canonical CSV export links for /resources/database.
/api/v1/resources/datasetGet published dataset artifact metadata
Returns the current dataset export contract, immutable artifact receipt, schema version, and truthful download URLs.
/api/v1/resources/dataset/exportDownload the current published dataset artifact
Stable export route for the current published dataset artifact. JSON keeps normalized arrays while CSV deterministically flattens those fields.
/api/v1/resources/directoryFetch Directory resource data
Directory machine-readable public resource route.
/api/v1/resources/directory/{slug}Fetch Directory resource data
Directory machine-readable public resource route.
/api/v1/resources/directory/{slug}/reviewsFetch Directory resource data
Directory machine-readable public resource route.
/api/v1/resources/glossaryFetch Glossary resource data
Glossary machine-readable public resource route.
/api/v1/resources/glossary/{term}Fetch Glossary resource data
Glossary machine-readable public resource route.
/api/v1/resources/indexFetch the machine-readable public resource index
Returns the canonical registry of public resource pages, APIs, freshness keys, health keys, and trust metadata for the resources area.
/api/v1/resources/industry-indexFetch Industry Index resource data
Industry Index machine-readable public resource route.
/api/v1/resources/questionsFetch Questions resource data
Questions machine-readable public resource route.
/api/v1/resources/questions/{slug}Fetch Questions resource data
Questions machine-readable public resource route.
/api/v1/resources/state-reportsFetch State Reports resource data
State Reports machine-readable public resource route.
/api/v1/resources/state-reports/{slug}Fetch State Reports resource data
State Reports machine-readable public resource route.
/api/v1/resources/state-reports/{slug}/exportFetch State Reports resource data
State Reports machine-readable public resource route.
/api/v1/resources/use-casesFetch Use Cases resource data
Use Cases machine-readable public resource route.
/api/v1/resources/use-cases/{slug}Fetch Use Cases resource data
Use Cases machine-readable public resource route.
Usage metering and quota management
/api/build-loop/paper/{paperRef}Get build loop paper bundle
/api/buildability/{receiptId}Get buildability receipt snapshot
Returns a compact buildability receipt assembled from deterministic launch fixtures when present, otherwise canonical Build Loop and methodology surfaces. Wave 1 is read-only and precomputed for the public launch lane. Missing proof, requirement, or approval fields are blockers and must not be inferred.
/api/feed/buildable-papers.jsonBuildable papers JSON feed
Public JSON Feed of high-signal buildable papers with repo links and launch-pack pointers.
/api/v1/usageGet API usage statistics
Request counts for today and this month, broken down by endpoint. Includes rate limit status and key info.
Opportunity workspace object, run-log, and approvals
/api/feed/agent-runs.jsonWorkspace + sidekick run-log feed
JSON Feed for authenticated user's recent run-log entries with approval, cost, and freshness metadata.
/api/webhooks/workspace/contractsWorkspace webhook event contracts
Returns event names and payload schemas for run lifecycle and approval lifecycle webhooks.
/api/workspaceList Opportunity Workspaces
Returns workspace records for the authenticated user filtered by status.
/api/workspaceCreate workspace from seed
Creates (or reuses) an Opportunity Workspace seeded from paper/topic/evidence/deep-search source.
/api/workspace/{workspaceId}Get workspace detail
Returns workspace, source attachments, memory summary, run-log slice, and background summary.
/api/workspace/{workspaceId}/approve/{runId}Resolve pending run approval
Approves or rejects a pending high-stakes run. Approved runs resume execution through the kernel.
/api/workspace/{workspaceId}/refreshTrigger workspace/sidekick action
Runs one of the registered workspace action kinds and writes through the universal run-log contract.
/api/workspace/{workspaceId}/runsList workspace run-log entries
Returns recent runs for the workspace including status, approval state, freshness snapshot, and estimated cost.
Control plane for briefs, background jobs, and founder actions
/api/feed/agent-runs.jsonWorkspace + sidekick run-log feed
JSON Feed for authenticated user's recent run-log entries with approval, cost, and freshness metadata.
/api/sidekick/workspace/{workspaceId}/backgroundGet sidekick background overview
Returns pending approvals, recent runs, modal schedules, freshness, and cost transparency summaries.
/api/webhooks/workspace/contractsWorkspace webhook event contracts
Returns event names and payload schemas for run lifecycle and approval lifecycle webhooks.
/api/workspace/{workspaceId}/approve/{runId}Resolve pending run approval
Approves or rejects a pending high-stakes run. Approved runs resume execution through the kernel.
/api/workspace/{workspaceId}/refreshTrigger workspace/sidekick action
Runs one of the registered workspace action kinds and writes through the universal run-log contract.
/api/buildability/brier-outcomesGet public Brier outcome ingestion state
Returns public outcome receipt ingestion state and the Foresight hindsight public ledger. The route stays pending until enough externally verified public outcome receipts and a verified public Brier receipt exist.
/api/v1/foresight/backtestsList featured Foresight backtests
Featured backtest runs plus their featured example outcomes. Calibration baseline + headline stat + lineage hash are returned per run.
/api/v1/foresight/paper/{arxivId}Get one Foresight paper pack
Single-paper bundle with live score decomposition + the latest valid frozen prediction. Equivalent to `/score?arxiv_id=…` returned with a path parameter so it composes with `/foresight/reasoning/{arxivId}`.
/api/v1/foresight/predictionsList public Foresight predictions
Paginated public prediction ledger. Rows include `lineage_verification_status`; only rows marked `verifiable` carry canonical 64-hex lineage suitable for verification surfaces.
/api/v1/foresight/scoreScore one Foresight paper
Live signal-fusion score decomposition plus the latest valid public frozen prediction when one exists. `frozen_prediction` is null when the paper is outside the public batch.
/api/v1/foresight/searchSearch published Foresight papers
Public paper search used by the Foresight reasoning + API picker surfaces. Returns paper headers (arxiv_id, title, slug, viability_score) for the matched corpus.
/api/capabilities.jsonMachine-readable ScienceToStartup capability index
Product graph for REST, MCP, llms discovery, Buildability Wave 1 launch surfaces, and Phase 7 pending signed receipt verifier gates.
/api/developers/whoamiInspect the authenticated developer actor
Returns the authenticated developer key owner, tier, rate limits, and workspace access for the provided bearer token.
/api/mcpInspect the remote MCP descriptor
Returns the hosted MCP transport descriptor, including the tiny Buildability Wave 1 public launch subset: read-mostly, precomputed, signed-when-available, no live internet rummaging, and explicit always_ask approval posture for mutating tools outside the subset.
/api/buildability/{receiptId}Get buildability receipt snapshot
Returns a compact buildability receipt assembled from deterministic launch fixtures when present, otherwise canonical Build Loop and methodology surfaces. Wave 1 is read-only and precomputed for the public launch lane. Missing proof, requirement, or approval fields are blockers and must not be inferred.
/api/buildability/attemptsSubmit authenticated build-attempt telemetry
Accepts real authenticated build-attempt telemetry for a paper. Requires a Bearer developer key bound to a user, rejects fake fixture input and client-controlled completion claims, redacts logs/secrets, deduplicates by Idempotency-Key or telemetry hash, and keeps live telemetry/adoption gates pending until persisted thresholds are met.
/api/buildability/brier-outcomesGet public Brier outcome ingestion state
Returns public outcome receipt ingestion state and the Foresight hindsight public ledger. The route stays pending until enough externally verified public outcome receipts and a verified public Brier receipt exist.
/api/buildability/clustersList buildability receipt clusters
Lists deterministic fixture clusters and real-public receipt clusters with fixture, unsigned real, and signed real counts separated.
/api/buildability/clusters/{slug}Fetch one buildability receipt cluster
Returns fixture receipt links and real-public receipt records for one cluster. Missing real receipts keep the route useful while preserving blocked-state truth.
/api/buildability/cohortFetch the public buildability receipt cohort state
Returns fixture seed counts separately from real public receipt packages, real unsigned receipts, and real signed external receipts. Deterministic fixtures never count toward public cohort volume, signed receipts, Wave 7 completion, telemetry, adoption, Brier, or divergence evidence.
/api/buildability/divergenceGet buildability judge-run divergence state
Returns the public judge-run divergence manifest, receipt source, blockers, and links. The route returns 200 with blocked_missing_judge_runs or pending_judge_runs until real external public-data judge-run receipts with hashes are supplied and verified.
/api/buildability/schemaGet buildability contract schemas
Returns shared BuildabilityReceipt and WaveCompletionReceipt schemas with unsigned external-gate verifier metadata.
/api/buildability/verify-receiptInspect the fail-closed Buildability receipt verifier
Returns usage metadata for the ed25519 receipt verifier. Unsigned, placeholder, fixture, or metadata-only receipts do not count as Wave 7 completion.
/api/buildability/verify-receiptVerify a Buildability or proof-wave receipt signature
Checks an ed25519 signature package against canonical BuildabilityReceipt or WaveCompletionReceipt JSON. The result remains fail-closed unless the cryptographic signature verifies and the receipt contract already carries verified external signature state with closed external gates.
/api/proof/wavesList proof wave completion receipts
Returns canonical Wave 0/1 completion receipts and unsigned external-gate verifier metadata. External signatures, pilot telemetry, registry approvals, production adoption, and Brier outcomes are not fabricated.
/api/proof/waves/{wave}Get one proof wave completion receipt
Returns one canonical Wave 0/1 completion receipt and its buildability receipt. Open external gates remain explicit blockers.
/api/proof/waves/verifyVerify proof wave artifact manifests
Verifies Wave 0/1 proof artifact manifests, receipt hashes, transcript hashes, and pending founder_signoff state. Current unsigned artifacts do not count complete.
/api/buildability/verify-receiptVerify a Buildability or proof-wave receipt signature
Checks an ed25519 signature package against canonical BuildabilityReceipt or WaveCompletionReceipt JSON. The result remains fail-closed unless the cryptographic signature verifies and the receipt contract already carries verified external signature state with closed external gates.
/api/proof.jsonSigned proof-feed (P3 Slice 05)
Returns >=1000 scored paper entries, each signed with the founder ed25519 key. Signatures are verifiable offline against the inlined `public_key_pem_inline` (which matches `/.well-known/founder-pubkey.pem` byte-for-byte). Pagination via `?cursor=` for >1000 entries.
/api/proof/wavesList proof wave completion receipts
Returns canonical Wave 0/1 completion receipts and unsigned external-gate verifier metadata. External signatures, pilot telemetry, registry approvals, production adoption, and Brier outcomes are not fabricated.
/api/proof/waves/{wave}Get one proof wave completion receipt
Returns one canonical Wave 0/1 completion receipt and its buildability receipt. Open external gates remain explicit blockers.
/api/proof/waves/{waveId}Fetch one public proof-wave receipt bundle
Returns one wave completion receipt, its paired buildability receipt, canonical hashes, and verifier state. Signed status requires a verified external founder signature.
/api/proof/waves/verifyVerify proof wave artifact manifests
Verifies Wave 0/1 proof artifact manifests, receipt hashes, transcript hashes, and pending founder_signoff state. Current unsigned artifacts do not count complete.
/api/trends/archiveList public Trends archive snapshots or check one date
Returns resolvable public archive entries with pagination metadata, or with date verifies exact snapshot availability. Archive entries only advertise dates with public production narratives.
/api/trends/deskGet the public Trends signal desk
Returns the production Trends desk with deskState, dataOrigin, degradedReason, provenance, coverage, watchlist, narratives, topics, entities, and source-count truth. Optional date must be YYYY-MM-DD and returns that exact materialized desk or a degraded/unavailable state.
/api/trends/entitiesList public Trends entities or get one exact entity
Returns URL-query-compatible entity collection data, or with slug returns an exact entity lookup independent of collection pagination.
/api/trends/historicalGet public Trends historical series
Returns historical Trends data. Legacy array compatibility is preserved while envelope mode exposes desk truth and query metadata.
/api/trends/methodologyGet public Trends methodology
Returns methodology, deskState, dataOrigin, and degradedReason for the active Trends desk.
/api/trends/narrativesList public Trends narratives
Returns URL-query-compatible narrative collection data with desk truth metadata and pagination metadata.
/api/trends/narratives/{slug}Get one public Trends narrative
Returns one production-backed public narrative by slug with desk truth metadata and links to HTML and markdown twins. Missing or malformed slugs do not fall back to synthetic production data.
/api/trends/sourcesList public Trends source coverage
Returns source coverage with desk truth metadata. count matches the public coverage roster.
/api/trends/topicsList public Trends topics or get one exact topic
Returns URL-query-compatible topic collection data, or with slug returns an exact topic lookup independent of collection pagination.
/api/v1/trends/desk-compactGet the compact public Trends signal desk
Returns a compact agent payload derived from the same production Trends desk. stats.sources equals the full public coverage roster, while sources may be sampled for compactness.
/api/research/searchCanonical Signal Canvas search
Citation-first search contract used by Signal Canvas corpus, paper, and workspace modes.
/api/research/search/streamCanonical Signal Canvas SSE stream
Streams events in fixed order: status, planner, answer, done.
/api/research/threadsList Signal Canvas research threads
Authenticated thread listing for workspace and saved Signal Canvas runs.
/api/research/threads/{threadId}Get a Signal Canvas research thread
Returns saved turns for one persisted Signal Canvas thread.
/api/freshness.jsonGet per-category corpus freshness snapshot
Returns per-category (cs.AI, cs.LG, cs.CL, stat.ML) freshness data including staleness hours, paper counts for last 24h and 7d, and a three-tier status (fresh/stale/critical). Cache-Control: public, s-maxage=300, stale-while-revalidate=600.
/api/freshness.jsonGet per-category corpus freshness snapshot
Returns per-category (cs.AI, cs.LG, cs.CL, stat.ML) freshness data including staleness hours, paper counts for last 24h and 7d, and a three-tier status (fresh/stale/critical). Cache-Control: public, s-maxage=300, stale-while-revalidate=600.
/api/batch_jobs/recent.jsonRecent BatchScheduler jobs (P1 Slice 04)
Returns last-window batch_jobs rows with cost_actual_usd vs cost_estimated_usd_at_list_price per provider. Backs the Karpathy slice-04 cost-ceiling check (PRD §8.2).
OpenAPI
Machine-readable REST contract for search, proof retrieval, Signal Canvas, and exports.
MCP guide
Human-readable setup guide for the remote MCP transport, tools, resources, and workspace actions.
Capability index
Product graph covering proof surfaces, install paths, and canonical action flows.
llms.txt
Short routing file for agents choosing between proof, developer, and install surfaces.
llms-full.txt
Exhaustive corpus and contract inventory for retrieval systems and agent builders.
AI plugin manifest
Additional discovery manifest for external agent clients.
Developer feed
Syndication feed for docs, install guides, examples, and use cases.
Developer sitemap
Dedicated sitemap for developer docs and machine-readable guides.