OSCR

The public API

OSCR has a free, read-only API over its catalogue. It needs no account and no key. Every route answers a plain GET (and HEAD) and returns JSON, with CORS open to any origin. The answers hold the catalogue's facts. They do not include PDFs, the full text of papers or email addresses. The overview is at the API page.

Quickstart

Every route starts with /api/v1. Fetch the index, which links to every endpoint:

# curl
curl https://openscicode.org/api/v1/
# Python (standard library only)
import json, urllib.request
with urllib.request.urlopen("https://openscicode.org/api/v1/") as r:
    index = json.load(r)
print([e["id"] for e in index["endpoints"]])
# R (base R, no package)
con <- url("https://openscicode.org/api/v1/")
index <- jsonlite::fromJSON(readLines(con, warn = FALSE))
close(con)
str(index$endpoints$id)

The examples below use curl; the Python and R calls are the same everywhere, only the URL changes. In Python, requests.get(url).json() works the same as the urllib above; in R, jsonlite::fromJSON(url) reads a URL directly.

Authentication

There is no authentication. Do not send a key, a token or a cookie: the API ignores them. Because it is keyless and CORS is open, you can call it from a browser page too. (A separate layer with tokens and write routes is in development: see Labs.)

The shape of an answer

Every answer is a JSON object with the API version, a canonical self link, and the payload:

{
  "oscr_api": "v1",
  "self": "https://openscicode.org/api/v1/stats",
  "generated_at": "2026-09-30T01:40:53Z",
  "figures": { "articles": 1234, "with_code": 567, ... },
  "source": "/data/stats.json"
}

Where a clean static file holds the same data, the answer names it (source or bulk): fetch that file directly to avoid the Worker entirely (it has no rate limit).

The endpoints

GET /api/v1/ and GET /api/v1/openapi.json

The index links to every endpoint. The OpenAPI 3.1 document describes them for tools (a static copy is at /data/openapi.json):

curl https://openscicode.org/api/v1/openapi.json

GET /api/v1/stats

The catalogue's figures (papers, papers with code, repositories, scripts, matches).

curl https://openscicode.org/api/v1/stats

GET /api/v1/paper/{doi}

One paper's record by its DOI: its code links and repositories, data links, status, tools, categories, and a matches summary. The answer links to the paper by its DOI and does not include its PDF or full text. See Giving a DOI for the slashes.

curl https://openscicode.org/api/v1/paper/10.5555%2Foscr.fixture.1
curl "https://openscicode.org/api/v1/paper?doi=10.5555/oscr.fixture.1"
# Python: a paper, by its DOI
import json, urllib.parse, urllib.request
doi = "10.5555/oscr.fixture.1"
url = "https://openscicode.org/api/v1/paper/" + urllib.parse.quote(doi, safe="")
with urllib.request.urlopen(url) as r:
    paper = json.load(r)["paper"]
print(paper["title"], [c["url"] for c in paper["code"]])

Full-text search, with the same query language and filters as the site's search. Parameters: q, page, size (1 to 50), and the site's filters. This is the only endpoint bound by a quota (see Rate and caching).

curl "https://openscicode.org/api/v1/search?q=eeg&size=20"
# R: the first page of a search
res <- jsonlite::fromJSON("https://openscicode.org/api/v1/search?q=eeg&size=20")
res$total
res$results$doi

GET /api/v1/{type} and GET /api/v1/{type}/{id}

The lists (/authors, /journals, /institutions, /tools, /datasets) are paginated (see Pagination) and point to the bulk file that holds them all. One entity is fetched by its key (singular type): an ORCID iD for an author, a ROR id for an institution, a slug otherwise.

curl "https://openscicode.org/api/v1/authors?size=50&page=1"
curl https://openscicode.org/api/v1/author/0000-0000-0000-0028
curl https://openscicode.org/api/v1/tool/matplotlib

GET /api/v1/repository/{host}/{owner}/{name}

A repository the registry knows: its licence, state, pinned commit, file and script counts, languages, and the papers that cite it. The answer does not include the code's text: read it in the Code to Paper reader on a paper's page, or in the scripts dataset.

curl https://openscicode.org/api/v1/repository/github.com/oscr-fixture/eeg-analysis

GET /api/v1/blocks/{id}

A block of code linked to a paper, by its permanent identifier (block identifiers): the paper's DOI, the repository, the commit read, the file, the lines, the paragraphs it was matched to, its Software Heritage identifier with its context, who linked it and its status. A paper's record (/paper/{doi}) lists its blocks in blocks, and the same facts are at /b/{id}.json.

curl https://openscicode.org/api/v1/blocks/oscr:b:ZHK95W68S9M1K-N

Giving a DOI

A DOI contains a slash (10.5555/abcd), so in the path it must be URL-encoded (the slash becomes %2F). To avoid encoding, pass it unencoded as the ?doi= query parameter instead. Both forms return the same record. A DOI is matched case-insensitively, with or without a https://doi.org/ prefix.

Pagination

A list takes page (from 1) and size (1 to 100, default 50). The answer carries total, page, size, pages and next (the URL of the next page, or null). For the whole list at once, fetch the bulk file the answer names: it is a single static download with no rate limit.

Rate and caching

The static files (/data/) and the Hugging Face dataset are unlimited: they are served by the CDN. The one exception is /api/v1/search, which reads the search database, so each call counts against the site's shared daily free budget. Call it sparingly and cache its answers. Every API answer carries a Cache-Control header (ten minutes), so a repeat of the same call is served from the cache. When the search's daily quota is spent, it answers 503 with the error quota.

Bulk downloads

To extract everything, read the static files; the API points to them so you can skip the Worker:

/data/articles.csv.gz, repositories.csv
One row per paper (gzipped: the plain file is over the hosting's 25 MiB limit), and per repository.
/data/alignments.jsonl.gz
One JSON object per aligned paper (paragraph numbers matched to code lines; the paper's text is not included), gzipped.
/data/entities/<type>.json, /data/papers/NN.json, /data/repos/NN.json
The full entity lists, and every paper's and repository's record (sharded).
# Python: download the whole paper table (gzipped), then every author
import csv, gzip, io, json, urllib.request
with urllib.request.urlopen("https://openscicode.org/data/articles.csv.gz") as r:
    rows = list(csv.DictReader(io.TextIOWrapper(gzip.GzipFile(fileobj=r), encoding="utf-8")))
print(len(rows), "papers")
with urllib.request.urlopen("https://openscicode.org/data/entities/authors.json") as r:
    authors = json.load(r)
print(len(authors), "authors")
# R: the same two files
papers  <- read.csv(gzcon(url("https://openscicode.org/data/articles.csv.gz")))
authors <- jsonlite::fromJSON("https://openscicode.org/data/entities/authors.json")
nrow(papers); length(authors$orcid)

The authors' scripts (their text) are a separate public dataset on Hugging Face, OpenScientificCodeRegistry/Database, read with pandas or DuckDB (see the data guide). The site does not serve the whole catalogue as a single file, because that file would be too large for the hosting.

Errors

On a failure the API returns the right status code and a JSON body of a fixed shape:

{ "error": "not_found", "message": "The registry has no record of this DOI.",
  "documentation_url": "https://openscicode.org/help/api/" }
StatuserrorWhen
400bad_doi, bad_key, bad_repository, bad_queryA parameter is malformed.
404not_foundNo such record or endpoint.
405method_not_allowedA method other than GET or HEAD.
503quota, unavailable, not_configuredThe search's database cannot answer (the quota is spent, or it is down).

Versioning and stability

The API is versioned in its path (/api/v1). Within a version, fields may be added but are not removed or renamed, so a reader that ignores unknown fields keeps working. A breaking change would come as a new version (/api/v2/), announced before the old one is retired. The record layout may gain fields as the catalogue grows.

Licence and citation

The catalogue's facts are open data; the authors' code stays under its own licence (that is why some files are shown by loading them from their source: the code policy). Use of the API and the data is covered by the terms of use. To cite OSCR and a record, see Citation.