The public API

With this API, a script, a notebook, a lab's CI or another service can read and write OSCR's own layer: repositories and their papers, research issues, stars and follows, notifications, outgoing webhooks and commit statuses. This is version 2026-09-29. The machine-readable description is openapi.json (OpenAPI 3.1).

GitHub's own objects (commits, files, issues, pull requests, releases) are served by GitHub's own API, with GitHub's tokens. OSCR's API serves what OSCR adds to them. The API never runs code.

Authentication and scopes

Every route but the index takes a personal token, made on your settings page: Authorization: Bearer oscr_pat_…. A token has scopes and expires after 1 to 366days (30 by default; every token expires). It can be revoked at once, and it is listed with its last use. An account holds 20 tokens at most. A token is shown once, and OSCR keeps only its SHA-256. Tokens are made and listed on the settings page only; a token cannot make or list tokens. The API never reads cookies, so a browser's session cannot act through it. CORS answers every origin, without credentials.

curl -H "Authorization: Bearer $TOKEN" https://openscicode.org/api/forge/v1/user

Every answer says the token's scopes (X-Token-Scopes), the scope the route needs (X-Accepted-Scopes) and the token's expiry (X-Token-Expires). A write through the API is the same write as on the site, made as you, with the same checks, daily caps and rows. Until OSCR's content rules open writing to everyone, only its owner can make a token.

Rate limits

A token may make 60 requests a minute and 1,000 a day. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used and X-RateLimit-Reset (Unix seconds, the next 00:00 UTC). Past a limit, the answer is 429 with Retry-After. GET /api/forge/v1/rate_limit shows the token's current use and is never counted. Writes also count toward your account's daily caps, as on the site. OSCR runs on a free plan. When its requests for the day are spent, every route answers 429 until 00:00 UTC, and the pages stay up.

Pagination and conditional requests

A list with more pages answers with Link: <…>; rel="next" and a next field, which hold the address of the next page with its cursor (?after=). Every GET answer carries an ETag. Send it back in If-None-Match, and an unchanged answer is 304 Not Modified, which does not count against the rate limit.

Errors

An error is a JSON object with a message in words, the request's id (also in X-Request-Id) and this page's address:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token may not do this: it needs the scope social:read. Make a token with it in your settings.",
    "request_id": "u2Hn0cZ3VwQy8pKe",
    "documentation_url": "https://openscicode.org/developers/#errors"
  }
}

The headers a browser's script may read (CORS): ETag, Link, Retry-After, X-Request-Id, X-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Reset, X-RateLimit-Resource, X-Token-Scopes, X-Accepted-Scopes, X-Token-Expires.

Versions and breaking changes

The API is versioned by date. Send X-Api-Version: 2026-09-29 to pin a version; without it, you get the current one. A breaking change comes with a new date. The previous version keeps answering as it did until its end date, which is announced here. Versions: 2026-09-29.

Breaking changes

There are none yet, because 2026-09-29 is the first version.

The routes

Under https://openscicode.org/api/forge/v1. A POST takes JSON (Content-Type: application/json).

• GET /api/forge/v1
• GET /api/forge/v1/user
• GET /api/forge/v1/rate_limit
• GET /api/forge/v1/cli
• POST /api/forge/v1/device/code
• POST /api/forge/v1/device/token
• POST /api/forge/v1/token/revoke
• GET /api/forge/v1/search
• GET /api/forge/v1/repos
• GET /api/forge/v1/repos/mine
• GET /api/forge/v1/research
• POST /api/forge/v1/research/open
• POST /api/forge/v1/research/comment
• POST /api/forge/v1/research/edit
• GET /api/forge/v1/social
• GET /api/forge/v1/social/mine
• GET /api/forge/v1/social/person
• POST /api/forge/v1/social/star
• POST /api/forge/v1/social/follow
• POST /api/forge/v1/social/list
• POST /api/forge/v1/social/profile
• GET /api/forge/v1/social/feed
• GET /api/forge/v1/social/activity
• GET /api/forge/v1/notifications
• POST /api/forge/v1/notifications/mark
• GET /api/forge/v1/hooks
• GET /api/forge/v1/hooks/deliveries
• POST /api/forge/v1/hooks/write
• GET /api/forge/v1/statuses
• POST /api/forge/v1/statuses/post
• POST /api/forge/v1/security/sarif
• POST /api/forge/v1/statuses/actions

For example, star a paper:

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"subject": "paper:doi:10.1234/eeg.2026", "label": "EEG filters", "on": true}' \
  https://openscicode.org/api/forge/v1/social/star

Outgoing webhooks

A webhook, made on your settings page or with POST /api/forge/v1/hooks/write, posts what happens to a paper or a repository to your service. An account holds 10.

• A paper's events: research_opened, research_comment, research_closed, research_reopened, code_linked, release_tied.
• A repository's events: issue_opened, issue_closed, issue_reopened, issue_comment, pull_opened, pull_closed, pull_merged, pull_reopened, pull_review, pull_comment, release_published.

When a webhook is made, OSCR sends a ping, and the webhook becomes active once the ping gets a 2xx answer. Each delivery waits 5 seconds for an answer. It is tried again after 1 s and 4 s when there is no answer, or after a 5xx, 408 or 429 answer. It is not tried again after another 4xx answer, and redirections are not followed. After 10 failures in a row the webhook pauses, and a ping makes it active again. The last 7 days of deliveries are listed, and each event's delivery can be sent again. The address must use https, and it cannot be a private network, this machine, a local name or OSCR itself.

Each delivery has the headers X-Hook-Event, X-Hook-Delivery (its id), X-Hook-ID, and the signature X-Hub-Signature-256: sha256=<hex>. The signature is the HMAC-SHA-256 of the raw body with the webhook's secret, computed the way GitHub signs. An example body:

{
  "event": "research_opened",
  "delivery": "5f0c6f3e-8a1b-4c7d-9e2f-0a1b2c3d4e5f",
  "hook": { "id": "Qk3xY7pLm2Nw9Zt4", "subject": "paper:doi:10.1234/eeg.2026" },
  "sent_at": "2026-09-29T12:00:03.000Z",
  "subject": "paper:doi:10.1234/eeg.2026",
  "at": "2026-09-29T12:00:00.000Z",
  "thread": "research:7",
  "title": "The filter's order is 4, the paper says 2",
  "url": "https://openscicode.org/research/7",
  "repository": { "path": "owner/name", "url": "https://openscicode.org/r/owner/name/" },
  "paper": { "doi": "10.1234/eeg.2026", "url": "https://doi.org/10.1234/eeg.2026" },
  "actor": { "github_id": "4242001", "login": "ada-fixture" }
}

The body holds only what OSCR's pages show (a title, a page's address, the time, a GitHub login). It never holds a text or an email address. Check the signature before anything else, in constant time:

import hashlib, hmac

def signed(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

# In your receiver: signed(SECRET, request.body, request.headers["X-Hub-Signature-256"])

import { createHmac, timingSafeEqual } from "node:crypto";

export function signed(secret, body, header) {
  const expected = Buffer.from("sha256=" + createHmac("sha256", secret).update(body).digest("hex"));
  const given = Buffer.from(header ?? "");
  return expected.length === given.length && timingSafeEqual(expected, given);
}

The secret is shown once, when the webhook is made or given a new secret. OSCR does not store it, because it is derived from a key of the server.

Commit statuses

A lab's CI, another forge or a reproduction service can report the result of a commit of a repository OSCR knows: error, failure, pending or success, under a context of its own. The latest status of each context is kept, with at most 20 contexts per commit. The repository's Checks page shows them beside its tests. With a token that has the statuses:write scope:

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"repo": "owner/name", "sha": "<the commit's 40 characters>", "state": "success",
       "context": "lab-ci/tests", "description": "212 tests passed",
       "target_url": "https://ci.lab.example/runs/1"}' \
  https://openscicode.org/api/forge/v1/statuses/post

From GitHub Actions, no secret is needed. The workflow asks GitHub for its OIDC token with OSCR's address as the audience, and OSCR checks it (GitHub's signature, the issuer, the audience, the times, a public repository it knows). The status then belongs to the repository and is named after the workflow:

name: Tests
on: [push, pull_request]
permissions:
  contents: read
  id-token: write        # GitHub's OIDC token: no secret stored in the repository
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python -m pytest
      - name: Tell the registry
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const token = await core.getIDToken("https://openscicode.org");
            await fetch("https://openscicode.org/api/forge/v1/statuses/actions", {
              method: "POST",
              headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
              body: JSON.stringify({ sha: context.sha, state: "${{ job.status == 'success' && 'success' || 'failure' }}",
                target_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}` }),
            });

The registry's checks

On every push to a pull request of a repository where its GitHub App is installed, OSCR posts one check run. The check reads the files as text and never runs the code. The same checks are shown for any commit on the repository's Checks page, including the commits the papers cite.

• Licence
• Environment
• The paper's DOI
• CITATION.cff
• Tracing maps
• File sizes
• README

A check fails only when the change itself breaks something a paper relies on, for example when it deletes or renames a file a tracing map points to, deletes the licence file, or makes CITATION.cff unreadable. A missing item is reported for you to look at and does not fail the check. Each finding says how to resolve it. A commit whose message ends with the trailer skip-checks: true is not checked.