--- title: rad: URLs description: Read public Radicle repositories from any page in Freedom Browser with fetch('rad:/…'): routes, parameters, pagination and errors. kick: Radicle dek: Any page can fetch public repository data as JSON from the user's own Radicle node. No prompt, no server, no API key. source: https://github.com/solardev-xyz/freedom-browser/blob/main/src/main/radicle-api-protocol.js --- Freedom resolves the `rad:` scheme in-process. A page, including one served from `bzz://`, can read a public Radicle repository with a plain `fetch()`. This is the read side of Radicle in Freedom; writes such as seeding and issues go through [`window.radicle`](radicle.html.md). ```javascript const rid = 'z3QXuMvMmSeEX3ZgoUidZC1v5MkKE'; // freedom-browser's Radicle mirror const repo = await (await fetch(`rad:${rid}`)).json(); const head = repo.payloads['xyz.radicle.project'].meta.head; const readme = await (await fetch(`rad:${rid}/readme/${head}`)).json(); const openIssues = await (await fetch(`rad:${rid}/issues?status=open`)).json(); ``` ## URL forms Both forms work and are equivalent: ```text rad:/ rad:/// ``` `` is the bare repository id, `z` followed by 20 to 60 base58 characters (no `rad:` prefix inside the URL). The scheme is registered as non-standard, so the browser does not lowercase it and the case-sensitive id reaches Freedom intact. ## Rules - **Read only**: `GET` and `HEAD`. Any other method is `405`. `HEAD` returns the same status and headers without a body. - **Public repositories only**: a repository whose visibility is not public is `403` (`repository is not public`). - **The node must have the repository.** `rad:` reads from the user's local storage. To read a repository the node does not have yet, ask the user to seed it with [`radicle_seed`](radicle.html.md#radicle_seed) and wait for `state: 'fetched'`. - **Full commit SHAs**: routes that take a revision need the full 40-character lowercase hex SHA; branch names and short SHAs are rejected with `400`. Get the default branch head from the repository metadata. - **CORS**: responses carry `Access-Control-Allow-Origin: *`, so cross-origin pages can read them. - **No consent**: public repository data is world-readable on the network, so no prompt is shown and no grant is needed. - When Radicle is disabled for the profile, every request is `403`. ## Routes The routes mirror the per-repository part of radicle-httpd's API (`/api/v1/repos//…`). Node-level endpoints (repository listing, node info, sessions) are deliberately not reachable. | Route | Returns | | ----- | ------- | | `rad:` | Repository metadata (shape below) | | `rad:/tree/` | The root tree at a commit | | `rad:/tree//` | A directory at a commit | | `rad:/blob//` | A file at a commit | | `rad:/readme/` | The README at a commit (`404 no readme` if there is none) | | `rad:/commits/` | One commit | | `rad:/commits?parent=&page=&perPage=` | Commit history from `parent` | | `rad:/stats/tree/` | Repository statistics at a commit | | `rad:/remotes` | The repository's remotes | | `rad:/issues?status=&page=&perPage=` | Issues | | `rad:/issues/` | One issue | | `rad:/patches?status=&page=&perPage=` | Patches | | `rad:/patches/` | One patch | Path segments may be URL-encoded. Empty, `.` and `..` segments, encoded slashes and control characters are rejected (`400`), so a request cannot leave the repository's scope. ### Repository metadata ```javascript { rid: 'rad:z…', payloads: { 'xyz.radicle.project': { data: { name, description, defaultBranch }, meta: { head, issues: { open }, patches: { open } } } }, delegates: [ … ], threshold: number, visibility: { type: 'public' }, seeding: number // number of seeders known to the node } ``` `meta.head` is the default branch's commit SHA; use it as `` for the tree, blob, readme and commit routes. ### Pagination and filters | Parameter | Routes | Rule | | --------- | ------ | ---- | | `page` | `commits`, `issues`, `patches` | 0-based, default `0` | | `perPage` | `commits`, `issues`, `patches` | 1 to 100, default `30` | | `parent` | `commits` | Required for the history route; a full SHA | | `status` | `issues`, `patches` | Keeps items whose `state.status` equals the value, for example `open` | Out-of-range values are clamped rather than rejected. ## Errors | Status | Body | When | | ------ | ---- | ---- | | `400` | `{ code, message: 'invalid rad reference' }` | Malformed id or unsafe path | | `400` | `{ error }` | A route is missing its revision or path, or the SHA is not 40 hex characters | | `403` | `{ code, message }` | Radicle is disabled for this profile | | `403` | `{ error: 'repository is not public' }` | The repository is private | | `404` | `{ error }` | Unknown route (`unsupported endpoint: …`), or the repository, object or README was not found | | `405` | `{ code, message: 'method not allowed' }` | Not `GET` or `HEAD` | | `500` | `{ error }` | Any other node error | Errors raised before the request reaches the repository (the first `400`, the profile `403` and `405`) use `{ code, message }`; errors from the repository routes use `{ error }`. Check `response.ok` before parsing.