API overview.
Everything the Radial UI shows comes through an API you can call yourself: a versioned REST surface under /api/v1.0, described by a spec-validated OpenAPI contract.
The contract is the product
The OpenAPI document is treated as a deliverable, not an afterthought: it validates clean, every operation has a stable operationId, pagination is documented once and used consistently, and errors return documented JSON shapes. If you build against the spec, the spec is telling you the truth.
The contract comes with a demo
The OpenAPI document and a matching Postman collection are not posted here; they come with a demo. Book one through the contact form and you get the current version with its change log as part of the walkthrough. Radial deployments also serve the same document at /api/v1.0/docs/public.json without a token, so what you build against is what your deployment ships.
Authentication and tokens
Access is token-based, the same pattern for a script, a notebook, or an integrated product:
- Create a personal access token in Radial (Settings, then Personal Access Tokens).
- Exchange it: POST /api/v1.0/auth/pat-exchange with body
{"pat": "<token>"}. That endpoint needs no prior authentication. - Send the returned access token on every request as Authorization: Bearer <access_token>.
Access tokens are short-lived (their lifetime is the expires_in seconds returned by the exchange), and there is no refresh token. When a request returns 401 with code: token_expired, exchange the PAT again. Use one token per integration.
Tokens are read-only by default. To modify data, send "scope": "radial:read radial:write" with the PAT at exchange time; a read-only token answers 403 with code insufficient_scope to any request that would change data, and the scope field of the exchange response shows what was granted.
What the surface covers
Resources map to the concepts in these docs: cases and case search, datasets, protocols and their scorecards (evaluate and metrics), structure dictionaries and their dose-endpoint definitions in Mayo syntax, DVH curves, curated case and dataset metadata, and ROI-map data. Treatment courses come with their delivered-fraction counts, per-fraction trends, adaptation deltas, the patient-wide list behind the re-irradiation ledger, and declared radiotherapy procedures. DICOM operations (staged studies, imports, query and retrieve, and job status) and module listings for segmentation and radiomics complete the surface. Course and procedure reads return the documented shape only, and the five course-management writes (assign, split, merge, record dose intent, and edit) are in the contract too, callable with a write-scoped token; the per-organ EQD2 computation and the procedure writes stay private. A few representative operations:
Versioning and deprecation
info.version follows semantic versioning: a MAJOR bump is a removal or an incompatible shape change (delivered under a new path prefix such as /api/v2.0), a MINOR bump is additive (new operations, or new optional fields and parameters), and a PATCH bump is documentation or examples only.
A deprecated operation keeps working for at least 12 months after it is marked. While deprecated it is flagged deprecated: true and returns Deprecation, Sunset, and Link response headers that name the successor. Removal happens only in a MAJOR version.
The policy is in force today, but no deprecation clock has started. The clock starts with the first external integration, so until then the surface can still move.