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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
environment | string | ||
draft | boolean | ||
commit | string | ||
params | object | ||
context | object | ||
data | auto, sample, live |
Responses
| Status | Description | Body |
|---|---|---|
200 | {datasets: {name: JSON}, origins: {name: {kind, source, bytes, reason}}} | |
403 | Live data was asked for where it isn't allowed | |
404 | The 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 |
409 | A source's connection has no binding for the environment | |
413 | A source passed its cap | |
422 | The parameters or sourceParams have errors | |
429 | The 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 |
502 | A 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
environment | query | string |
Responses
| Status | Description | Body |
|---|---|---|
200 | {environment, sources: [{name, version, versions, description, kind, connection, params, schema, hasSample, bound}]} | |
429 | The 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 | No 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)
| Field | Type | Required | Description |
|---|---|---|---|
environment | string | ||
definition | SourceDefinition | yes | |
schema | object | ||
sample | any | ||
describe | boolean | ||
params | object | Parameter values for describe. |
Responses
| Status | Description | Body |
|---|---|---|
201 | The stored version, with its query | |
409 | The version exists, or the branch moved | |
422 | The definition is not valid | |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | A dotted source name, e.g. billing.bill |
environment | query | string | ||
version | query | string |
Responses
| Status | Description | Body |
|---|---|---|
200 | ||
404 | No such source or version in the environment | |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | A dotted source name, e.g. billing.bill |
environment | query | string |
Responses
| Status | Description | Body |
|---|---|---|
200 | {name, environment, versions: [{version, description, tree, hasSample}]} | |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | A dotted source name, e.g. billing.bill |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
environment | string | ||
version | string | ||
definition | SourceDefinition | ||
params | object |
Responses
| Status | Description | Body |
|---|---|---|
200 | {schema, columns: [{name, databaseType, type, nullable}], sample} | |
403 | No source.manage or data.live, or an agent | |
409 | The connection has no binding for the environment | |
413 | The result passed the connection's row or byte cap | |
429 | The 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 |
502 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | A dotted source name, e.g. billing.bill |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
version | string | The version; empty for the latest. | |
from | string | ||
to | string | Defaults to the environment after from. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The version in the target environment, with bound | |
409 | The target holds a different copy of the version | |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
environment | query | string | ||
check | query | boolean |
Responses
| Status | Description | Body |
|---|---|---|
200 | The connections | object |
403 | The caller has neither source.read nor connection.manage in any environment asked for | |
429 | The 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)
| Field | Type | Required | Description |
|---|---|---|---|
connections | array 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
| Status | Description | Body |
|---|---|---|
200 | The policy | ConnectionPolicy |
403 | The caller has connection.manage in no environment | |
429 | The 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
| Status | Description | Body |
|---|---|---|
200 | The providers, the built-in ones first | object |
401 | Not signed in | |
403 | The caller has neither connection.manage in an environment nor settings.manage | |
429 | The 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)
| Field | Type | Required | Description |
|---|---|---|---|
providers | array 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)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | The connection's name, when it has one. | |
driver | postgres, mysql, mssql, sqlite, http | yes | |
environment | string | The environment; the first when left out. | |
binding | ConnectionBinding | yes |
Responses
| Status | Description | Body |
|---|---|---|
200 | The result, ok or failed | ConnectionTestResult |
403 | The caller lacks connection.manage in the environment | |
422 | A 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 |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
200 | The connection | Connection |
403 | The caller has neither source.read nor connection.manage anywhere | |
404 | ||
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
confirm | array of string | The environments where the change of what published sources read was confirmed. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The connection, changed | Connection |
201 | The connection, added | Connection |
400 | The 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 | |
409 | fixed: 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 |
422 | A 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 |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | |
revision | query | integer (int64) | The revision the caller saw; refused (409 changed) when it moved |
Responses
| Status | Description | Body |
|---|---|---|
204 | Deleted | |
403 | The caller lacks connection.manage in an environment with a binding | |
404 | ||
409 | fixed: 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 |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes |
Request body, optional (application/json): ConnectionAction
Responses
| Status | Description | Body |
|---|---|---|
200 | The connection | Connection |
403 | The caller lacks connection.manage in an environment with a binding | |
404 | ||
409 | fixed: 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 |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes |
Request body, optional (application/json): ConnectionAction
Responses
| Status | Description | Body |
|---|---|---|
200 | The connection | Connection |
403 | The caller lacks connection.manage in an environment with a binding | |
404 | ||
409 | fixed: 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 |
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | |
environment | query | string |
Responses
| Status | Description | Body |
|---|---|---|
200 | The result, ok or failed | ConnectionTestResult |
403 | The caller lacks connection.manage in the environment | |
404 | ||
429 | The 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | |
environment | query | string | ||
draft | query | boolean | Read the draft (or the published copy when no draft is written yet). | |
commit | query | string | ||
values | query | string | Parameter values chosen so far, as a JSON object (for cascading picklists). | |
data | query | auto, sample, live |
Responses
| Status | Description | Body |
|---|---|---|
200 | {id, environment, commit, draft, params: [{name, type, label, description, required, multiple, hidden, value, options: [{value, label}], optionsData}], values, data, diagnostics} | |
403 | Live data was asked for without data.live | |
404 | The 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 |
429 | The 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 |