Skip to main content

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. Credentialless contract invocation, global egress-profile administration, and exact API write grants are documented separately in Authoring API Egress.

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.

MethodEndpointDescription
GET/connectors/spaces/{space_slug}/{connector_id}/api-contractRead the active normalized contract snapshot, or null when none is active.
PUT/connectors/spaces/{space_slug}/{connector_id}/api-contractActivate a reviewed manual or repository-file normalized contract.
POST/connectors/spaces/{space_slug}/{connector_id}/api-contract/refreshExplicitly fetch, normalize, hash, and activate the configured remote definition.
POST/connectors/spaces/{space_slug}/{connector_id}/testValidate connector configuration, compatible credentials, and contract access without invoking write operations.
POST/connectors/spaces/{space_slug}/{connector_id}/authoring-api-grantsIssue one exact, expiring write or destructive-operation grant.
DELETE/connectors/spaces/{space_slug}/{connector_id}/authoring-api-grants/{grant_id}Revoke a still-pending API operation grant.

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​

MethodEndpointDescription
GET/spaces/{space_slug}/pipeline-authoring/workspacesList Pipeline Authoring workspaces in the space.
POST/spaces/{space_slug}/pipeline-authoring/workspacesCreate 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}/accessRead workspace access settings.
PUT/spaces/{space_slug}/pipeline-authoring/workspaces/{workspace_id}/accessReplace workspace access settings.
POST/spaces/{space_slug}/pipeline-authoring/workspaces/{workspace_id}/archiveArchive a workspace.
GET/spaces/{space_slug}/pipeline-authoring/settingsRead the current user's Pipeline Authoring defaults.
PATCH/spaces/{space_slug}/pipeline-authoring/settingsUpdate 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​

MethodEndpointDescription
GET/spaces/{space_slug}/pipeline-authoring/definitionsList pipeline definitions.
POST/spaces/{space_slug}/pipeline-authoring/definitionsCreate 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}/readinessRead 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}/versionsList saved definition versions.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/versions/{version_id}/compareCompare a saved version with the current definition.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/versions/{version_id}/restoreRestore a saved version.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/archiveArchive a definition.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publishPublish reviewed files to the configured repository.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/deployment-artifactsList immutable Airflow packaged-DAG artifacts.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/deployment-artifacts/{artifact_id}/downloadDownload 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​

MethodEndpointDescription
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/nodesList 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}/nodesAdd 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}/dependenciesList spec.edges using public dependency terminology.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/dependenciesAdd one dependency edge.
DELETE/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/dependenciesRemove one dependency edge.
PUT/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/dependenciesReplace all dependency edges.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readmeResolve and read the DAG README resource.
PUT/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readmeCreate or update the DAG README through the draft-file overlay.
DELETE/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readmeDelete 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 permits only one non-production exception: when the gate mode is not block, the exact failure set may contain only validation_section_sandbox_skipped. It does not bypass block mode or excuse any other failed, warned, missing, or skipped section.

Passing section statuses are necessary but not sufficient. Publication also requires a passing trusted-verification parent bound to the exact candidate and spec. When the candidate contains executable Python, the canonical server-side behavioral resolution must authorize the matching trusted record. Candidate exit codes, JUnit payloads, and output are observations only; support-test evidence is authoritative only after independent dependency-backed, sandbox, or other platform-controlled verification.

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.

MethodEndpointDescription
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publication-operationsCreate or recover an idempotent publication operation.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publication-operationsList 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}/cancelCancel before the first Git mutation.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/publication-operations/{operation_id}/retryCreate an audited child attempt.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/resource-sync-runsCreate or recover an idempotent managed-resource sync.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/resource-sync-runsList 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}/cancelStop before the next resource mutation while retaining completed items.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/resource-sync-runs/{run_id}/retryRetry 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​

MethodEndpointDescription
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/treeList the draft file tree.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/searchSearch draft files.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/filesRead one draft file by path.
PUT/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/filesCreate or update a draft file.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/uploadsUpload one or more draft files.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/renameRename one draft file.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/moveMove one or more draft files.
DELETE/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/filesDelete one draft file.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/files/reset-overrideReset 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.

File reads expose protected_actions for compiler-owned generated paths, including the primary artifact, canonical spec, generated unit test, generated package initializers, selected requirements manifest, support files, and support tests. Those paths cannot be moved or deleted directly, and a move cannot target one. Use the supported draft or owning spec operation instead; command approval does not override compiler ownership.

This compiler-ownership rule is distinct from sensitive-artifact policy. Workspace mutations to protected CI, CODEOWNERS, hook, Docker, build, script, and shell paths require a server-generated protected_workspace_file approval. Its fingerprint binds repository_id, repository_ref, target, base definition_version_id, result spec_fingerprint, approved_plan_hash, path, create/update/delete operation, exact content SHA-256 or stable deletion tombstone SHA-256, expected_base_sha, and policy_version. Publication recomputes those inputs; any drift invalidates the approval before Git mutation.

Paths in .git or credential/secrets directories, non-template .env and credential files, and private-key or certificate material are blocked, not approval-gated. They cannot be made publishable by either sensitive-artifact or repository-command approval.

Context, Autocomplete, And Clarifications​

MethodEndpointDescription
GET/spaces/{space_slug}/pipeline-authoring/contextRead the authoring context bundle for the space.
POST/spaces/{space_slug}/pipeline-authoring/editor/completionsRequest repository-aware editor completions.
GET/spaces/{space_slug}/pipeline-authoring/clarifications/contextRead available clarification context.
POST/spaces/{space_slug}/pipeline-authoring/clarifications/credentialsStore credential answers for a clarification flow.
POST/spaces/{space_slug}/pipeline-authoring/clarifications/schema-previewPreview schema details needed by a clarification.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/clarifications/historyList clarification history for a definition.
PUT/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/interactions/{interaction_id}/answersAtomically replace a native interaction's complete answer batch using an expected revision.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/clarifications/stateSave clarification state.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/clarifications/activityRecord 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​

MethodEndpointDescription
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chatSend a synchronous authoring message.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/messagesList authoring conversation messages.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/streamStream an authoring response as server-sent events.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/jobsStart an asynchronous authoring job.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/jobs/activeRead the active job for the definition, if any.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/chat/decisions/{decision_request_id}/jobFind 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}/cancelCancel an authoring job.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/external-research/{interaction_id}/decisionApprove or decline the durable public-research grant and, when approved, queue its continuation.

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, repair_ledger, and typed recovery_actions. Persisted message reads and chat-job status can also expose the additive run_projection described below. The string next_actions field remains available during the compatibility migration. chat/stream returns text/event-stream.

Plan-review generation_readiness.status uses its own enum: not_applicable, ready, blocked, failed_validation, reviewable_with_warnings, or environment_blocked. Do not combine it with the immutable operation-readiness enum returned by /readiness, which is ready, blocked, not_validated, stale, or unsupported.

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, an optional versioned acceptance_contract, evidence requirements, runtime-resource bindings, 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.

Execution-unit acceptance contracts​

Fresh executable plans use acceptance_contract.version: 1 with one to 40 discriminated requirements. Unknown fields are rejected. The requirement kinds cover:

  • Exact spec metadata, node, edge, and external-link effects.
  • Workspace file effects, including the expected current SHA-256 for updates, removals, and refactors.
  • Deployment requirements and typed runtime-resource locators.
  • Python exports, imports, callable signatures, provider/member calls, and independently checked callable behavior.
  • Support-test imports, exact patch sets, required patch targets, and forbidden patch targets.

For example, one reviewed callable can bind its public shape and behavior to the same unit:

{
  "acceptance_contract": {
    "version": 1,
    "requirements": [
      {
        "kind": "python_callable",
        "path": "pipelines/orders.py",
        "name": "load_orders",
        "required_parameters": ["source_uri"],
        "optional_parameters": ["limit"],
        "exact_parameters": true,
        "accepts_kwargs": false
      },
      {
        "kind": "python_callable_behavior",
        "version": 1,
        "path": "pipelines/orders.py",
        "name": "load_orders",
        "callable_mode": "sync",
        "cases": [
          {
            "id": "empty-source",
            "args": [""],
            "kwargs": {},
            "expectation": {
              "kind": "raises",
              "exception_type": "ValueError"
            }
          }
        ]
      }
    ]
  }
}

Behavior cases accept bounded JSON arguments and keyword arguments. Each case expects either an exact JSON return (kind: "return") or an allowlisted built-in exception (kind: "raises"). Behavioral execution is independently validated, repeated to detect nondeterminism, and identity-bound to the reviewed callable and candidate. Expectations remain on the trusted host; they are not sent to the candidate runtime as assertions.

Runtime-resource bindings are also reviewed inputs. For managed S3 and Postgres resources, the planner aligns generated contracts with the governed Airflow hook surface and the corresponding support-test patch target. Unknown, ambiguous, or unrelated raw-client calls remain validation errors. Narrow revisions preserve unnamed units and omitted keys from matching reviewed behavior cases, then run the complete graph, acceptance, resource, and feasibility gates again.

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.

When a decomposition plan is awaiting review, an ordinary message can be interpreted against that exact plan revision. Clear whole-plan approval, cancellation, or revision instructions apply the bound decision. A question can return a plan-grounded answer while leaving the review pending. Ambiguous, low-confidence, unrelated, or new requests preserve the pending plan and ask the client to use or clarify the review controls. This interpretation is not used for implementation authorization or repository-command approval.

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.

The external-research decision endpoint accepts only the durable interaction created for the current definition and root task:

{
  "decision": "approve"
}

decision is approve or decline. Approval returns the task grant and queues the exact stored continuation when needed:

{
  "grant_id": "grant-uuid",
  "status": "approved",
  "expires_at": "2026-08-21T12:00:00Z",
  "searches_consumed": 0,
  "searches_remaining": 6,
  "continuation_job_id": "job-uuid",
  "continuation_status": "queued"
}

Consent status is approved, declined, expired, or revoked; continuation_status is queued or not_requested. One approved grant covers at most six distinct searches with up to eight normalized results each for the same user, space, definition, root request, and provider binding. Identical queries reuse durable evidence. Provider-binding drift, revoked access, unsafe queries, no-progress repetition, quota exhaustion, and post-approval research fail closed rather than selecting another provider or inventing evidence.

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, repair_ledger, execution_unit_states, recovery_actions, narrative_events, narrative_omitted_count, and run_projection directly, including while the job is active. execution_unit_states includes dependencies, evidence and action references, and blocked reasons.

run_projection is the canonical public read model for both the live job and its persisted assistant turn. Its display_status is queued, running, recovering, needs_input, needs_review, succeeded, failed, or cancelled; liveness is healthy, delayed, recovering, or stalled. It also carries the raw job status, job and source-message identities, elapsed duration, bounded activity, omission count, budget state, failure kind, and up to ten recovery actions. Parent terminal state takes precedence over stale child activity, so a settled projection never contains a running activity item. Clients should key turns by run_projection.job_id and prefer this object over re-deriving display state from message text or legacy activity snapshots.

The additive repair_ledger has schema version 1, up to 100 ordered entries, and an omitted_count. Entries have stable IDs and sequences plus stage, semantic/provider layer, route, trigger, status, attempt bounds, optional parent attempt, execution-unit and diagnostic identities, bounded affected paths, approval requirement, and authorized AI-log references. Stages are structured_output, decomposition, generation, validation, and diff_review. The ledger deliberately excludes prompts, generated code, provider bodies, raw diagnostics, and detected secret values. Older jobs and messages may omit both additive objects; clients must retain their existing compatibility projection for those records.

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 v5 for the same durable transcript; readers must continue accepting v1-v4 snapshots and derive the compatibility presentation when newer additive fields are absent.

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​

MethodEndpointDescription
GET/spaces/{space_slug}/pipeline-authoring/node-catalogList supported pipeline node types and options.
POST/spaces/{space_slug}/pipeline-authoring/compiler/validateValidate a pipeline authoring spec.
POST/spaces/{space_slug}/pipeline-authoring/compiler/compileCompile a pipeline authoring spec.
POST/spaces/{space_slug}/pipeline-authoring/compiler/jobsStart 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}/cancelCancel a compiler job and discard any delayed result.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/readinessRead authoritative readiness for an operation; pass operation=generate, sync_resources, or publish.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/deployment-resourcesPreview deployment resources needed by a definition.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/deployment-resources/syncSync 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​

MethodEndpointDescription
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessionsList repo edit sessions for a definition.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/activeRead 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}/eventsList repo edit session events.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/pending-changesRead pending generated-file changes.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/resumeResume a paused repo edit session.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/retryRetry a repo edit session from a selected point.
POST/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/repo-edit-sessions/{session_id}/cancelCancel a repo edit session.
GET/spaces/{space_slug}/pipeline-authoring/definitions/{definition_id}/audit-historyList 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.

Repository-command approvals are matched by an exact fingerprint over the command identifier, argv, purpose, timeout, working directory, bounded paths, repository identity, prepared-edit identifiers, profile and test-runner metadata, workspace fingerprint, runtime image digest, and network request and policy hash. A change to any bound field produces a different request and invalidates the prior approval. Shell and command-forwarding executables such as bash, sh, and zsh are not valid registered command profiles; an authored bash_command node is pipeline runtime content and never grants authoring-time shell authority.

Authored Bash has a separate bash_command sensitive-artifact contract. When the Bash classifier returns approval_required, the server-generated request binds repository and ref, target, base definition version, result spec fingerprint, approved-plan hash, node ID, the exact command SHA-256, sorted detected capabilities, the execute operation, and Bash policy version. Changing the node, command, capabilities, version, plan, target, repository, or policy invalidates the approval. Commands classified as blocked are never approvable.

Error Notes​

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