Template Catalog

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Templates are bundled seed patterns that create a draft release, a flow asset, supporting governed assets, and optionally a trigger binding in one operation.

What templates expose today

Templates are not arbitrary user-authored packages yet. The current API serves a bundled catalog with typed metadata.

Catalog reads require authentication. Applying a template requires TEMPLATE_MANAGE on the target workload’s workspace because apply creates governed assets, immutable asset versions, release bindings, and sometimes a managed trigger.

Template catalog fields

Field	Description
`slug`	Unique template identifier
`display_name`	Human-readable template name
`description`	Short summary of the workload pattern
`category`	Template category such as `knowledge`, `ops`, or `approval`
`tags`	Free-form discovery tags
`trigger_type`	Trigger type declared by the template flow
`step_types`	Step types used in the bundled flow
`asset_stub_kinds`	Asset kinds the template will create
`smoke_tested`	Whether the bundled template is covered by smoke-style apply validation
`has_governance_packs`	Whether the template advertises any optional governance control packs
`governance_pack_count`	Number of advertised governance control packs (`0` for most templates)

Template detail fields

The detail endpoint adds:

Field	Description
`readme_markdown`	Renderable template documentation
`flow_content`	Parsed orchestration flow definition
`asset_stubs`	Asset stubs that will be materialized on apply
`trigger_binding`	Optional managed trigger definition bundled with the template
`governance_control_packs`	Advertised optional governance control packs (advisory; opt-in at apply)

Example templates

Common bundled patterns include:

rag-knowledge-qa
document-summarization
scheduled-executive-report
webhook-to-slack-alert
approval-workflow

The exact list depends on the bundled catalog in your deployment.

You can filter the catalog by search, category, tag, or step_type. Filtering is additive: a request such as /v1/templates?category=knowledge&step_type=retrieval returns knowledge templates that also contain retrieval steps.

Applying a template

Template apply is intentionally narrow in the current implementation.

The request body supports:

Field	Required	Description
`workload_id`	Yes	Target workload that receives the new draft release
`environment`	No	Target environment. Defaults to `dev`
`instance_name`	No	Optional suffix/prefix input used to derive generated resource names

There is no general-purpose overrides payload in the current public template API.

Apply performs these operations as one governed workflow:

Load the target workload and verify it belongs to a workspace.
Check TEMPLATE_MANAGE for that workspace.
Record template.apply_attempted in governance audit.
Create a draft release for the requested environment.
Create the bundled flow asset and supporting asset stubs.
Persist JSON asset content to object storage and create immutable versions.
Bind created versions to the draft release with the roles declared by the template.
Create the managed trigger binding when the template includes one.
Record template.applied with created asset/version/binding counts.

If audit recording after instantiation fails, the API attempts to delete the created object-store artifacts and surfaces the failure instead of silently leaving an unaudited template application.

Apply request


curl -X POST http://localhost:8000/v1/templates/rag-knowledge-qa/apply \
  -H "Content-Type: application/json" \
  -d '{
    "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "environment": "dev",
    "instance_name": "support-docs"
  }'

Apply response


{
  "template_slug": "rag-knowledge-qa",
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "release": {
    "release_id": "r1a2b3c4-0000-0000-0000-000000000002",
    "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "environment": "dev",
    "state": "draft",
    "policy_bundle_id": null,
    "supersedes_release_id": null,
    "created_at": "2026-04-10T12:00:00Z",
    "created_by": "user:alice",
    "updated_at": "2026-04-10T12:00:00Z"
  },
  "flow": {
    "asset_id": "f1a2b3c4-0000-0000-0000-000000000001",
    "slug": "support-docs-rag-knowledge-qa",
    "asset_kind": "orchestration_flow",
    "owner_ref": "team:platform",
    "lifecycle_state": "active",
    "created_at": "2026-04-10T12:00:00Z",
    "created_by": "user:alice"
  },
  "created_assets": [
    {
      "asset_id": "a2b3c4d5-0000-0000-0000-000000000001",
      "slug": "support-docs-rag-knowledge-qa-model",
      "asset_kind": "model_policy",
      "owner_ref": "team:platform",
      "lifecycle_state": "active"
    }
  ],
  "created_versions": [
    {
      "asset_version_id": "v1a2b3c4-0000-0000-0000-000000000001",
      "asset_id": "a2b3c4d5-0000-0000-0000-000000000001",
      "version_label": "v1",
      "content": {
        "provider_route": {
          "route_id": "template-default",
          "provider": "your-provider",
          "model": "your-model",
          "account_slot": "template-primary",
          "region": "us-east-1",
          "residency": "us",
          "state": "approved",
          "sensitivity_tiers": ["public", "internal", "confidential"],
          "capability_tags": ["chat", "tool_use"],
          "cost_class": "standard",
          "guardrail_refs": ["guardrail:default-llm"],
          "prompt_caching": "allowed",
          "logging": "redacted"
        },
        "fallback_routes": []
      }
    }
  ],
  "bindings": [
    {
      "binding_id": "b1a2b3c4-0000-0000-0000-000000000001",
      "release_id": "r1a2b3c4-0000-0000-0000-000000000002",
      "asset_version_id": "v1a2b3c4-0000-0000-0000-000000000001",
      "role": "model_policy"
    }
  ],
  "trigger_binding": null
}

Governance control packs

Some templates advertise optional governance control packs — advisory metadata that maps the template to bounded control objectives. Packs are disabled by default and hidden from the default apply path; a template detail response lists what is available under governance_control_packs, and the summary fields has_governance_packs / governance_pack_count flag their presence.

A pack is opt-in at apply time. Enable one or more by pack_id:

API: add "enabled_control_packs": ["ai-systems-rag-readiness"] to the apply request body.
SDK: client.templates.apply(slug, workload_id=…, enabled_control_packs=[…]).
CLI: orqestractl template apply <slug> --workload <id> --enable-pack <pack_id> (repeatable). orqestractl template preview <slug> renders the available packs.

When at least one pack is enabled, the apply response carries an advisory governance_setup:

evidence_checklist — one item per pack evidence spec (key, label, evidence_source, control_family, regime-bound control_ids, the labeled cross-regime support_control_ids, and status: "open").
readiness_summary — counts by control family, the enabled frameworks, the advisory owner_default / reviewer_default responsibility-category hints (suggestions, never actor refs or auto-assignments), the review cadence, the recommended policy bundles split into configured vs recommended_absent (configured is computed from the bindings actually created at apply, never from the pack declaration), a distinct support_controls grouping, and a mandatory bounded-claim caveat.

These surfaces are advisory only (decision_mode: "advisory_signal"). A pack makes no runtime-enforcement claim and binds nothing; the checklist is a derived response artifact, not persisted evidence, and the readiness summary is not a certification or conformity claim. Counsel and auditors decide any external claim.

API reference

List templates


curl "http://localhost:8000/v1/templates?category=knowledge&tag=rag"

Example response:


[
  {
    "slug": "rag-knowledge-qa",
    "display_name": "RAG Knowledge Q&A",
    "description": "Retrieve governed context, then generate a grounded answer.",
    "category": "knowledge",
    "tags": ["rag", "grounded"],
    "trigger_type": "api_request",
    "step_types": ["llm_call", "return", "task"],
    "asset_stub_kinds": ["model_policy", "policy_bundle", "prompt_template", "knowledge_base"],
    "smoke_tested": true,
    "has_governance_packs": true,
    "governance_pack_count": 1
  }
]

Get template detail


curl http://localhost:8000/v1/templates/{slug}

Example response excerpt:


{
  "slug": "rag-knowledge-qa",
  "display_name": "RAG Knowledge Q&A",
  "description": "Retrieve governed context, then generate a grounded answer.",
  "category": "knowledge",
  "tags": ["rag", "grounded"],
  "trigger_type": "api_request",
  "step_types": ["llm_call", "return", "task"],
  "asset_stub_kinds": ["model_policy", "policy_bundle", "prompt_template", "knowledge_base"],
  "smoke_tested": true,
  "readme_markdown": "# RAG Knowledge Q&A\n\n...",
  "flow_content": {
    "name": "RAG Knowledge Q&A",
    "trigger": {
      "type": "api_request",
      "inputs_schema": {
        "question": "string"
      }
    },
    "entry_step": "retrieve_context",
    "steps": [
      {
        "id": "retrieve_context",
        "type": "task",
        "action": "retrieve_documents",
        "next": "generate_answer"
      }
    ]
  },
  "asset_stubs": [
    {
      "slug_suffix": "model",
      "asset_kind": "model_policy",
      "role": "model_policy",
      "description": "Governed model policy stub.",
      "version_label": "v1",
      "content": {
        "provider_route": {
          "route_id": "template-default",
          "provider": "your-provider",
          "model": "your-model",
          "account_slot": "template-primary",
          "region": "us-east-1",
          "residency": "us",
          "state": "approved",
          "sensitivity_tiers": ["public", "internal", "confidential"],
          "capability_tags": ["chat", "tool_use"],
          "cost_class": "standard",
          "guardrail_refs": ["guardrail:default-llm"],
          "prompt_caching": "allowed",
          "logging": "redacted"
        },
        "fallback_routes": []
      }
    }
  ],
  "trigger_binding": null
}

SDK usage


async with OrqestraClient(base_url=url, api_key=key) as client:
    templates = await client.templates.list(category="knowledge", step_type="retrieval")
    detail = await client.templates.get("rag-knowledge-qa")
    applied = await client.templates.apply(
        "rag-knowledge-qa",
        workload_id=workload_id,
        environment="dev",
        instance_name="support-docs",
        # Optional, opt-in: derives an advisory governance_setup in the response.
        enabled_control_packs=["ai-systems-rag-readiness"],
    )

Operator expectations

Applying a template currently gives you a strong starting point, not a finished production workload.

Operators should still:

Review the created flow and asset versions.
Confirm the generated release bindings.
Add approvals and move the release through review_ready -> approved -> active.
Customize generated assets where the template uses starter defaults.
Replace starter connection references with deployment-specific connection instances.
Run the release validation and evidence checks that apply to the workload’s environment.

Troubleshooting

Error	Likely cause
`Template not found`	The slug is not present in the bundled catalog
`Workload not found`	The target workload ID does not exist or has no workspace scope
`403` on apply	The actor lacks `TEMPLATE_MANAGE` on the target workspace
`422` on apply	The template instance name or generated content failed validation
Draft release exists but is not active	Template apply does not bypass release review, approval, or activation