Assets

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

Assets are the versioned configuration objects that releases bind to workloads. They are the core governance unit for prompts, models, policies, flows, knowledge sources, and related execution settings.

Asset fields

The lifecycle is draft, active, retired, or archived. Use the workspace-scoped archive action from the asset detail page, SDK, CLI, or MCP tool. It requires ASSET_EDIT, retains version history, and returns a conflict with visible blocking releases while any version is bound by a draft, review-ready, approved, or active release. Archiving is terminal.

Workspace-scoped assets carry workspace_id; namespace-scoped visibility is derived from the workspace’s namespace when the asset is created. Platform built-ins are explicitly marked with the global built-in ownership tier. Do not infer global visibility from a missing workspace alone.

Current asset kinds

knowledge_base versions must include an access_contract. The contract is deny-by-default and names the principals, groups, workspaces, and access modes that may retrieve from that corpus. Retrieval strategy, top_k, chunk sizing, thresholds, filters, and related retrieval controls live in the same knowledge_base.content.retrieval object so the runtime can enforce access checks before adding retrieved context to model calls. Revoking or malformed contracts fail closed before retrieval and disable runtime memory replay/writeback for that execution.

Version fields

Versioning model

Asset versions are immutable. To change a prompt, model, policy, or flow, create a new version and bind that version in a new release.

That is what makes:

• release review meaningful
• rollback possible
• audit reconstruction precise

orqestractl sync respects that model without requiring source-authored version labels. It compares declared content by canonical JSON hash, reuses an identical live version when one exists, and creates a new immutable version when content changes. The control plane assigns the next internal version label.

Validation and storage

Creating a version validates the payload against the JSON schema for the asset kind and then applies business rules for governed content. Examples include provider-route checks for model_policy, deny-by-default access contracts for knowledge_base, and flow schema checks for orchestration_flow.

The version payload is checksummed with canonical JSON and persisted through the object-store interface at assets/{asset_id}/{asset_version_id}/content.json. The database row keeps the same content, checksum, and artifact reference so the control plane can serve fast API reads while still preserving an external artifact trail.

Governed builders

Professional asset builders keep authoring, readiness, preview, evaluation linkage, and version creation in one governed path. Agent Builder is the first kind-specific builder: its rail shows readiness checks, prompt preview results, saved-asset evaluation session context, and save/version readiness beside the authoring canvas.

When Agent Builder is embedded in the Create Asset flow, the page still exposes a single primary Create action. That action delegates to the builder save lifecycle, so schema validation, dirty-state gating, and version creation remain owned by the builder. Evaluation-suite promotion is only available for saved, clean agent content; an unsaved draft does not request saved-asset evaluation sessions.

AI-assisted prompt drafts

POST /v1/asset-drafts/generate?workspace_id={workspace_id} drafts a prompt_template without saving it. The caller must hold ASSET_CREATE in the target workspace — no principal binding of your own on the built-in platform generator is required, because the generator runs under its own system credential, provisioned automatically at startup. Orqestra resolves the generator’s active production release server-side, runs it through the governed runtime, validates the returned JSON, and only then returns draft_content for review.

Generation is synchronous because the draft is the response. A generator with no active production release, or one that is not fully provisioned, returns 503; missing ASSET_CREATE on the target workspace or a runtime policy denial returns 403; and queued-only dispatch returns the typed 409 inline_dispatch_unavailable. The route creates no asset or version.

Scope and permissions

Share grants can make an asset visible to another namespace. The read path still checks that the actor can view at least one workspace in the target namespace before returning the shared asset.

API reference

Base URL: http://localhost:8000

Create an asset

curl -X POST http://localhost:8000/v1/assets \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-system-prompt",
    "asset_kind": "prompt_template",
    "owner_ref": "team:my-team"
  }'

{
  "asset_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "slug": "my-system-prompt",
  "asset_kind": "prompt_template",
  "owner_ref": "team:my-team",
  "lifecycle_state": "active",
  "created_at": "2026-04-06T12:00:00Z",
  "created_by": "user:alice"
}

List assets

curl "http://localhost:8000/v1/assets?workspace_id=$WORKSPACE_ID&asset_kind=prompt_template"

The endpoint returns a JSON array.

Create a version

curl -X POST http://localhost:8000/v1/assets/{asset_id}/versions \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "system_prompt": "You are a helpful assistant for {{team_name}}."
    }
  }'

{
  "asset_version_id": "e5f6a7b8-0000-0000-0000-000000000001",
  "asset_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "version_label": "v1",
  "content": {
    "system_prompt": "You are a helpful assistant for {{team_name}}."
  },
  "artifact_ref": "assets/...",
  "checksum": "sha256...",
  "created_at": "2026-04-06T12:01:00Z",
  "created_by": "user:alice"
}

Prompt template grammar

A prompt_template system_prompt may layer a governed grammar over the legacy {{variable}} placeholders. Templates without grammar tokens render exactly as before.

The variables array gains an optional per-variable type (string | number | boolean | array, default string), and the template gains an optional top-level allowed_commands string array:

{
  "content": {
    "system_prompt": "Greet $arg:audience using @asset-ref:tone-guide, then !command:run_query.",
    "variables": [{ "name": "audience", "description": "Who to greet", "type": "string" }],
    "allowed_commands": ["run_query"]
  }
}

Resolution is fail closed and errors are value-free (they never echo the offending template text). A cross-workspace or missing @asset-ref, a nested @asset-ref (an asset body that itself references another asset), or a malformed token is rejected with a bounded 422; a !command slug outside allowed_commands or a $arg value that does not match its declared type fails the render closed (never a silent pass).

List versions

curl "http://localhost:8000/v1/assets/{asset_id}/versions?workspace_id=$WORKSPACE_ID"

Inspect blast radius

Before changing a shared asset, inspect which releases and workloads already bind versions of that asset:

curl "http://localhost:8000/v1/assets/{asset_id}/blast-radius"

The blast-radius response is also exposed by the SDK:

impact = await client.assets.blast_radius(asset_id)

Use this before creating a replacement version for a heavily shared model, policy, prompt, or knowledge base.

Troubleshooting

Related guides

• Releases
• Flows
• Policies
• Models
• Knowledge Entitlements