Transform Authoring API
Transform Authoring APIs manage governed dbt-style transform workspaces, repository-backed projects, draft files, previews, validation, model queries, runs, packages, macros, quick fixes, chat assistance, and publication.
info
All endpoints are mounted under /api/v1.0. Paths below omit that prefix for
readability.
Base Path
/spaces/{space_slug}/transform-authoring
All endpoints require authentication and access to the target space. Workspace visibility and direct grants use the shared Authoring Workspace Access model.
Workspace Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /spaces/{space_slug}/transform-authoring/workspaces | List Transform Authoring workspaces in the space. |
POST | /spaces/{space_slug}/transform-authoring/workspaces | Create a workspace. |
PATCH | /spaces/{space_slug}/transform-authoring/workspaces/{workspace_id} | Update workspace metadata, defaults, visibility, owner, runner settings, or editor settings. |
GET | /spaces/{space_slug}/transform-authoring/workspaces/{workspace_id}/access | Read workspace access settings. |
PUT | /spaces/{space_slug}/transform-authoring/workspaces/{workspace_id}/access | Replace workspace access settings. |
POST | /spaces/{space_slug}/transform-authoring/workspaces/{workspace_id}/archive | Archive a workspace. |
Create Workspace
{
"name": "Analytics engineering",
"default_repository_id": "repository-uuid",
"owner_user_id": "owner-user-uuid",
"visibility": "shared",
"default_branch": "main",
"default_project_path": "analytics",
"default_project_type": "dbt",
"default_connector_id": "connector-uuid",
"authoring_query_connector_ids": ["connector-uuid"],
"default_environment": "dev",
"default_sql_dialect": "postgres",
"runner_settings": {},
"editor_settings": {}
}
Workspace responses include repository defaults, project defaults, owner, visibility, query connectors, default environment and dialect, runner settings, editor settings, archive timestamp, timestamps, and effective permissions.
Project Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /spaces/{space_slug}/transform-authoring/repositories/{repository_id}/projects | Discover transform projects in a repository. |
POST | /spaces/{space_slug}/transform-authoring/projects/open | Open a transform project and create or load its draft. |
PATCH | /spaces/{space_slug}/transform-authoring/projects/{project_id} | Update project metadata, base branch, connector, environment, or SQL dialect. |
Open Project
{
"workspace_id": "workspace-uuid",
"repository_id": "repository-uuid",
"project_type": "dbt",
"project_path": "analytics",
"branch": "main",
"name": "Analytics",
"connector_id": "connector-uuid",
"environment": "dev",
"sql_dialect": "postgres"
}
The open response includes the project and current draft. Project updates
accept name, base_branch, default_connector_id, environment, and
sql_dialect.
Draft File And Operation Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/tree | List the draft file tree. |
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/files/search | Search draft files. |
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/files | Read one draft file by path. |
PUT | /spaces/{space_slug}/transform-authoring/projects/{project_id}/files | Create or update a draft file. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/files/uploads | Upload one or more draft files. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/files/move | Move one or more draft files. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/files/rename | Rename one draft file. |
DELETE | /spaces/{space_slug}/transform-authoring/projects/{project_id}/files | Delete one draft file. |
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/operations | List draft operations. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/operations/{operation_id}/undo | Undo a draft operation. |
Save Draft File
{
"path": "models/marts/customer_renewals.sql",
"content": "select * from {{ ref('stg_customers') }}",
"language": "sql",
"base_sha": "optional-current-file-sha"
}
Rename and delete requests use path plus optional base_sha. Move requests
send moves, each with path, new_path, and optional base_sha.
Validation, Preview, And Model Query Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/validate | Validate the current draft. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/preview | Run a synchronous model preview. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/preview/jobs | Start an asynchronous model preview. |
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/preview/jobs/{job_id} | Read preview job status. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/model-query | Start a paginated model query. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/model-query/compile | Compile model query SQL. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/model-query/compile/jobs | Start an asynchronous model-query compile job. |
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/model-query/compile/jobs/{job_id} | Read model-query compile job status. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/model-query/{cursor_id}/next | Fetch the next model-query page. |
DELETE | /spaces/{space_slug}/transform-authoring/projects/{project_id}/model-query/{cursor_id} | Close a model-query cursor. |
Preview Or Model Query Request
{
"path": "models/marts/customer_renewals.sql",
"query_sql": "select * from model limit 100",
"connector_id": "connector-uuid",
"environment": "dev",
"resolution_mode": "standard",
"target_environment": "dev",
"scoped_schema": "qarion_preview_jdoe",
"state_manifest_connector_id": null,
"profile_key": "default",
"profile_overrides": {},
"environment_variables": {},
"compile_strategy": "full",
"row_limit": 100,
"page_size": 100
}
Preview uses row_limit. Model query uses page_size and can return a
cursor_id for pagination. Compile requests omit row_limit and use the same
connector, environment, resolution, profile, and environment-variable fields.
Runs, Macros, Environment, And Autocomplete
| Method | Endpoint | Description |
|---|---|---|
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/runs | List transform runs for a project. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/runs | Start a transform run. |
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/macros | List macros discovered in the draft. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/macros/test | Test a macro with arguments and context. |
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/environment-variables | Read allowed environment variable metadata. |
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/autocomplete | Read autocomplete context for editors. |
Create Run
{
"run_type": "static_validate",
"selector": "models/marts/customer_renewals.sql",
"connector_id": "connector-uuid",
"environment": "dev",
"allow_writes": false,
"resolution_mode": "standard",
"target_environment": "dev",
"scoped_schema": "qarion_preview_jdoe",
"state_manifest_connector_id": null,
"profile_key": "default",
"profile_overrides": {},
"environment_variables": {}
}
run_type can be parse, compile, run, test, build, render,
plan, or static_validate. Use allow_writes: false for previews and
validation flows that should not mutate target data.
Test Macro
{
"macro_name": "generate_surrogate_key",
"path": "models/marts/customer_renewals.sql",
"profile_key": "default",
"arguments": {
"columns": ["customer_id", "renewal_date"]
},
"context": {}
}
Packages And Quick Fixes
| Method | Endpoint | Description |
|---|---|---|
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/packages/preview-import | Preview importing a package into the project. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/packages/import | Import a package into the project. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/quick-fixes/dbt-model-yaml-entry | Create or update a dbt model YAML entry for a model. |
Package import requests use the Transform Package catalog contract and can
require python_package_repository create permission when importing from a
public package source. The quick-fix request accepts model_path and
model_name and returns the updated draft file, target YAML path, detected
columns, and operation metadata.
{
"model_path": "models/marts/customer_renewals.sql",
"model_name": "customer_renewals"
}
Chat And Publication Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /spaces/{space_slug}/transform-authoring/projects/{project_id}/chat/messages | List Transform Authoring chat messages. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/chat | Send a chat message to the transform authoring agent. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/chat/messages/{message_id}/apply | Apply actions from a prior chat message. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/chat/actions | Apply explicit chat actions. |
POST | /spaces/{space_slug}/transform-authoring/projects/{project_id}/publish | Publish reviewed draft changes to the repository. |
Chat requests send a message. Chat action requests apply generated actions to
the current draft and return action results plus updated draft state.
Publish Project
{
"title": "Update customer renewal model",
"body": "Validated preview and model YAML updates.",
"target_branch": "main",
"profile_key": "default",
"profile_overrides": {}
}
Publish responses include draft and project identifiers, repository identifier, source and target branches, commit SHA when available, merge request metadata, changed files, and profile metadata.
Error Notes
| Status | Meaning |
|---|---|
400 | Payload, workspace settings, project path, file path, profile, environment variable, or run request is invalid. |
403 | The user cannot view or manage the workspace, project, repository, connector, package source, or publication target. |
404 | Space, workspace, repository, project, draft file, operation, job, run, cursor, message, connector, or package source was not found. |
409 | Draft file base SHA, operation state, cursor state, publication, or concurrent draft state conflict. |
422 | Validation, compile, preview, model-query, package import, macro, or quick-fix contract failed. |
503 | dbt, SQLMesh, package installation, query execution, repository provider, or AI dependency is unavailable. |