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.

Managed API Connector Contracts

Pipeline Authoring API operations are bound to the active immutable contract snapshot of an api connector. Contract endpoints use the connector API base path rather than the Pipeline Authoring base path.

Method	Endpoint	Description
`GET`	`/connectors/spaces/{space_slug}/{connector_id}/api-contract`	Read the active normalized contract snapshot, or `null` when none is active.
`PUT`	`/connectors/spaces/{space_slug}/{connector_id}/api-contract`	Activate a reviewed manual or repository-file normalized contract.
`POST`	`/connectors/spaces/{space_slug}/{connector_id}/api-contract/refresh`	Explicitly fetch, normalize, hash, and activate the configured remote definition.
`POST`	`/connectors/spaces/{space_slug}/{connector_id}/test`	Validate connector configuration, compatible credentials, and contract access without invoking write operations.

An API connector selects rest, soap, or graphql and an authentication mode of none, basic, api_key, bearer, or oauth2_client_credentials. Except for none, it must reference an active, compatible Qarion credential available in the same space. Connector configuration must contain only non-secret values; secret-bearing headers or fields are rejected.

Manual contract writes accept a normalized contract and optional source metadata:

{
  "source_kind": "manual",
  "source_reference": "reviewed customer API definition",
  "contract": {
    "protocol": "rest",
    "title": "Customer API",
    "version": "2026-07",
    "endpoints": ["https://api.example.com"],
    "operations": [
      {
        "key": "getCustomer",
        "method": "GET",
        "path": "/customers/{customer_id}",
        "request_schema": {},
        "response_schema": {},
        "security": [],
        "pagination": {},
        "destructive": false
      }
    ],
    "schemas": {},
    "security_schemes": [],
    "pagination": {},
    "metadata": {}
  }
}

Snapshot responses include id, connector_id, protocol, source metadata, the normalized contract, a SHA-256 content_hash, active status, and timestamps. Snapshot history is retained. A failed refresh does not deactivate the last successful snapshot. Remote definitions and their imports are subject to HTTPS allowlisting, DNS and private-network protection, same-origin redirect rules, bounded document/import graphs, and no cross-origin credential forwarding.

Pipeline specs persist connector and optional credential IDs, the active snapshot ID and hash, the normalized operation key, and reviewed non-secret operation details. Publication and execution fail closed on contract drift, missing or incompatible resources, unresolved standards conflicts, failed resource synchronization, or missing destructive confirmation.

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.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readiness`	Read version-bound readiness for generation, resource sync, or publication.
`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.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/deployment-artifacts`	List immutable Airflow packaged-DAG artifacts.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/deployment-artifacts/{artifact_id}/download`	Download an authorized packaged-DAG ZIP.

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.

For Airflow, deployment.airflow_package_mode accepts extracted (the default) or zipimport. deployment.requirements_manifest_path is an optional safe, repository-relative path whose basename is requirements.txt or pyproject.toml. When omitted, Qarion walks from the generated DAG's directory toward the repository root and uses the nearest supported manifest. Two formats at the same nearest directory require clarification.

Airflow publication creates the artifact after authoritative generated-code and dependency-lock validation and before any Git mutation. Its runtime closure contains the DAG, transitive repository-local imports, package initializers, explicit runtime files, the selected manifest, exact hash-verified wheel contents, and .qarion/deployment.json. Entries are sorted and receive stable timestamps and permissions, so identical inputs produce the same SHA-256. zipimport rejects native extensions; extracted supports native wheels only when they match the configured Airflow Python/platform target. Extracted mode preserves repository-relative paths; ZIP-import mode places the DAG module at the archive root because Airflow reads that ZIP directly from DAGS_FOLDER.

The synchronous publish response and completed publication-operation result include deployment_artifact metadata. A list response has the following shape:

{
  "items": [
    {
      "id": "8b00c45b-0ea4-4fb0-93c5-441e11621d64",
      "definition_version_id": "55b866d8-d978-4719-881c-54ed57145968",
      "package_mode": "extracted",
      "manifest_path": "dags/finance/requirements.txt",
      "dependency_lock_identity": "<sha256>",
      "filename": "renewals-55b866d8-extracted.zip",
      "sha256": "<sha256>",
      "size_bytes": 184320,
      "status": "ready"
    }
  ],
  "total": 1
}

Configure the storage family with PIPELINE_AUTHORING_ARTIFACT_STORAGE_BACKEND and the matching LOCAL_DIR, S3_*, GCS_*, or AZURE_* variables. Archive limits are controlled by PIPELINE_AUTHORING_ARTIFACT_MAX_MB and PIPELINE_AUTHORING_ARTIFACT_MAX_UNCOMPRESSED_MB. The demo uses its artifact bucket under the pipeline-authoring/ prefix. Helm exposes the same family as backend.config.artifactStorage.pipelineAuthoringArtifacts, including optional airflowPlatform and airflowPythonVersion wheel-target settings.

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": "strict"
}

Publish responses include the updated definition, source and target branches, merge request identity and URL when available, generated files, and validation report details. Publication locks and revalidates the current immutable version before any Git mutation. Its strict gate requires compiler, static-code, support-test, dependency, runtime-resource, and sandbox sections to be exactly passed; warnings or skipped requested checks block publication. The fast policy is a non-production diagnostic override and does not bypass a configured block-mode publication gate.

Durable Publication And Resource Sync

New integrations should use the asynchronous operation resources. They survive request loss, worker restarts, duplicate delivery, and browser reloads while preserving checkpoint and per-resource evidence.

Method	Endpoint	Description
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publication-operations`	Create or recover an idempotent publication operation.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publication-operations`	List recent or active operations for reconnect recovery.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publication-operations/{operation_id}`	Read checkpoint, progress, readiness evidence, result, and recovery capabilities.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publication-operations/{operation_id}/cancel`	Cancel before the first Git mutation.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publication-operations/{operation_id}/retry`	Create an audited child attempt.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/resource-sync-runs`	Create or recover an idempotent managed-resource sync.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/resource-sync-runs`	List recent or active sync runs for reconnect recovery.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/resource-sync-runs/{run_id}`	Read aggregate status and durable per-item results.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/resource-sync-runs/{run_id}/cancel`	Stop before the next resource mutation while retaining completed items.
`POST`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/resource-sync-runs/{run_id}/retry`	Retry only incomplete or retryable items in an audited child run.

Create and retry requests require an Idempotency-Key header. Reusing a key with the same canonical request returns the original resource; reusing it for a different request returns 409. Accepted create/retry commands return 202, a Location header, and the current typed operation resource. Poll Location with backoff or discover active resources through the collection endpoints.

The legacy publish and resource-sync endpoints remain available during the migration. They create the same durable aggregates inline and may include an operation_id or run_id in their compatibility response.

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.
`PUT`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/interactions/{interaction_id}/answers`	Atomically replace a native interaction's complete answer batch using an expected revision.
`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.

Native message reads expose a typed interaction. Clarification interactions carry an opaque revision, backend-computed item and batch completeness, continuation state, available commands, and optional committed progress. waiting_external is a separate interaction kind and does not accept answer batches. A stale expected revision returns 409 with the latest interaction.

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,
  "repair_request": 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, activity events, budget_state, repair_outcome, and typed recovery_actions. The string next_actions field remains available during the compatibility migration. chat/stream returns text/event-stream.

New or revised plan reviews expose top-level execution_units, related to their business tasks by parent_plan_task_id and rendered beneath those tasks in the cockpit. A unit carries id, kind, depends_on, required, allowed action categories, bounded path/spec targets, acceptance criteria, evidence requirements, a verification profile, and approved-plan and input hashes. Applied actions and checklist evidence carry execution_unit_id; strict plans reject actions that are missing attribution or fall outside that unit's scope. Execution uses dependency-ordered waves with at most three non-overlapping units. Older approved plans derive one compatibility unit per plan item and do not retroactively enable the strict scope contract.

Successful unit candidates and evidence are checkpointed by the repository edit session. A changed plan or unit-input hash invalidates only affected unit checkpoints. Partial or incomplete execution slices remain resumable but cannot satisfy the publication gate.

Targeted Repair Request

Use repair_request instead of embedding validation JSON in message. The server resolves every target against the current compiler report and repository edit session before enqueueing recovery work.

{
  "message": "Repair the selected validation findings.",
  "repair_request": {
    "source": "validation_diagnostic",
    "compiler_job_id": "compiler-job-uuid",
    "validation_report_hash": "64-character-sha256-hash",
    "diagnostic_ids": ["diagnostic:stable-id"],
    "section_categories": [],
    "execution_unit_ids": ["implement-renewal-load"],
    "repo_edit_session_id": "repo-edit-session-uuid",
    "requested_strategy": "targeted"
  }
}

source is validation_section, validation_diagnostic, or diff_review; requested_strategy is auto, targeted, retry_validation, or replan. Section and diagnostic sources require their corresponding target lists. Execution-unit targets require a repository edit session. Qarion returns 409 when the compiler request no longer matches the current spec, the report hash or selected diagnostics changed, or the selected execution units are stale.

Diagnostics and blocking diff findings can produce these independent repair routes: code_repairable, plan_repairable, user_input, environment, transient, unsafe_scope, and internal. Responses expose route-specific recovery_actions, such as retry_failed_units, revise_plan, provide_input, resolve_environment, retry_validation, or inspect_recovery_context.

To act on a native interaction, omit message and send interaction_response. The server validates requirement metadata, creates the safe summary message, and derives an idempotency key. kind: "clarification" remains accepted for legacy clients; native external-wait retries use kind: "waiting_external".

{
  "interaction_response": {
    "schema_version": "1",
    "kind": "clarification",
    "interaction_id": "opaque-interaction-id",
    "expected_revision": "opaque-revision",
    "client_request_id": "client-generated-id",
    "command": "submit",
    "answers": [
      {
        "requirement_id": "target_mapping",
        "values": {"customer_key": "customer_id"}
      }
    ]
  }
}

Commands are submit, cancel, retry, and summarize_saved. Cancelling an interaction whose draft effect is advanced also requires cancel_mode set to keep_progress or restore_base.

Incremental Job Polling

The chat-job status endpoint accepts after_sequence and timeout_ms. Omit the cursor on the initial read. For subsequent reads, pass the latest received next_sequence; the response includes only newer progress_events and narrative_events. A request can wait up to 20,000 milliseconds for a new event or terminal state.

GET .../chat/jobs/{job_id}?after_sequence=42&timeout_ms=20000

Job status exposes next_sequence, budget_state, repair_outcome, execution_unit_states, recovery_actions, narrative_events, and narrative_omitted_count directly, including while the job is active. execution_unit_states includes dependencies, evidence and action references, and blocked reasons.

Each narrative_events item is a versioned, public-safe Eve milestone with a stable id, source_sequence, kind, status, optional phase, localized title_key plus title_fallback, bounded body, optional source_role and step_id, evidence_refs, and authorized technical ai_log_ids. Clients should upsert by id, accept the greatest source_sequence, and preserve source order. A running milestone therefore becomes its completed, degraded, or failed form without producing a duplicate message.

The server retains at most 50 narrative items. narrative_omitted_count reports older compacted items. Assistant-message agent_activity snapshots use schema v2 for the same durable transcript; readers must continue accepting v1 snapshots without narration.

Narration is projected after progress-event redaction and is not raw chain-of-thought. Prompts, tool arguments and results, provider-private reasoning, heartbeats, streaming tokens, cache telemetry, and raw model payloads are excluded. Narrative items are not separate chat messages and are not included in rolling summaries, semantic memory, recent prompt messages, or future model context.

budget_state distinguishes logical operations from provider attempts and can include lane usage, token usage and reservation, remaining deadline, and an exact exhaustion reason. Pipeline Authoring enforces a 48 logical-operation ceiling: 36 shared planning/implementation operations, 4 protected final-review operations, and 8 protected repair/replan operations. Unused work capacity can roll forward to repair; work cannot draw from either protected reserve. Provider invocations and retries are counted separately from logical operations. Older checkpoint payloads that recorded only ai_calls remain readable and may project that legacy value into both counters.

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.
`POST`	`/spaces/{space_slug}/pipeline-authoring/compiler/jobs/{job_id}/cancel`	Cancel a compiler job and discard any delayed result.
`GET`	`/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readiness`	Read authoritative readiness for an operation; pass `operation=generate`, `sync_resources`, or `publish`.
`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. Jobs that provide definition_id are bound to its current immutable version; definition_version_id, when supplied, must match that version. Only version-bound compile jobs persist readiness evidence. Use readiness_operation=publish for the validation shown before publication.

{
  "mode": "compile",
  "spec": {},
  "definition_id": "definition-uuid",
  "definition_version_id": "version-uuid",
  "readiness_operation": "publish"
}

The readiness response is bound to the current definition version and target. Its status is one of ready, blocked, not_validated, stale, or unsupported; blockers and ordered checks explain the next action. Older jobs remain audit evidence but cannot replace the active result for a newer version, target, or validation-policy version.

Validation reports retain their existing section shape. A section marked passed was either executed successfully or was explicitly not applicable. When a requested phase cannot run because a prerequisite failed, its status is skipped and the prerequisite reason is included in its summary or diagnostic. Publication treats warnings and skipped sections as blockers.

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, stale validation repair target or report hash, 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​

Managed API Connector Contracts​

Workspace And Settings Endpoints​

Create Workspace​

Definition And Version Endpoints​

Create Definition​

Graph And README Endpoints​

Add Node​

Replace Dependencies​

Update README​

Publish Definition​

Durable Publication And Resource Sync​

Draft File Endpoints​

Save Draft File​

Context, Autocomplete, And Clarifications​

Chat And Agent Job Endpoints​

Chat Request​

Targeted Repair Request​

Incremental Job Polling​

Compiler, Validation, And Deployment Endpoints​

Repo Edit Session And Audit Endpoints​

Error Notes​

Related​