Pipeline Authoring API

Pipeline Authoring APIs manage governed pipeline workspaces, pipeline definitions, repository-backed draft files, AI-assisted implementation runs, validation, deployment resource sync, publication, and audit history.

info

All endpoints are mounted under /api/v1.0. Paths below omit that prefix for readability.

Base Path

/spaces/{space_slug}/pipeline-authoring

All endpoints require authentication and access to the target space. Workspace visibility and direct grants use the shared Authoring Workspace Access model.

Workspace And Settings Endpoints

Method	Endpoint	Description
`GET`	`/spaces/{space_slug}/pipeline-authoring/workspaces`	List Pipeline Authoring workspaces in the space.
`POST`	`/spaces/{space_slug}/pipeline-authoring/workspaces`	Create a workspace.
`PATCH`	`/spaces/{space_slug}/pipeline-authoring/workspaces/{workspace_id}`	Update workspace metadata, repository, visibility, owner, query connectors, or customization.
`GET`	`/spaces/{space_slug}/pipeline-authoring/workspaces/{workspace_id}/access`	Read workspace access settings.
`PUT`	`/spaces/{space_slug}/pipeline-authoring/workspaces/{workspace_id}/access`	Replace workspace access settings.
`POST`	`/spaces/{space_slug}/pipeline-authoring/workspaces/{workspace_id}/archive`	Archive a workspace.
`GET`	`/spaces/{space_slug}/pipeline-authoring/settings`	Read the current user's Pipeline Authoring defaults.
`PATCH`	`/spaces/{space_slug}/pipeline-authoring/settings`	Update the current user's default repository.

Create Workspace

{
  "name": "Customer renewal pipelines",
  "default_repository_id": "repository-uuid",
  "owner_user_id": "owner-user-uuid",
  "visibility": "shared",
  "authoring_query_connector_ids": ["connector-uuid"],
  "customization": {}
}

Workspace responses include identity, default repository, owner, visibility, authoring query connectors, customization, archive timestamp, timestamps, and effective_permissions.

Definition And Version Endpoints

Method	Endpoint	Description
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions`	List pipeline definitions.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions`	Create a pipeline definition.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}`	Read one pipeline definition.
`PATCH`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}`	Update metadata, workspace, repository, or spec.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/versions`	List saved definition versions.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/versions/{version_id}/compare`	Compare a saved version with the current definition.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/versions/{version_id}/restore`	Restore a saved version.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/archive`	Archive a definition.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publish`	Publish reviewed files to the configured repository.

Create Definition

{
  "name": "Customer renewal load",
  "description": "Loads renewal candidates and quality checks.",
  "target": "airflow",
  "workspace_id": "workspace-uuid",
  "repository_id": "repository-uuid",
  "spec": {}
}

target selects the pipeline runtime target, such as Airflow or Dagster. Updates accept name, description, workspace_id, repository_id, spec, and an optional change_summary.

Graph And README Endpoints

Method	Endpoint	Description
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/nodes`	List `spec.nodes` with upstream and downstream dependency counts.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/nodes/{node_id}`	Read one node with upstream and downstream edge IDs.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/nodes`	Add one canonical node and optional upstream/downstream dependencies.
`PATCH`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/nodes/{node_id}`	Patch canonical node fields. Node ID changes are rejected.
`DELETE`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/nodes/{node_id}`	Delete one node and all incident dependencies.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/dependencies`	List `spec.edges` using public dependency terminology.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/dependencies`	Add one dependency edge.
`DELETE`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/dependencies`	Remove one dependency edge.
`PUT`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/dependencies`	Replace all dependency edges.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readme`	Resolve and read the DAG README resource.
`PUT`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readme`	Create or update the DAG README through the draft-file overlay.
`DELETE`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readme`	Delete the README override or mark repository content deleted.

Graph mutations require manage access, reject archived definitions, validate the full PipelineAuthoringSpec, and append exactly one new definition version. Responses include the refreshed definition for mutating calls. Duplicate nodes, duplicate dependencies, missing nodes, unsupported node ID changes, and invalid full specs fail before a new version is written.

Add Node

{
  "node": {
    "id": "load_customer_renewals",
    "type": "python_module",
    "label": "Load customer renewals",
    "module": "pipelines.customer_renewals",
    "callable": "load"
  },
  "upstream": ["extract_customer_renewals"],
  "downstream": ["validate_customer_renewals"],
  "change_summary": "Add renewal load task"
}

Public API terminology uses nodes and dependencies; the persisted spec keeps nodes and edges. Direct API mutations expect canonical node payloads. Guided agent flows can still normalize connector and credential names before preparing reviewed actions.

Replace Dependencies

{
  "edges": [
    { "upstream": "extract_customer_renewals", "downstream": "load_customer_renewals" },
    { "upstream": "load_customer_renewals", "downstream": "validate_customer_renewals" }
  ],
  "change_summary": "Rewire renewal task order"
}

Update README

{
  "path": "dags/customer_renewal.md",
  "content": "# Customer renewal DAG\n\nDaily renewal-candidate load.",
  "base_sha": "optional-current-readme-sha",
  "change_summary": "Document renewal DAG"
}

README path resolution is: explicit deployment.readme_path, else the DAG or artifact path with an .md suffix, else README.md. Supplying path on update persists deployment.readme_path. base_sha is optional, but when supplied it must match the active README file at that path. README updates and deletes reuse the existing draft-file override/deletion semantics; generic file CRUD remains available for other files.

Planner-facing graph tools are intentionally split from direct API mutation: read tools list/get nodes, dependencies, and README content, while prepare tools return structured add_node, update_node, remove_node, add_edge, remove_edge, replace_edges, set_deployment, and upsert_workspace_file actions for review. Prepare tools do not persist versions by themselves.

Publish Definition

{
  "repository_id": "repository-uuid",
  "title": "Add customer renewal pipeline",
  "body": "Generated and validated in Qarion.",
  "sandbox_policy": "enforce"
}

Publish responses include the updated definition, source and target branches, merge request identity and URL when available, generated files, and validation report details. Publication is intended for reviewed changes that have passed the applicable generated-code and validation gates.

Draft File Endpoints

Method	Endpoint	Description
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/tree`	List the draft file tree.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/search`	Search draft files.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files`	Read one draft file by path.
`PUT`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files`	Create or update a draft file.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/uploads`	Upload one or more draft files.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/rename`	Rename one draft file.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/move`	Move one or more draft files.
`DELETE`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files`	Delete one draft file.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/reset-override`	Reset a draft override back to repository content.

Save Draft File

{
  "path": "dags/customer_renewal.py",
  "content": "from airflow import DAG\n",
  "language": "python",
  "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.

Context, Autocomplete, And Clarifications

Method	Endpoint	Description
`GET`	`/spaces/{space_slug}/pipeline-authoring/context`	Read the authoring context bundle for the space.
`POST`	`/spaces/{space_slug}/pipeline-authoring/editor/completions`	Request repository-aware editor completions.
`GET`	`/spaces/{space_slug}/pipeline-authoring/clarifications/context`	Read available clarification context.
`POST`	`/spaces/{space_slug}/pipeline-authoring/clarifications/credentials`	Store credential answers for a clarification flow.
`POST`	`/spaces/{space_slug}/pipeline-authoring/clarifications/schema-preview`	Preview schema details needed by a clarification.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/clarifications/history`	List clarification history for a definition.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/clarifications/state`	Save clarification state.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/clarifications/activity`	Record a clarification activity event.

Editor completion requests include the file path, cursor position, content, and optional language/context fields. Clarification requests are used by the agent flow when missing connector, credential, schema, or requirement details must be captured before generation continues.

Chat And Agent Job Endpoints

Method	Endpoint	Description
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat`	Send a synchronous authoring message.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/messages`	List authoring conversation messages.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/stream`	Stream an authoring response as server-sent events.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/jobs`	Start an asynchronous authoring job.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/jobs/active`	Read the active job for the definition, if any.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/decisions/{decision_request_id}/job`	Find the job associated with a plan decision request.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/jobs/{job_id}`	Read authoring job status.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/jobs/{job_id}/cancel`	Cancel an authoring job.

Chat Request

{
  "message": "Create a daily Airflow pipeline for renewal candidates.",
  "clarification_submission": null,
  "plan_decision": null,
  "recovery_context": null,
  "authoring_mode": "guided",
  "reasoning_level": "standard"
}

Chat responses can include the updated definition, validation result, assistant message records, checkpoint and workflow identifiers, repo edit session identifier, applied actions, clarification requirements, plan review, task checklist, parallel subagent summary, and activity events. chat/stream returns text/event-stream.

Compiler, Validation, And Deployment Endpoints

Method	Endpoint	Description
`GET`	`/spaces/{space_slug}/pipeline-authoring/node-catalog`	List supported pipeline node types and options.
`POST`	`/spaces/{space_slug}/pipeline-authoring/compiler/validate`	Validate a pipeline authoring spec.
`POST`	`/spaces/{space_slug}/pipeline-authoring/compiler/compile`	Compile a pipeline authoring spec.
`POST`	`/spaces/{space_slug}/pipeline-authoring/compiler/jobs`	Start an asynchronous compile or validate job.
`GET`	`/spaces/{space_slug}/pipeline-authoring/compiler/jobs/{job_id}`	Read compiler job status.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/deployment-resources`	Preview deployment resources needed by a definition.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/deployment-resources/sync`	Sync deployment resources to an orchestrator connector.

Validate and compile requests send spec. Compiler jobs send mode as validate or compile plus spec.

{
  "mode": "validate",
  "spec": {}
}

Deployment resource sync accepts an optional orchestrator_connector_id and returns created, updated, skipped, and failed resource counts.

Repo Edit Session And Audit Endpoints

Method	Endpoint	Description
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions`	List repo edit sessions for a definition.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/active`	Read the active repo edit session, if any.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}`	Read repo edit session detail.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/events`	List repo edit session events.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/pending-changes`	Read pending generated-file changes.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/resume`	Resume a paused repo edit session.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/retry`	Retry a repo edit session from a selected point.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/cancel`	Cancel a repo edit session.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/audit-history`	List audit history for a definition.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/audit-history/{audit_run_id}`	Read one audit-history run.

Repo edit sessions capture the review-gated agent lifecycle: plan reviews, task checklist evidence, generated files, command approval requests, pending changes, retry/resume events, and cancellation. Audit history is read-only and supports downstream governance and troubleshooting views.

Error Notes

Status	Meaning
`400`	Payload, workspace settings, file path, spec, or plan decision is invalid.
`403`	The user cannot view or manage the workspace, definition, repository, connector, or deployment target.
`404`	Space, workspace, definition, version, file, job, session, audit run, repository, or connector was not found.
`409`	Draft file base SHA, active job/session state, stale review, or publication state conflict.
`422`	A generated-code, validation, compiler, clarification, or request-contract check failed.
`503`	Authoring runtime, compiler, repository provider, deployment connector, or AI dependency is unavailable.

Base Path​

Workspace And Settings Endpoints​

Create Workspace​

Definition And Version Endpoints​

Create Definition​

Graph And README Endpoints​

Add Node​

Replace Dependencies​

Update README​

Publish Definition​

Draft File Endpoints​

Save Draft File​

Context, Autocomplete, And Clarifications​

Chat And Agent Job Endpoints​

Chat Request​

Compiler, Validation, And Deployment Endpoints​

Repo Edit Session And Audit Endpoints​

Error Notes​

Related​