Schemas

The objects the routes share, as api/openapi.yaml describes them.

LicenceRequired

403 from a route the licence doesn't include: the assistant's routes (assistant), linking an identity (sso), publishing, rolling back or releasing a library outside the first environment and every promote (environments), a job with a callbackUrl (scale), and changing the branding (branding).

Field	Type	Required	Description
error	licence-required	yes
feature	sso, environments, assistant, scale, branding, template-sources	yes
message	string	yes	What a licence would unlock.

LicenceLimit

409 when a limit refuses a change: creating or restoring a template past templates, changing a frozen template's draft or publishing or promoting it (templates), publishing or promoting a template that pins more sub-reports than subreportsPerTemplate, and creating a user, granting a role or enabling a user that would make a designer past designerSeats.

Field	Type	Required	Description
error	licence-limit	yes
limit	templates, subreportsPerTemplate, designerSeats	yes
allowed	integer	yes
used	integer	yes
message	string	yes

Licence

The licence's state. licensee, id, binding, history and warnings are there only for administrators.

Field	Type	Required	Description
phase	community, transition, active, expiring, grace, lapsed	yes
edition	string	yes	The licence's label, or Community. Shown, never checked.
everLicensed	boolean	yes	The install has had a licence, or is from before licences.
fixed	boolean	yes	The licence setting fixes it.
expires	string (date-time)
graceEnds	string (date-time)
transitionEnds	string (date-time)
daysLeft	integer		Days to the next phase.
features	map of boolean	yes	sso, environments, assistant, scale and branding, each on or off.
limits	array of object	yes
limits[].name	templates, subreportsPerTemplate, designerSeats	yes
limits[].limited	boolean	yes
limits[].allowed	integer	yes
limits[].used	integer
limits[].community	integer	yes
licensee	string
id	string
binding	object
binding.installation	string
binding.domains	array of string
binding.thisInstallation	string
binding.thisHost	string
history	object
history.transition	object
history.transition.start	string (date-time)
history.transition.end	string (date-time)
history.licences	array of object
history.licences[].id	string
history.licences[].expires	string (date-time)
history.licences[].installed	string (date-time)
warnings	array of object	yes
warnings[].code	string	yes
warnings[].message	string	yes

TrashItem

A deleted template, folder or library. A folder item lists in contains the subfolders and templates that went with it; they are restored and purged with it.

Field	Type	Required	Description
id	string	yes
kind	template, folder, library	yes
name	string	yes	The template's id, the folder's path, or the library's name.
title	string
folder	string		Where it was: a template's folder, or a folder's parent.
deletedAt	string (date-time)	yes
deletedBy	string	yes
purgeAt	string (date-time)		When the sweep purges it; absent under trash.retentionDays 0.
contains	array of object	yes
contains[].kind	template, folder	yes
contains[].name	string	yes
contains[].title	string
contains[].folder	string

Session

A sign-in session. id names it in the API; it is neither the token nor its hash, and signs no one in. expires is when it ends: its lifetime (auth.sessions.lifetime, 24h by default) or, with auth.sessions.idleTimeout, an idle timeout if that comes first.

Field	Type	Required	Description
id	string
created	string (date-time)
lastUsed	string (date-time)
expires	string (date-time)
method	string		password, password+totp, password+passkey, password+recovery, oidc:<provider> or saml:<provider>; empty when unknown.
userAgent	string		The browser's User-Agent at sign-in; empty when unknown.
address	string		The client address at sign-in (security.trustedProxies); empty when unknown.
current	boolean		This request is signed in with it.

RateLimits

A key's own rate per request class, in place of limits.rate. A class left out keeps the default, and so does a burst left out; perMinute 0 is no limit for this key and class. A key's requests never count in signin or public, which count per address.

Field	Type	Required	Description
read	Rate
write	Rate
render	Rate
assistant	Rate

Rate

Field	Type	Required	Description
perMinute	integer		At least 0.
burst	integer		At least 0.

Job

Field	Type	Required	Description
id	string
status	queued, running, done, error, cancelled
templateId	string
environment	string
format	string
idempotencyKey	string		The Idempotency-Key the job was submitted with.
error	string		Why the job ended in error.
reportIds	array of string		The rendered runs' reports.
progress	object
progress.done	integer
progress.total	integer
attempts	integer		Failed attempts so far.
runs	array of object
runs[].done	boolean
runs[].reportId	string
callback	object		The job's webhook, when it was submitted with a callbackUrl.
callback.url	string
callback.status	pending, delivered, failed
callback.attempts	integer		Failed deliveries so far.
callback.nextAttempt	string (date-time)		When a pending callback is tried again.
callback.lastError	string
callback.deliveredAt	string (date-time)
createdAt	string (date-time)
startedAt	string (date-time)
finishedAt	string (date-time)
done	string (date-time)		finishedAt.
expiresAt	string (date-time)		When the job gives up waiting.

SourceDefinition

source.json. kind is sql (query {sql, shape: rows|one|value, types} or {fields: {name: {sql, shape, types}}}, parameters written :name) or http (query {method: GET|POST, path with {name} segments, query values {name}, body with {"$param": name}, pointer}).

Field	Type	Required	Description
name	string	yes
version	string	yes
description	string
kind	sql, http	yes
connection	string	yes
params	array of object
params[].name	string	yes
params[].type	string, number, integer, boolean, date, datetime	yes
params[].description	string
params[].required	boolean
params[].multiple	boolean
params[].default	any
query	object

ViewState

RFML §17.6.1 view state. At most viewer.maxViewStateBytes (default 8 KB) as compact JSON, so it fits in the viewer's URL. Toggle keys are node@instance keys; a filter value is a value, a list of values or {min, max}. params only where viewer.viewStateParams allows.

Field	Type	Required	Description
params	object
toggles	map of expanded, collapsed
sorts	map of array of object
filters	map of map of any

ViewSession

Field	Type	Required	Description
id	string	yes
templateId	string	yes
environment	string	yes
commit	string	yes
draft	boolean	yes
params	object	yes
view	ViewState	yes
origins	object	yes	Where each dataset came from (kind live, sample, supplied or none; source name@version).
bytes	integer (int64)	yes	The session's data.
created	string (date-time)	yes
expiresAt	string (date-time)	yes	When the session ends if it isn't used.
viewerUrl	string	yes	Where the viewer shows it, e.g. /view/{id}.
refetched	array of string		PATCH only. The datasets fetched again.

Document

An RFML document (docs/spec/rfml.md); its JSON Schema is GET /v1/schema.

A object.

Op

An RFML edit operation (§21.1); its JSON Schema is GET /v1/schema?part=ops.

Field	Type	Required	Description
op	string	yes

Diagnostic

Field	Type	Required	Description
code	string	yes
severity	error, warning, info	yes
message	string	yes
node	string
path	string
range	array of integer
instance	string
fixes	array of object
fixes[].title	string
fixes[].ops	array of Op

DraftResult

Field	Type	Required	Description
revision	integer (int64)	yes	The draft's revision after the edit.
jsonPatch	array of object	yes	RFC 6902 over the canonical JSON, before → after.
inverse	array of Op	yes
diagnostics	array of Diagnostic	yes
dryRun	boolean
undone	integer (int64)
redone	integer (int64)

UndoRequest

Field	Type	Required	Description
environment	string
baseRevision	integer (int64)

Setting

Field	Type	Required	Description
path	string	yes
value	any	yes	As reportd config show shows it, secrets masked.
origin	string	yes	default, file, settings or "env REPORTD_…".
editable	boolean	yes
fixed	boolean		On the editable list, but the config file or the environment sets it.
secret	boolean		Takes only a secret: reference.
feature	string		The licence feature it needs.
title	string
doc	string		What it does, from the comment on its Go field.
kind	string, bool, int, duration, strings, list, map
default	any		Its value in a config that sets nothing, when it has one.
unit	seconds, ms, hours, days, MB, bytes, megapixels, a minute		What a number counts, from its name.
renderd	boolean		The renderd reportd starts (renderer.command) is given it, so it starts again on a change.
options	array of string		The values it takes, when it takes one of a few; "" is the default.

BrandingColours

Field	Type	Required	Description
primary	string	yes
accent	string	yes

BrandingSignIn

Field	Type	Required	Description
heading	string
text	string		Plain text; newlines are kept.
supportURL	string		An https: or mailto: link, or empty.

Branding

Field	Type	Required	Description
productName	string	yes
colours	BrandingColours	yes
palette	map of string		The studio's and viewer's colour tokens (ink, ink-2, accent, …) derived from the colours; absent while the colours are the defaults.
signIn	BrandingSignIn	yes
files	object	yes	Each file's URL under /branding/, or null; the favicon always has one.
files.logo	string
files.favicon	string
files.background	string
custom	boolean	yes	The stored branding shows.

BrandingEdit

Field	Type	Required	Description
productName	string
colours	BrandingColours
signIn	BrandingSignIn

BrandingChanged

Field	Type	Required	Description
branding	Branding	yes
updatedAt	string (date-time)
updatedBy	string

TemplateSourceEdit

Field	Type	Required	Description
name	string
kind	git, folder, gallery
enabled	boolean
url	string (uri)		git: the repository (https only); gallery: a published gallery's folder (https).
ref	string		git: a branch, tag or commit; the default branch when empty.
path	string		git: the folder that holds the templates; the root when empty.
token	string		git: a secret: reference to a read-only access token, sent as basic auth, never the token. Its value is the token, or user:token for a host that needs a user.
allowPrivate	boolean		git and gallery: let reads reach internal addresses (a self-hosted server).
folder	string		folder: an absolute path on the server.
maxBytes	integer		git: the clone's cap (100 MB when 0, at most 1 GB).

TemplateSource

Field	Type	Required	Description
id	string	yes
preset	boolean	yes	The example gallery.
active	boolean	yes	Designers see its templates.
off	turned-off, licence-required, examples-gallery-off		Why it isn't active; a lapsed licence keeps the source but turns it off.
state	object	yes
state.readAt	string (date-time)
state.commit	string		The commit a git source was read at.
state.templates	integer	yes
state.error	string		Why the last read failed.
updatedAt	string (date-time)
updatedBy	string

SourceTemplate

Field	Type	Required	Description
source	string	yes	The template source's id.
id	string	yes	Unique in its source.
title	string	yes
description	string	yes
path	string		Its folder in the source.
rfml	string	yes
status	available, too-new, unsupported	yes
reason	string		Why it is refused: "Needs Reportforge 0.10.0 or later (RFML 0.3)".
needs	string		The first release that writes a too-new version.

SourceListing

Field	Type	Required	Description
id	string	yes
name	string	yes
kind	git, folder, gallery	yes
state	ok, unavailable	yes
message	string		"Finance templates can't be reached right now.".
commit	string

FontSourceEdit

Field	Type	Required	Description
id	string
name	string
kind	github, url, fontsource, index	yes
enabled	boolean
owner	string		github.
repo	string		github.
ref	string		github: a branch, tag or commit (main by default).
layout	metadata, folders		github.
path	string		github: the folder that holds the families.
token	string		github: a secret: reference to a token, never the token.
hosts	array of string		url and index: origins such as https://fonts.example.com or https://*.foundry.com.
index	string (uri)		index: the index's URL, on one of the hosts.
allowPrivate	boolean		Let fetches reach internal addresses.
maxBytes	integer		One import's cap (20 MB when 0).

FontSource

Field	Type	Required	Description
preset	boolean	yes
fetchHosts	array of string	yes
updatedAt	string (date-time)
updatedBy	string

FontFamily

Field	Type	Required	Description
id	string	yes	The family's key in its source: a folder path, a Fontsource id, an index's name.
name	string	yes
category	string
licence	string		An SPDX identifier.

FontStyle

Field	Type	Required	Description
weight	integer	yes
style	normal, italic, oblique	yes
variable	boolean	yes	The style comes from a variable file.
file	string	yes
size	integer

FontDocument

Field	Type	Required	Description
name	string	yes
kind	licence, readme, notes	yes
size	integer

FontFamilyDetail

Field	Type	Required	Description
styles	array of FontStyle	yes
documents	array of FontDocument	yes
licenceURL	string
subsets	array of string		Fontsource's subsets.
subset	string		The subset an import takes unless asked for another.
version	string
warnings	array of string		Said before Add, such as a licence that can't be told.

FontImport

Field	Type	Required	Description
environment	string
source	string	yes	The font source's id.
family	string		The family's id in the source; for a url source, the family to take from a zip that holds several.
styles	array of string		Style keys: 400, 700italic. None means every style.
subset	string		Fontsource: the subset (its default, usually latin, when left out).
url	string (uri)		url source: the link to a font file or a zip.
documents	array of object		url source: a licence or readme by its own link.
documents[].url	string	yes
documents[].kind	licence, readme, notes	yes

LibraryFontFile

Field	Type	Required	Description
path	string	yes
weight	string	yes	400, or a variable file's range: 400 700.
style	normal, italic, oblique	yes

LibraryFontDocument

Field	Type	Required	Description
path	string	yes
kind	licence, readme, notes	yes

LibraryFontFamily

A family the library's manifest declares (fonts)

Field	Type	Required	Description
files	array of LibraryFontFile	yes
documents	array of LibraryFontDocument
source	string
sourceName	string
origin	string
version	object		The commit and each file's blob SHA (GitHub), the release (Fontsource, an index), or a link's ETag or Last-Modified and sha256; files by where they came from.
version.commit	string
version.release	string
version.etag	string
version.lastModified	string
version.sha256	string
version.files	map of string

FontDeclared

Field	Type	Required	Description
family	string	yes
declared	LibraryFontFamily	yes
warnings	array of string	yes
commit	string	yes

AuditEvent

Field	Type	Required	Description
time	string (date-time)	yes
principal	string	yes
actorKind	string	yes	user, key, agent, or system for reportd's own.
onBehalfOf	string		The user an agent acted for.
source	string		api, mcp, assistant, cli or sweep.
action	string	yes
environment	string
template	string
commit	string
format	string
node	string		The reportd node that wrote it.

AuditPage

Field	Type	Required	Description
events	array of AuditEvent	yes
next	string		The next page's cursor; absent on the last page.

UsageRecord

render: principal, onBehalfOf, template, environment, format, source (api, studio, viewer, job, mcp, assistant), outcome (ok, error, refused), pages, ms, bytes; time is when it began. job: principal, template, environment, runs, outcome, ms. webhook: job, outcome (delivered, failed), attempts. signIn: principal (when known, else client), method (password, oidc, saml), outcome (ok, failed). rateLimited and error: class, status (error), principal or client. tally: class, requests in the minute starting at time.

Field	Type	Required	Description
kind	render, job, webhook, signIn, rateLimited, error, tally	yes
time	string (date-time)	yes
node	string	yes
principal	string
onBehalfOf	string
client	string
template	string
environment	string
format	string
source	string
outcome	string
method	string
class	string
job	string
status	integer
pages	integer
runs	integer
attempts	integer
ms	integer (int64)
bytes	integer (int64)
requests	integer (int64)

UsageRow

Field	Type	Required	Description
key	string		The day, template, environment or format; empty in the summary.
renders	integer (int64)
ok	integer (int64)
errors	integer (int64)
refused	integer (int64)
pages	integer (int64)
bytes	integer (int64)
ms	integer (int64)
p50	integer (int64)
p95	integer (int64)
max	integer (int64)

UsageDay

Field	Type	Required	Description
day	string (date)
partial	boolean		Not rolled up yet; totalled from its records.
peakConcurrent	integer
peakByNode	map of integer
jobs	array of object
jobs[].outcome	string
jobs[].count	integer
jobs[].runs	integer
webhooks	array of object
webhooks[].outcome	string
webhooks[].count	integer
webhooks[].attempts	integer
requests	array of object
requests[].class	string
requests[].requests	integer
requests[].rateLimited	integer
requests[].errors	integer
signIns	array of object
signIns[].method	string
signIns[].outcome	string
signIns[].count	integer

UsageReport

Field	Type	Required	Description
from	string (date)	yes
to	string (date)	yes
by	day, template, environment, format	yes
rows	array of UsageRow	yes
summary	UsageDay	yes
days	array of UsageDay	yes