Skip to content

Schemas ​

The objects the routes share.

SecretField ​

A secret: reference (secret:env:CONN_BILLING, secret:file:conn-billing), never a value. The administrator's data.connections.secrets patterns say which a studio connection may use, and a reference reportd's own settings use (or a REPORTD_ variable, or a template or font source's token) is always refused, with the same message. On a write it may be {"set": "<value>"}: a draft's test uses it once; a save puts it in the secret store plugin (or replaces the field's stored secret, keeping its reference), and answers 422 no-store while none runs. A stored secret's reference (secret:store:<id>) is allowed only on the field it was set for. Replies hold only the reference.

A one of string, object.

ConnectionBinding ​

One environment's binding. postgres, mysql and mssql take fields (host and the rest; reportd builds the DSN, and the host is the binding's allowed host) or dsn, a whole DSN in a secret, which needs allowHosts. sqlite takes file, a name in the policy's SQLite folder, opened read-only. http takes baseUrl (a literal), auth and literal headers, which are not for secrets. A field another driver uses is refused. options are each driver's allowlist only (GET /v1/connections/policy); a DSN read from a secret is held to the same lists when it is opened.

FieldTypeRequiredDescription
hoststring
portintegerpostgres 5432, mysql 3306, mssql 1433 when left out (mssql: unless instance).
instancestringmssql, found through the SQL Server Browser.
databasestring
userstring
passwordSecretField
sslModeverify-full, verify-ca, require, disablepostgres; verify-full when left out.
tlstrue, skip-verify, preferredmysql; true when left out.
encrypttrue, strict, disablemssql; true when left out.
trustServerCertificatebooleanmssql.
optionsmap of string
filestring
dsnSecretField
allowHostsarray of string
baseUrlstring (uri)
authobject
auth.kindnone, bearer, header, basicyes
auth.headerstringheader's name.
auth.tokenSecretField
auth.userstringbasic's user.
auth.passwordSecretField
headersmap of string
storedmap of objectThe secret fields (password, dsn, auth.token, auth.password) whose reference is a secret typed into the form and kept by the store plugin, with who set it and when; never its value. reportd keeps it: what a write sends is ignored.

StoredConnection ​

A connection added in the studio, as it is kept. Its name never changes.

FieldTypeRequiredDescription
namestringThe path's name; policy and test are the routes'.
driverpostgres, mysql, mssql, sqlite, httpyes
descriptionstring
disabledboolean
environmentsmap of ConnectionBinding
timeoutSecintegerAt least 0.
maxRowsintegerAt least 0.
maxBytesinteger (int64)At least 0.
revisioninteger (int64)The revision this write changes: 0 to add.
updatedAtstring (date-time)
updatedBystring

Connection ​

A connection as GET /v1/connections/{name} answers it.

FieldTypeRequiredDescription
namestring
driverstring
kindsql, http
descriptionstring
originconfig, studio
fixedbooleanconfig.yaml's: the studio can't change it.
disabledboolean
timeoutSecinteger
maxRowsinteger
maxBytesinteger (int64)
revisioninteger (int64)
updatedAtstring (date-time)
updatedBystring
boundarray of string
environmentsmap of ConnectionBindingThe bindings of the environments the caller manages.
dependentsmap of array of stringThe sources using it, by environment.
shadowedConnection

ConnectionInfo ​

FieldTypeRequiredDescription
namestring
driverstring
kindsql, http
descriptionstring
originconfig, studio
fixedboolean
disabledboolean
shadowedboolean
revisioninteger (int64)
maxRowsinteger
maxBytesinteger (int64)
timeoutSecinteger
environmentsarray of object
environments[].environmentstring
environments[].statusunbound, shadowed, unchecked, ok, error
environments[].messagestring
environments[].latencyMsinteger
environments[].usedByintegerThe sources there that use it, with git source control.
environments[].bindingConnectionBinding

ConnectionAction ​

FieldTypeRequiredDescription
revisioninteger (int64)The revision the caller saw (0: whatever is there).
confirmarray of string

ConnectionTestResult ​

ok with the latency, or failed with a category from the error's type and a fixed message and hint: never a driver's text, a DSN or a server's banner. The categories tell an open port from a closed one only on hosts the policy already allows.

FieldTypeRequiredDescription
statusok, failedyes
latencyMsinteger
categorydns, blocked, timeout, refused, tls, sign-in, database, secret-missing, secret-provider, secret-store, unbound, failed
messagestring
hintstring

ConnectionPolicy ​

FieldTypeRequiredDescription
saveablebooleanfalse until data.connections.allowHosts lists a host.
errorstringWhy the policy in Settings can't be used.
allowHostsarray of string
allowPrivateboolean
allowLoopbackboolean
sqliteboolean
sqliteDirstring
sqliteFilesarray of stringThe files in the SQLite folder a binding may name, relative to it with /, three folders deep and at most 500, for the form's picker.
secretsarray of string
providersarray of object
providers[].namestring
providers[].builtInboolean
providers[].writableboolean
environmentsarray of string
optionsmap of array of string

Permission ​

A permission a role gives (auth.AllPermissions). Agent keys never have trash.purge, settings.manage, fonts.sources, templates.sources or connection.manage, whatever their roles.

A studio.access, template.read, template.write, template.publish, template.promote, template.rollback, report.render, report.read, user.manage, audit.read, template.unlock, source.read, source.manage, data.live, report.view, library.write, library.release, trash.purge, settings.manage, fonts.sources, templates.sources, connection.manage.

SecretProvider ​

FieldTypeRequiredDescription
namestringyesThe reference prefix: secret:<name>:….
builtInbooleanyes
writablebooleanyesA running plugin that keeps typed secrets.
stateok, degraded, failing, starting, restarting, waiting, refused, stoppedyes
runningbooleanyesok, degraded or failing: it answers.
sincestring (date-time)
messagestring
featurestringThe licence feature a plugin declares.
versionstringThe plugin's own version.
expiresAtstring (date-time)When the plugin says its own sign-in expires.
staleintegeryes

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).

FieldTypeRequiredDescription
errorlicence-requiredyes
featuresso, environments, assistant, scale, branding, template-sources, secret-vaultsyes
messagestringyesWhat 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.

FieldTypeRequiredDescription
errorlicence-limityes
limittemplates, subreportsPerTemplate, designerSeatsyes
allowedintegeryes
usedintegeryes
messagestringyes

Licence ​

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

FieldTypeRequiredDescription
phasecommunity, transition, active, expiring, grace, lapsedyes
editionstringyesThe licence's label, or Community. Shown, never checked.
everLicensedbooleanyesThe install has had a licence, or is from before licences.
fixedbooleanyesThe licence setting fixes it.
expiresstring (date-time)
graceEndsstring (date-time)
transitionEndsstring (date-time)
daysLeftintegerDays to the next phase.
featuresmap of booleanyessso, environments, assistant, scale and branding, each on or off.
limitsarray of objectyes
limits[].nametemplates, subreportsPerTemplate, designerSeatsyes
limits[].limitedbooleanyes
limits[].allowedintegeryes
limits[].usedinteger
limits[].communityintegeryes
licenseestring
idstring
bindingobject
binding.installationstring
binding.domainsarray of string
binding.thisInstallationstring
binding.thisHoststring
historyobject
history.transitionobject
history.transition.startstring (date-time)
history.transition.endstring (date-time)
history.licencesarray of object
history.licences[].idstring
history.licences[].expiresstring (date-time)
history.licences[].installedstring (date-time)
warningsarray of objectyes
warnings[].codestringyes
warnings[].messagestringyes

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.

FieldTypeRequiredDescription
idstringyes
kindtemplate, folder, libraryyes
namestringyesThe template's id, the folder's path, or the library's name.
titlestring
folderstringWhere it was: a template's folder, or a folder's parent.
deletedAtstring (date-time)yes
deletedBystringyes
purgeAtstring (date-time)When the sweep purges it; absent under trash.retentionDays 0.
containsarray of objectyes
contains[].kindtemplate, folderyes
contains[].namestringyes
contains[].titlestring
contains[].folderstring

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.

FieldTypeRequiredDescription
idstring
createdstring (date-time)
lastUsedstring (date-time)
expiresstring (date-time)
methodstringpassword, password+totp, password+passkey, password+recovery, oidc:<provider> or saml:<provider>; empty when unknown.
userAgentstringThe browser's User-Agent at sign-in; empty when unknown.
addressstringThe client address at sign-in (security.trustedProxies); empty when unknown.
currentbooleanThis 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.

FieldTypeRequiredDescription
readRate
writeRate
renderRate
assistantRate
probeRate

Rate ​

FieldTypeRequiredDescription
perMinuteintegerAt least 0.
burstintegerAt least 0.

Job ​

FieldTypeRequiredDescription
idstring
statusqueued, running, done, error, cancelled
templateIdstring
environmentstring
formatstring
idempotencyKeystringThe Idempotency-Key the job was submitted with.
errorstringWhy the job ended in error, or why its last attempt failed.
reportIdsarray of stringThe rendered runs' reports, in run order.
progressobject
progress.doneinteger
progress.totalinteger
attemptsintegerFailed attempts so far.
runsarray of object
runs[].doneboolean
runs[].reportIdstring
callbackobjectThe job's webhook, when it was submitted with a callbackUrl.
callback.urlstring
callback.statuspending, delivered, failed
callback.attemptsintegerFailed deliveries so far.
callback.nextAttemptstring (date-time)When a pending callback is tried again.
callback.lastErrorstring
callback.deliveredAtstring (date-time)
createdAtstring (date-time)
startedAtstring (date-time)
finishedAtstring (date-time)
donestring (date-time)finishedAt, under the name the first version used.
expiresAtstring (date-time)When the job gives up waiting, or when its finished record is removed.

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}).

FieldTypeRequiredDescription
namestringyes
versionstringyes
descriptionstring
kindsql, httpyes
connectionstringyes
paramsarray of object
params[].namestringyes
params[].typestring, number, integer, boolean, date, datetimeyes
params[].descriptionstring
params[].requiredboolean
params[].multipleboolean
params[].defaultany
queryobject

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.

FieldTypeRequiredDescription
paramsobject
togglesmap of expanded, collapsed
sortsmap of array of object
filtersmap of map of any

ViewSession ​

FieldTypeRequiredDescription
idstringyes
templateIdstringyes
environmentstringyes
commitstringyes
draftbooleanyes
paramsobjectyes
viewViewStateyes
originsobjectyesWhere each dataset came from (kind live, sample, supplied or none; source name@version).
bytesinteger (int64)yesThe session's data.
createdstring (date-time)yes
expiresAtstring (date-time)yesWhen the session ends if it isn't used.
viewerUrlstringyesWhere the viewer shows it, e.g. /view/{id}.
refetchedarray of stringPATCH 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.

FieldTypeRequiredDescription
opstringyes

Diagnostic ​

FieldTypeRequiredDescription
codestringyes
severityerror, warning, infoyes
messagestringyes
nodestring
pathstring
rangearray of integer
instancestring
fixesarray of object
fixes[].titlestring
fixes[].opsarray of Op

DraftResult ​

FieldTypeRequiredDescription
revisioninteger (int64)yesThe draft's revision after the edit.
jsonPatcharray of objectyesRFC 6902 over the canonical JSON, before → after.
inversearray of Opyes
diagnosticsarray of Diagnosticyes
dryRunboolean
undoneinteger (int64)
redoneinteger (int64)

UndoRequest ​

FieldTypeRequiredDescription
environmentstring
baseRevisioninteger (int64)

Setting ​

FieldTypeRequiredDescription
pathstringyes
valueanyyesAs reportd config show shows it, secrets masked.
originstringyesdefault, file, settings or "env REPORTD_…".
editablebooleanyes
fixedbooleanOn the editable list, but the config file or the environment sets it.
secretbooleanTakes only a secret: reference.
featurestringThe licence feature it needs.
titlestring
docstringWhat it does.
kindstring, bool, int, duration, strings, list, map
defaultanyIts value in a config that sets nothing, when it has one.
unitseconds, ms, hours, days, MB, bytes, megapixels, a minuteWhat a number counts, from its name.
renderdbooleanThe renderd reportd starts (renderer.command) is given it, so it starts again on a change.
optionsarray of stringThe values it takes, when it takes one of a few; "" is the default.

BrandingColours ​

FieldTypeRequiredDescription
primarystringyes
accentstringyes

BrandingSignIn ​

FieldTypeRequiredDescription
headingstring
textstringPlain text; newlines are kept.
supportURLstringAn https: or mailto: link, or empty.

Branding ​

FieldTypeRequiredDescription
productNamestringyes
coloursBrandingColoursyes
palettemap of stringThe studio's and viewer's colour tokens (ink, ink-2, accent, …) derived from the colours; absent while the colours are the defaults.
signInBrandingSignInyes
filesobjectyesEach file's URL under /branding/, or null; the favicon always has one.
files.logostring
files.faviconstring
files.backgroundstring
custombooleanyesThe stored branding shows, not the defaults.

BrandingEdit ​

FieldTypeRequiredDescription
productNamestring
coloursBrandingColours
signInBrandingSignIn

BrandingChanged ​

FieldTypeRequiredDescription
brandingBrandingyes
updatedAtstring (date-time)
updatedBystring

TemplateSourceEdit ​

FieldTypeRequiredDescription
namestring
kindgit, folder, gallery
enabledboolean
urlstring (uri)git: the repository (https only); gallery: a published gallery's folder (https).
refstringgit: a branch, tag or commit; the default branch when empty.
pathstringgit: the folder that holds the templates; the root when empty.
tokenstringgit: 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.
allowPrivatebooleangit and gallery: let reads reach loopback and private addresses (a self-hosted server). Link-local and cloud metadata addresses stay refused.
folderstringfolder: an absolute path on the server.
maxBytesintegergit: the clone's cap (100 MB when 0, at most 1 GB).

TemplateSource ​

FieldTypeRequiredDescription
idstringyes
presetbooleanyesThe example gallery, whose address is examples.gallery.
activebooleanyesDesigners see its templates.
offturned-off, licence-required, examples-gallery-offWhy it isn't active; a lapsed licence keeps the source but turns it off.
stateobjectyes
state.readAtstring (date-time)
state.commitstringThe commit a git source was read at.
state.templatesintegeryes
state.errorstringWhy the last read failed.
updatedAtstring (date-time)
updatedBystring

SourceTemplate ​

FieldTypeRequiredDescription
sourcestringyesThe template source's id.
idstringyesUnique in its source.
titlestringyes
descriptionstringyes
categorystringWhat kind of document it is (billing, documentation…), when its source says; the studio's gallery filters by it.
levelstarter, intermediate, advancedHow much of RFML it uses, when its source says.
pathstringIts folder in the source, when it has one.
rfmlstringyes
statusavailable, too-new, unsupportedyes
reasonstringWhy it is refused: "Needs Report Server 0.10.0 or later (RFML 0.3)".
needsstringThe first release that writes a too-new version, when this one knows.

SourceListing ​

FieldTypeRequiredDescription
idstringyes
namestringyes
kindgit, folder, galleryyes
stateok, unavailableyes
messagestring"Finance templates can't be reached right now.".
commitstring

FontSourceEdit ​

FieldTypeRequiredDescription
idstring
namestring
kindgithub, url, fontsource, indexyes
enabledboolean
ownerstringgithub.
repostringgithub.
refstringgithub: a branch, tag or commit (main by default).
layoutmetadata, foldersgithub.
pathstringgithub: the folder that holds the families.
tokenstringgithub: a secret: reference to a token, never the token.
hostsarray of stringurl and index: origins such as https://fonts.example.com or https://*.foundry.com.
indexstring (uri)index: the index's URL, on one of the hosts.
allowPrivatebooleanLet fetches reach loopback and private addresses. Link-local and cloud metadata addresses stay refused.
maxBytesintegerOne import's cap (20 MB when 0).

FontSource ​

FieldTypeRequiredDescription
presetbooleanyes
fetchHostsarray of stringyes
updatedAtstring (date-time)
updatedBystring

FontFamily ​

FieldTypeRequiredDescription
idstringyesThe family's key in its source: a folder path, a Fontsource id, an index's name.
namestringyes
categorystring
licencestringAn SPDX identifier, when the source says.

FontStyle ​

FieldTypeRequiredDescription
weightintegeryes
stylenormal, italic, obliqueyes
variablebooleanyesThe style comes from a variable file.
filestringyes
sizeinteger

FontDocument ​

FieldTypeRequiredDescription
namestringyes
kindlicence, readme, notesyes
sizeinteger

FontFamilyDetail ​

FieldTypeRequiredDescription
stylesarray of FontStyleyes
documentsarray of FontDocumentyes
licenceURLstring
subsetsarray of stringFontsource's subsets.
subsetstringThe subset an import takes unless asked for another.
versionstring
warningsarray of stringSaid before Add, such as a licence that can't be told.

FontImport ​

FieldTypeRequiredDescription
environmentstring
sourcestringyesThe font source's id.
familystringThe family's id in the source; for a url source, the family to take from a zip that holds several.
stylesarray of stringStyle keys: 400, 700italic. None means every style.
subsetstringFontsource: the subset (its default, usually latin, when left out).
urlstring (uri)url source: the link to a font file or a zip.
documentsarray of objecturl source: a licence or readme by its own link.
documents[].urlstringyes
documents[].kindlicence, readme, notesyes

LibraryFontFile ​

FieldTypeRequiredDescription
pathstringyes
weightstringyes400, or a variable file's range: 400 700.
stylenormal, italic, obliqueyes

LibraryFontDocument ​

FieldTypeRequiredDescription
pathstringyes
kindlicence, readme, notesyes

LibraryFontFamily ​

A family the library's manifest declares (fonts)

FieldTypeRequiredDescription
filesarray of LibraryFontFileyes
documentsarray of LibraryFontDocument
sourcestring
sourceNamestring
originstring
versionobjectThe 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.commitstring
version.releasestring
version.etagstring
version.lastModifiedstring
version.sha256string
version.filesmap of string

FontDeclared ​

FieldTypeRequiredDescription
familystringyes
declaredLibraryFontFamilyyes
warningsarray of stringyes
commitstringyes

AuditEvent ​

FieldTypeRequiredDescription
timestring (date-time)yes
principalstringyes
actorKindstringyesuser, key, agent, or system for reportd's own.
onBehalfOfstringThe user an agent acted for.
sourcestringapi, mcp, assistant, cli or sweep.
actionstringyes
environmentstring
templatestring
commitstring
formatstring
nodestringThe reportd node that wrote it.

AuditPage ​

FieldTypeRequiredDescription
eventsarray of AuditEventyes
nextstringThe 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.

FieldTypeRequiredDescription
kindrender, job, webhook, signIn, rateLimited, error, tallyyes
timestring (date-time)yes
nodestringyes
principalstring
onBehalfOfstring
clientstring
templatestring
environmentstring
formatstring
sourcestring
outcomestring
methodstring
classstring
jobstring
statusinteger
pagesinteger
runsinteger
attemptsinteger
msinteger (int64)
bytesinteger (int64)
requestsinteger (int64)

UsageRow ​

FieldTypeRequiredDescription
keystringThe day, template, environment or format; empty in the summary.
rendersinteger (int64)
okinteger (int64)
errorsinteger (int64)
refusedinteger (int64)
pagesinteger (int64)
bytesinteger (int64)
msinteger (int64)
p50integer (int64)
p95integer (int64)
maxinteger (int64)

UsageDay ​

FieldTypeRequiredDescription
daystring (date)
partialbooleanNot rolled up yet; totalled from its records.
peakConcurrentinteger
peakByNodemap of integer
jobsarray of object
jobs[].outcomestring
jobs[].countinteger
jobs[].runsinteger
webhooksarray of object
webhooks[].outcomestring
webhooks[].countinteger
webhooks[].attemptsinteger
requestsarray of object
requests[].classstring
requests[].requestsinteger
requests[].rateLimitedinteger
requests[].errorsinteger
signInsarray of object
signIns[].methodstring
signIns[].outcomestring
signIns[].countinteger

UsageReport ​

FieldTypeRequiredDescription
fromstring (date)yes
tostring (date)yes
byday, template, environment, formatyes
rowsarray of UsageRowyes
summaryUsageDayyes
daysarray of UsageDayyes