Skip to content

Data sources ​

Data sources and connections, the secret providers they read, and the data and parameters a template reads.

POST /v1/templates/{id}/data ​

The data a preview would use, by the render policy (for the designer).

Runs the data plan without rendering: live datasets where the caller may use live data (data: live for drafts), else the sources' samples. Datasets that use the document's own samples are left out. Agents, MCP tools and read-only callers get samples; data: live where that isn't allowed is 403.

Parameters

NameInTypeRequiredDescription
idpathstringyes

Request body (application/json)

FieldTypeRequiredDescription
environmentstring
draftboolean
commitstring
paramsobject
contextobject
dataauto, sample, live

Responses

StatusDescriptionBody
200{datasets: {name: JSON}, origins: {name: {kind, source, bytes, reason}}}
403Live data was asked for where it isn't allowed
404The template is in the trash: {error: "in-trash", message, item}. item, the trash item's id, is there only for callers with template.read.object
409A source's connection has no binding for the environment
413A source passed its cap
422The parameters or sourceParams have errors
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object
502A data source failed

GET /v1/sources ​

The source catalogue of one environment (RFML §10.4), without queries.

Each source's latest version: name, description, kind (sql or http), connection, typed params, the output schema and whether it has a sample, every version, and bound (its connection has a binding in this environment). Needs source.read. Queries are never listed.

Parameters

NameInTypeRequiredDescription
environmentquerystring

Responses

StatusDescriptionBody
200{environment, sources: [{name, version, versions, description, kind, connection, params, schema, hasSample, bound}]}
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object
503No source catalogue (sourceControl.driver is not git)

POST /v1/sources ​

Add a source version (source.manage).

Writes sources/<name>/<version>/{source.json,schema.json,sample.json} on the environment branch. Versions are immutable: an existing one is 409. The connection must exist and be of the definition's kind. With describe: true the query is run once (needs data.live) to fill in the schema and, when none is given, the sample. Agents can't define sources.

Request body (application/json)

FieldTypeRequiredDescription
environmentstring
definitionSourceDefinitionyes
schemaobject
sampleany
describeboolean
paramsobjectParameter values for describe.

Responses

StatusDescriptionBody
201The stored version, with its query
409The version exists, or the branch moved
422The definition is not valid
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

GET /v1/sources/{name} ​

One source version (the latest, or ?version=) with its schema and sample.

The query is included only for callers with source.manage, and never through MCP tools.

Parameters

NameInTypeRequiredDescription
namepathstringyesA dotted source name, e.g. billing.bill
environmentquerystring
versionquerystring

Responses

StatusDescriptionBody
200
404No such source or version in the environment
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

GET /v1/sources/{name}/versions ​

Every version of a source in one environment, oldest first.

Parameters

NameInTypeRequiredDescription
namepathstringyesA dotted source name, e.g. billing.bill
environmentquerystring

Responses

StatusDescriptionBody
200{name, environment, versions: [{version, description, tree, hasSample}]}
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

POST /v1/sources/{name}/describe ​

Run a source once and describe its result.

Runs a stored version, or an unsaved definition, through the environment's connection and returns a JSON Schema, the SQL columns and up to 20 rows. It reads live data: it needs source.manage and data.live, and agents and MCP tools can't.

Parameters

NameInTypeRequiredDescription
namepathstringyesA dotted source name, e.g. billing.bill

Request body (application/json)

FieldTypeRequiredDescription
environmentstring
versionstring
definitionSourceDefinition
paramsobject

Responses

StatusDescriptionBody
200{schema, columns: [{name, databaseType, type, nullable}], sample}
403No source.manage or data.live, or an agent
409The connection has no binding for the environment
413The result passed the connection's row or byte cap
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object
502The source failed; the message names no connection details

POST /v1/sources/{name}/promote ​

Copy one source version from one environment to another.

Needs source.read in from and source.manage in to. Copying a version the target holds unchanged does nothing; one that differs is 409.

Parameters

NameInTypeRequiredDescription
namepathstringyesA dotted source name, e.g. billing.bill

Request body (application/json)

FieldTypeRequiredDescription
versionstringThe version; empty for the latest.
fromstring
tostringDefaults to the environment after from.

Responses

StatusDescriptionBody
200The version in the target environment, with bound
409The target holds a different copy of the version
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

GET /v1/connections ​

Every data connection and its health, never a secret's value.

The operator's connections from config.yaml (origin config, fixed: the studio can't change them) and those added in the studio (origin studio), per environment the caller has source.read or connection.manage in. A studio connection whose name config.yaml has since taken is listed beside config's with shadowed: true, and config's is used. Each environment's status is unbound (no binding, or turned off), shadowed, unchecked, ok or error; usedBy counts the sources there that use it (any version). With connection.manage in an environment, a studio connection's binding there is shown too, its fields and secret: references, never their values; config's references are never shown. check=true pings each binding, and counts in the probe rate class (10 a minute by default) rather than read; messages name no hosts, users or driver errors.

Parameters

NameInTypeRequiredDescription
environmentquerystring
checkqueryboolean

Responses

StatusDescriptionBody
200The connectionsobject
403The caller has neither source.read nor connection.manage in any environment asked for
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

200 body (application/json)

FieldTypeRequiredDescription
connectionsarray of ConnectionInfo

GET /v1/connections/policy ​

The policy studio connections are held to, for the form.

Needs connection.manage in an environment. The administrator's data.connections settings: the hosts a binding may reach (saveable is false while there are none), private and loopback addresses, the SQLite folder and the files in it, the secret: reference patterns, the secret providers running (env and file, as secrets.providers turns them on, and the secret plugins that are up; a writable one takes typed secrets), the environments the caller manages, and the options each driver's fields may set.

Responses

StatusDescriptionBody
200The policyConnectionPolicy
403The caller has connection.manage in no environment
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

GET /v1/secrets/providers ​

The secret providers, and how each one is.

Needs connection.manage in an environment, or settings.manage. The built-in providers (env and file, as secrets.providers turns them on) and the secret plugins secrets.plugins names, each with its state: ok, degraded or failing (a running plugin's answer to health), starting, restarting (after a crash, with back-off), waiting (for the licence check), refused (a licence feature the licence lacks, or no protocol version in common) or stopped. The message is reportd's own words, or a running plugin's health message; never a value. stale counts the values reportd keeps serving past secrets.cacheSec while the plugin fails, for up to secrets.staleSec.

Responses

StatusDescriptionBody
200The providers, the built-in ones firstobject
401Not signed in
403The caller has neither connection.manage in an environment nor settings.manage
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

200 body (application/json)

FieldTypeRequiredDescription
providersarray of SecretProvider

POST /v1/connections/test ​

Test an unsaved binding from the form.

Needs connection.manage in the environment. The binding is checked as a save checks it (the policy's hosts, the SQLite folder, the secret patterns, the options) before anything is dialled; then it is opened on a connector of its own and pinged within 5 s. A secret field may be {"set": "<value>"}, used for this test only and kept nowhere. The answer is a category, never a driver's text. Audited as data.connection.test <name>, or (a new connection) without a name. Counts in the probe rate class.

Request body (application/json)

FieldTypeRequiredDescription
namestringThe connection's name, when it has one.
driverpostgres, mysql, mssql, sqlite, httpyes
environmentstringThe environment; the first when left out.
bindingConnectionBindingyes

Responses

StatusDescriptionBody
200The result, ok or failedConnectionTestResult
403The caller lacks connection.manage in the environment
422A connection or binding that can't be saved or tested: {error, field, message}, error one of invalid (a bad field), secret-literal (a value where a secret: reference goes), policy (outside the administrator's data.connections policy: a host, an address, the SQLite folder, a reference outside the patterns or one reportd's own settings use) or no-store (a {"set"} on a save, with no secret store plugin running).object
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

GET /v1/connections/{name} ​

One connection, its revision and its dependents.

Needs source.read or connection.manage in an environment. bound lists every environment with a binding; environments holds the bindings of those the caller manages (a studio connection's only). dependents are the sources using it in each environment the caller may see. For a config connection whose name a studio connection also has, shadowed is that studio connection.

Parameters

NameInTypeRequiredDescription
namepathstringyes

Responses

StatusDescriptionBody
200The connectionConnection
403The caller has neither source.read nor connection.manage anywhere
404
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

PUT /v1/connections/{name} ​

Add or change a studio connection.

The connection as it should be, with the revision it changes (0 to add). Needs connection.manage in every environment whose binding it adds, changes or removes; a binding in an environment the caller doesn't manage (and so never sees) stays as it is when left out. A change of driver, a limit, or disabled reaches every binding, so needs it in each. A binding outside the first environment needs the environments licence feature (Community has one environment). The name can't change, and can't be one config.yaml uses. A change, removal or turning off of a binding in an environment where sources use the connection needs confirm naming that environment (409 needs-confirm). Sending what is there writes nothing. Audited as data.connection.add <name> per environment bound, or data.connection.change <name>: <fields> per environment touched, naming fields and never values (a secret field as password (reference), or password (stored secret) when typed in) and ending (confirmed) after a confirm; driver, limits and description as one change event with no environment. A secret field sent as {"set"} is put in the store plugin, or replaces the field's stored secret (a change, so it may need a confirm), audited as secret.set or secret.replace <reference> (<name>, <environment>, <field>); a stored secret the change leaves unused (its binding removed, or its field moved to a reference) is deleted, audited as secret.delete. A store that fails the write answers 503 secret-store, and nothing is saved.

Parameters

NameInTypeRequiredDescription
namepathstringyes

Request body (application/json)

FieldTypeRequiredDescription
confirmarray of stringThe environments where the change of what published sources read was confirmed.

Responses

StatusDescriptionBody
200The connection, changedConnection
201The connection, addedConnection
400The body isn't a connection (an unknown field, say)
403{error: forbidden, environment}: the caller lacks connection.manage in an environment the change touches; or LicenceRequired (environments) for a binding outside the first environment
409fixed: config.yaml has the name, so the studio can't change it or take it. changed: the revision moved (revision is the current one): load it again. needs-confirm: published sources read through the binding in environments (their names in dependents): send it again with confirm naming each. in-use: sources use the connection (dependents), so it can't be deleted.object
422A connection or binding that can't be saved or tested: {error, field, message}, error one of invalid (a bad field), secret-literal (a value where a secret: reference goes), policy (outside the administrator's data.connections policy: a host, an address, the SQLite folder, a reference outside the patterns or one reportd's own settings use) or no-store (a {"set"} on a save, with no secret store plugin running).object
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object
503{error: secret-store, message}: the secret store plugin failed to keep a typed secret; nothing was saved

DELETE /v1/connections/{name} ​

Delete a studio connection.

Needs connection.manage in every environment with a binding. Refused while any source uses it (409 in-use with the dependents): turning it off is the step that can be undone. A shadowed connection is never in use. Audited as data.connection.remove <name>. Its stored secrets are deleted from the store plugin, each audited as secret.delete <reference> (<name>, <environment>, <field>).

Parameters

NameInTypeRequiredDescription
namepathstringyes
revisionqueryinteger (int64)The revision the caller saw; refused (409 changed) when it moved

Responses

StatusDescriptionBody
204Deleted
403The caller lacks connection.manage in an environment with a binding
404
409fixed: config.yaml has the name, so the studio can't change it or take it. changed: the revision moved (revision is the current one): load it again. needs-confirm: published sources read through the binding in environments (their names in dependents): send it again with confirm naming each. in-use: sources use the connection (dependents), so it can't be deleted.object
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

POST /v1/connections/{name}/disable ​

Turn a studio connection off.

Off, it behaves as one with no binding: a live fetch fails with "connection <name> is turned off". Needs connection.manage in every environment with a binding, and confirm naming each where sources use it (409 needs-confirm). Audited as data.connection.disable <name> per environment, ending (confirmed) after a confirm.

Parameters

NameInTypeRequiredDescription
namepathstringyes

Request body, optional (application/json): ConnectionAction

Responses

StatusDescriptionBody
200The connectionConnection
403The caller lacks connection.manage in an environment with a binding
404
409fixed: config.yaml has the name, so the studio can't change it or take it. changed: the revision moved (revision is the current one): load it again. needs-confirm: published sources read through the binding in environments (their names in dependents): send it again with confirm naming each. in-use: sources use the connection (dependents), so it can't be deleted.object
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

POST /v1/connections/{name}/enable ​

Turn a studio connection on again.

Needs connection.manage in every environment with a binding. Audited as data.connection.enable <name>.

Parameters

NameInTypeRequiredDescription
namepathstringyes

Request body, optional (application/json): ConnectionAction

Responses

StatusDescriptionBody
200The connectionConnection
403The caller lacks connection.manage in an environment with a binding
404
409fixed: config.yaml has the name, so the studio can't change it or take it. changed: the revision moved (revision is the current one): load it again. needs-confirm: published sources read through the binding in environments (their names in dependents): send it again with confirm naming each. in-use: sources use the connection (dependents), so it can't be deleted.object
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

POST /v1/connections/{name}/test ​

Test a saved binding.

Needs connection.manage in the environment. The binding (config's or the studio's) is opened on a connector of its own, pinged within 5 s, and closed; a studio connection is checked against the policy again first. The answer is a category, never a driver's text. Audited as data.connection.test <name>, so a probing pattern shows in the log. Counts in the probe rate class.

Parameters

NameInTypeRequiredDescription
namepathstringyes
environmentquerystring

Responses

StatusDescriptionBody
200The result, ok or failedConnectionTestResult
403The caller lacks connection.manage in the environment
404
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object

GET /v1/templates/{id}/params ​

The template's parameters as prompts, with picklist choices.

Every declared parameter in order, with its bound value and its options. Computed options that read datasets are evaluated against data loaded by the render policy (samples for agents, MCP tools, read-only callers and drafts; live where the caller has data.live). X-Data-Origins says where each loaded dataset came from.

Parameters

NameInTypeRequiredDescription
idpathstringyes
environmentquerystring
draftquerybooleanRead the draft (or the published copy when no draft is written yet).
commitquerystring
valuesquerystringParameter values chosen so far, as a JSON object (for cascading picklists).
dataqueryauto, sample, live

Responses

StatusDescriptionBody
200{id, environment, commit, draft, params: [{name, type, label, description, required, multiple, hidden, value, options: [{value, label}], optionsData}], values, data, diagnostics}
403Live data was asked for without data.live
404The template is in the trash: {error: "in-trash", message, item}. item, the trash item's id, is there only for callers with template.read.object
429The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.object