{"openapi":"3.0.0","paths":{"/records":{"get":{"operationId":"RecordController_findAll","summary":"List datasets with SHARE scores","description":"Returns a paginated list of scientific datasets with their SHARE scores and metadata. Supports full-text search on title and DOI, filtering by repository, and sorting by any score component. Results include all 25 SHARE signal indicators and score breakdowns.","parameters":[{"name":"rubric","required":false,"in":"query","description":"Public SHARE version. Omit for the current SHARE 2.0 scores.","schema":{"enum":["2.0","1.0"],"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"minimum":1,"maximum":10000,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"asc","enum":["asc","desc"],"type":"string"}},{"name":"search","required":false,"in":"query","description":"Full-text search on title and DOI (PostgreSQL plainto_tsquery)","schema":{"example":"climate change genomics","type":"string"}},{"name":"repository","required":false,"in":"query","description":"Filter by repository name","schema":{"example":"zenodo","type":"string"}}],"responses":{"200":{"description":"Paginated list of datasets","content":{"application/json":{"schema":{"example":{"data":[{"id":"clx...","doi":"10.5281/zenodo.1234567","title":"Sample Research Dataset","repository":"zenodo","shareScore":78.5,"stewardshipScore":85,"harmonizationScore":70,"accessScore":90,"engagementScore":60,"reuseScore":45,"authors":[{"id":"clx...","name":"Jane Doe","affiliation":"MIT"}]}],"pagination":{"total":115000000,"page":1,"limit":10,"totalPages":11500000,"hasNext":true,"hasPrev":false}}}}}},"400":{"description":"Unsupported SHARE version"},"409":{"description":"Selected rubric has no published score data"}},"tags":["Datasets"]}},"/records/{id}/impact":{"get":{"operationId":"RecordController_findImpact","summary":"Get stewardship and separately reported outcomes for a dataset","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"rubric","required":false,"in":"query","schema":{"enum":["2.0","1.0"],"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}}},"tags":["Datasets"]}},"/records/{id}":{"get":{"operationId":"RecordController_findOne","summary":"Get a single dataset by ID","description":"Returns a single dataset record by its internal ID, including all SHARE scores, metadata, and authors.","parameters":[{"name":"id","required":true,"in":"path","description":"Internal record ID (CUID)","schema":{"type":"string"}},{"name":"rubric","required":false,"in":"query","schema":{"enum":["2.0","1.0"],"type":"string"}}],"responses":{"200":{"description":"Dataset record with SHARE scores and authors"},"400":{"description":"Unsupported SHARE version"},"404":{"description":"Dataset not found"}},"tags":["Datasets"]}},"/authors":{"get":{"operationId":"AuthorController_findAll","summary":"List researchers with S-Index scores","description":"Returns a paginated list of researchers with their S-Index, S-Impact, and aggregate SHARE scores. The S-Index is analogous to the H-index: max(k) where a researcher has k datasets with SHARE score >= k. Supports filtering by minimum S-Index and minimum dataset count.","parameters":[{"name":"rubric","required":false,"in":"query","description":"Public SHARE version. Omit for the current SHARE 2.0 scores.","schema":{"enum":["2.0","1.0"],"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"minimum":1,"maximum":10000,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"asc","enum":["asc","desc"],"type":"string"}},{"name":"search","required":false,"in":"query","description":"Search by researcher name","schema":{"example":"John Smith","type":"string"}},{"name":"minSIndex","required":false,"in":"query","description":"Minimum S-Index filter","schema":{"minimum":0,"example":10,"type":"number"}},{"name":"minDatasets","required":false,"in":"query","description":"Minimum dataset count filter","schema":{"minimum":0,"example":5,"type":"number"}}],"responses":{"200":{"description":"Paginated list of researchers","content":{"application/json":{"schema":{"example":{"data":[{"id":"clx...","name":"Jane Doe","slug":"jane-doe","affiliation":"MIT","sIndex":42,"sImpact":3150.5,"datasetCount":87,"avgScore":65.3,"maxScore":95,"shareScore":72.1}],"pagination":{"total":1300000,"page":1,"limit":10,"totalPages":130000,"hasNext":true,"hasPrev":false}}}}}},"400":{"description":"Unsupported SHARE version"},"409":{"description":"Selected rubric has no published researcher metrics"}},"tags":["Researchers"]}},"/authors/{slug}":{"get":{"operationId":"AuthorController_findOne","summary":"Get researcher detail by slug","description":"Returns detailed information about a researcher including their S-Index, all score components, and their top 100 datasets sorted by SHARE score.","parameters":[{"name":"slug","required":true,"in":"path","description":"URL-friendly researcher identifier (e.g., \"jane-doe\")","schema":{"example":"jane-doe","type":"string"}},{"name":"rubric","required":false,"in":"query","schema":{"enum":["2.0","1.0"],"type":"string"}}],"responses":{"200":{"description":"Researcher detail with top datasets"},"400":{"description":"Unsupported SHARE version"},"404":{"description":"Researcher not found"}},"tags":["Researchers"]}},"/metrics/live":{"get":{"operationId":"MetricsController_getLiveMetrics","summary":"Get live platform metrics","description":"Returns real-time aggregate statistics including total records, total authors, mean SHARE score, score distribution (11 buckets: 0-9 through 100), and per-repository breakdowns. Uses statistical sampling for performance on 115M+ records.","parameters":[{"name":"rubric","required":false,"in":"query","schema":{"enum":["2.0","1.0"],"type":"string"}}],"responses":{"200":{"description":"Live platform metrics","content":{"application/json":{"schema":{"example":{"totalRecords":115000000,"totalAuthors":1300000,"repositoryCount":5,"meanShareScore":42.3,"pctAbove70":12.5,"meanStewardship":55,"meanHarmonization":38,"meanAccess":62,"meanEngagement":28,"meanReuse":15,"meanSIndex":3.2,"maxSIndex":142,"scoreDistribution":{"0-9":5000000,"10-19":8000000},"repositoryBreakdown":[{"repository":"zenodo","count":1300000,"meanScore":45.2}]}}}}},"400":{"description":"Unsupported SHARE version"},"409":{"description":"Selected rubric has no published aggregate metrics"}},"tags":["Metrics"]}},"/metrics/history":{"get":{"operationId":"MetricsController_getHistory","summary":"Get historical metrics snapshots","description":"Returns all historical metrics snapshots captured over time. Each snapshot includes total records, authors, mean scores, and distributions at the time of capture. Useful for tracking platform growth and score trends.","parameters":[{"name":"rubric","required":false,"in":"query","schema":{"enum":["2.0","1.0"],"type":"string"}}],"responses":{"200":{"description":"Array of historical metrics snapshots"},"400":{"description":"Unsupported SHARE version"},"409":{"description":"Selected rubric has no published historical metrics"}},"tags":["Metrics"]}},"/api-keys/register":{"post":{"operationId":"ApiKeyController_register","summary":"Register for a free API key","description":"Register with your name and email to receive an API key. Keys provide higher rate limits (1000 req/min vs 100 req/min) and usage tracking. Anonymous access without a key is also supported. Limited to 3 registrations per hour per IP.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterKeyDto"}}}},"responses":{"201":{"description":"API key created successfully","content":{"application/json":{"schema":{"example":{"key":"ss_live_a1b2c3d4e5f6...","name":"Jane Doe","email":"jane@university.edu","createdAt":"2026-02-10T00:00:00.000Z","message":"Store this key securely — it will not be shown again."}}}}},"429":{"description":"Rate limit exceeded — max 3 registrations per hour"}},"tags":["API Keys"]}},"/rubrics":{"get":{"operationId":"RubricController_list","summary":"List public SHARE versions","description":"Returns SHARE 1.0 and SHARE 2.0 with current score-data availability. Immutable contract identity remains in technical provenance.","parameters":[],"responses":{"200":{"description":"Supported rubric releases"}},"tags":["Rubrics"]}},"/rubrics/{version}":{"get":{"operationId":"RubricController_findOne","summary":"Get a SHARE version or technical contract release","parameters":[{"name":"version","required":true,"in":"path","description":"Public SHARE version; exact historical contract IDs remain accepted for compatibility","schema":{"example":"2.0","type":"string"}}],"responses":{"200":{"description":"Rubric release descriptor"},"400":{"description":"Unsupported rubric version"}},"tags":["Rubrics"]}},"/institutions":{"get":{"operationId":"AttributionController_institutions","summary":"List exact reported-affiliation SHARE 2 aggregates","description":"Each identity is the SHA-256 of exact raw reported affiliation text. Labels are sanitized for display; rows are not canonical organizations or ROR matches and have no institutional S-Index.","parameters":[{"name":"rubric","required":false,"in":"query","description":"Public SHARE version. Omit for the current SHARE 2.0 scores.","schema":{"default":"2.0","enum":["2.0","1.0"],"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"minimum":1,"maximum":10000,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"asc","enum":["asc","desc"],"type":"string"}},{"name":"search","required":false,"in":"query","description":"Search sanitized reported-affiliation labels","schema":{"maxLength":240,"type":"string"}},{"name":"countryCode","required":false,"in":"query","description":"Filter by ISO 3166-1 alpha-3 country code","schema":{"minLength":3,"maxLength":3,"pattern":"/^[A-Za-z]{3}$/","example":"USA","type":"string"}}],"responses":{"200":{"description":"Paginated reported-affiliation aggregates"},"400":{"description":"Unsupported rubric, sort, or country code"},"409":{"description":"Selected release has no complete attribution receipt"}},"tags":["Attribution"]}},"/geography":{"get":{"operationId":"AttributionController_geography","summary":"List non-exclusive country attribution for SHARE 2","description":"Records may count in more than one country. A record is deduplicated within each country, and failed score rows are excluded from numerical means.","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":250,"default":250,"type":"number"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"maximum":10000,"default":1,"type":"number"}},{"name":"sortBy","required":false,"in":"query","schema":{"type":"string"}},{"name":"sortOrder","required":false,"in":"query","schema":{"default":"asc","enum":["asc","desc"],"type":"string"}}],"responses":{"200":{"description":"Paginated ISO alpha-3 country aggregates"},"400":{"description":"Unsupported rubric or sort"},"409":{"description":"Selected release has no complete attribution receipt"}},"tags":["Attribution"]}},"/evaluations":{"post":{"operationId":"EvaluationController_evaluate","summary":"Resolve and evaluate a DOI or dataset identifier","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEvaluationDto"}}}},"responses":{"200":{"description":"Published record result"},"201":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"Valid but unsupported source"}},"tags":["Evaluator"]}},"/evaluation-jobs":{"post":{"operationId":"EvaluationJobController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEvaluationJobDto"}}}},"responses":{"202":{"description":""}}}},"/evaluation-jobs/{id}":{"get":{"operationId":"EvaluationJobController_find","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/auth/orcid/start":{"get":{"operationId":"AccountController_start","parameters":[],"responses":{"200":{"description":""}}}},"/auth/orcid/callback":{"get":{"operationId":"AccountController_callback","parameters":[],"responses":{"200":{"description":""}}}},"/auth/magic/request":{"post":{"operationId":"AccountController_requestMagicLink","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestMagicLinkDto"}}}},"responses":{"201":{"description":""}}}},"/auth/magic/consume":{"post":{"operationId":"AccountController_consumeMagicLink","parameters":[],"responses":{"201":{"description":""}}}},"/account/me":{"get":{"operationId":"AccountController_me","parameters":[],"responses":{"200":{"description":""}}}},"/account/profile-claims":{"post":{"operationId":"AccountController_claim","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProfileClaimDto"}}}},"responses":{"201":{"description":""}}}},"/account/visibility-requests":{"post":{"operationId":"AccountController_visibilityRequest","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityRequestDto"}}}},"responses":{"201":{"description":""}}}},"/account/saved-records":{"post":{"operationId":"AccountController_saveRecord","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveRecordDto"}}}},"responses":{"201":{"description":""}}}},"/account/saved-records/{recordId}":{"delete":{"operationId":"AccountController_removeSavedRecord","parameters":[{"name":"recordId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/account/saved-authors":{"post":{"operationId":"AccountController_saveAuthor","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveAuthorDto"}}}},"responses":{"201":{"description":""}}}},"/account/saved-authors/{authorId}":{"delete":{"operationId":"AccountController_removeSavedAuthor","parameters":[{"name":"authorId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/account/dataset-submissions":{"get":{"operationId":"AccountController_datasetSubmissions","parameters":[],"responses":{"200":{"description":""}}},"post":{"operationId":"AccountController_submitDataset","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetSubmissionDto"}}}},"responses":{"201":{"description":""}}}},"/account/measurements":{"post":{"operationId":"AccountController_measure","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetSubmissionDto"}}}},"responses":{"201":{"description":""}}}},"/auth/logout":{"post":{"operationId":"AccountController_logout","parameters":[],"responses":{"201":{"description":""}}}},"/widgets/datasets/{id}/badge.svg":{"get":{"operationId":"WidgetController_dataset","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/widgets/repositories/{repository}/badge.svg":{"get":{"operationId":"WidgetController_repository","parameters":[{"name":"repository","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/widgets/researchers/{slug}/badge.svg":{"get":{"operationId":"WidgetController_researcher","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}}},"info":{"title":"ShareScore API","description":"Open REST API serving versioned SHARE scores and S-Index metrics for scientific datasets. Requests without a rubric use the live SHARE 2.0 release. Requests with `rubric=1.0` uses historical SHARE 1.0 compatibility scores. Exact contract IDs remain accepted for compatibility but are not public product versions.\n\nThe **SHARE Score** (0–100) measures data sharing quality across five dimensions: **S**tewardship, **H**armonization, **A**ccess, **R**euse/Reusability, and **E**ngagement. In SHARE 2.0, R is deposit-time Reusability and is never mapped to the legacy post-deposit reuse field. The **S-Index** is a researcher-level metric analogous to the H-index but for data sharing.\n\nAll endpoints are read-only and require no authentication. Use the **Try it out** button on any endpoint below to query live data.\n\n**Rate Limits:** 100 requests/minute (no key required), 1,000/minute with a free API key.\n\nDeveloper docs and code examples: [sharescore.org/developers](https://sharescore.org/developers)","version":"1.5.0","contact":{"name":"ShareScore Team","url":"https://sharescore.org","email":"shuhan.he1@gmail.com"},"license":{"name":"Open Access","url":"https://sharescore.org/about"}},"tags":[],"servers":[{"url":"https://api.sharescore.org","description":"Production"},{"url":"http://localhost:3001","description":"Local Development"}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional API key for higher rate limits"}},"schemas":{"RegisterKeyDto":{"type":"object","properties":{"name":{"type":"string","description":"Your name or organization","example":"Jane Doe"},"email":{"type":"string","description":"Contact email address","example":"jane@university.edu"},"description":{"type":"string","description":"How you plan to use the API","example":"Research on data sharing practices"}},"required":["name","email"]},"CreateEvaluationDto":{"type":"object","properties":{"identifier":{"type":"string","minLength":1,"maxLength":2048},"rubricVersion":{"type":"string","enum":["1.0","2.0","1.0.0","2.0.0-beta.1","2.0.0-beta.2"]}},"required":["identifier","rubricVersion"]},"CreateEvaluationJobDto":{"type":"object","properties":{"identifier":{"type":"string","maxLength":2048},"rubricVersion":{"type":"string","enum":["1.0","2.0","1.0.0","2.0.0-beta.1","2.0.0-beta.2"]}},"required":["identifier","rubricVersion"]},"RequestMagicLinkDto":{"type":"object","properties":{"email":{"type":"string","maxLength":254},"returnTo":{"type":"string","maxLength":300}},"required":["email"]},"CreateProfileClaimDto":{"type":"object","properties":{"authorSlug":{"type":"string","maxLength":160,"pattern":"/^[a-zA-Z0-9._~-]+$/"}},"required":["authorSlug"]},"VisibilityRequestDto":{"type":"object","properties":{"authorSlug":{"type":"string","maxLength":160,"pattern":"/^[a-zA-Z0-9._~-]+$/"},"requestType":{"type":"string","enum":["opt_out","opt_in"]},"reason":{"type":"string","maxLength":500}},"required":["authorSlug","requestType"]},"SaveRecordDto":{"type":"object","properties":{"recordId":{"type":"string","minLength":1,"maxLength":160},"note":{"type":"string","maxLength":500}},"required":["recordId"]},"SaveAuthorDto":{"type":"object","properties":{"authorSlug":{"type":"string","maxLength":160,"pattern":"/^[a-zA-Z0-9._~-]+$/"},"note":{"type":"string","maxLength":500}},"required":["authorSlug"]},"DatasetSubmissionDto":{"type":"object","properties":{"identifier":{"type":"string","minLength":1,"maxLength":2048},"rubricVersion":{"type":"string","enum":["1.0","2.0","1.0.0","2.0.0-beta.1","2.0.0-beta.2"]}},"required":["identifier"]}}}}