Workloads

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

A workload is the top-level governed runtime boundary in Orqestra. Releases, lane bindings, principal bindings, executions, and consumer interfaces all hang off the workload.

Workload identity

The API route prefix is still:

/v1/workloads/{workload_id}

But workload payloads use the field name workload_id.

Workload fields

Guided onboarding metadata

The portal’s new workload flow includes copilot guidance for builder onboarding, operator handoff, and bounded connector setup posture. The guidance is review-only: it records workload setup intent in interface_config and does not enable connector access or apply production release changes by itself.

Common guided-intake keys in interface_config:

Status lifecycle

registered <-> suspended -> retired

status is a LIFECYCLE fact only — registered means the workload exists and is not suspended/retired; it makes no claim that the workload can actually run. Runtime READINESS is a separate, derived projection (ready or blocked with typed reasons: no invocation mode, no bound service lane, no active release, an unfulfilled human-oversight or connection-binding handoff), returned by:

curl http://localhost:8000/v1/workloads/{workload_id}/readiness

{
  "status": "blocked",
  "blockers": [
    {
      "kind": "service_lane_unbound",
      "detail": "No effective service-lane binding.",
      "target_ref": null
    }
  ]
}

A registered workload can still be blocked; trigger-binding admission (and runtime dispatch) requires registered lifecycle AND ready readiness — never lifecycle alone. Suspending a workload prevents new traffic, but does not delete releases, bindings, or evidence.

Service lane bindings

Lane bindings let operators describe how a workload should be served at runtime.

Lane binding fields

Principal bindings

Principal bindings govern who may interact with or operate a workload.

Principal binding fields

Access modes

API reference

Base URL: http://localhost:8000

Create a workload

curl -X POST http://localhost:8000/v1/workloads \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-knowledge-assistant",
    "display_name": "My Knowledge Assistant",
    "description": "Retrieval-grounded assistant for governed workspace knowledge.",
    "owner_ref": "team:my-team",
    "invocation_mode": "chat",
    "interface_config": {
      "flow_slug": "knowledge-qa",
      "domain": "knowledge",
      "system_of_record": "docs",
      "service_lane": "standard",
      "desired_release_lane": "staged",
      "human_decision_required": false,
      "pii_classification": "internal",
      "source_repo": "knowledge-assistant",
      "workload_intent": "Answer governed workspace questions.",
      "target_audience": "Operations reviewers",
      "expected_tools": "Knowledge retrieval, evidence lookup",
      "provider_preference": "Region-pinned provider",
      "connector_activation": {
        "family": "source_repository",
        "requested_scopes": "repo:read",
        "callback_url": "https://example.com/oauth/callback",
        "webhook_posture": "review_required",
        "endpoint_posture": "managed_endpoint",
        "workspace_access": "workspace:operations",
        "release_context_requirements": "Release must pin workspace and source repository.",
        "evidence_receipt_status": "draft_receipt"
      }
    }
  }'

{
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "slug": "my-knowledge-assistant",
  "display_name": "My Knowledge Assistant",
  "description": "Retrieval-grounded assistant for governed workspace knowledge.",
  "owner_ref": "team:my-team",
  "status": "registered",
  "invocation_mode": "chat",
  "interface_config": {
    "flow_slug": "knowledge-qa",
    "domain": "knowledge",
    "system_of_record": "docs",
    "service_lane": "standard",
    "desired_release_lane": "staged",
    "human_decision_required": false,
    "pii_classification": "internal",
    "source_repo": "knowledge-assistant",
    "workload_intent": "Answer governed workspace questions.",
    "target_audience": "Operations reviewers",
    "expected_tools": "Knowledge retrieval, evidence lookup",
    "provider_preference": "Region-pinned provider",
    "connector_activation": {
      "family": "source_repository",
      "requested_scopes": "repo:read",
      "callback_url": "https://example.com/oauth/callback",
      "webhook_posture": "review_required",
      "endpoint_posture": "managed_endpoint",
      "workspace_access": "workspace:operations",
      "release_context_requirements": "Release must pin workspace and source repository.",
      "evidence_receipt_status": "draft_receipt"
    }
  },
  "created_at": "2026-04-06T12:00:00Z",
  "created_by": "user:alice"
}

List workloads

curl http://localhost:8000/v1/workloads

Optional filters:

curl "http://localhost:8000/v1/workloads?status=registered"
curl "http://localhost:8000/v1/workloads?workspace_id=<workspace-id>"

The endpoint returns a JSON array of workload objects, unfiltered — a workspace_builtin-managed workload (the built-in knowledge assistant’s own workload) stays in the response at its existing metadata-only summary level, like every other list route. Each object’s management_source field reports its ownership: null for an ordinary workload, "workspace_builtin" for a managed one. A caller that needs to identify or exclude a managed row — declarative sync’s diff, for example — partitions on this field client-side.

Get a workload

curl http://localhost:8000/v1/workloads/{workload_id}

Update a workload

curl -X PATCH http://localhost:8000/v1/workloads/{workload_id} \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended"
  }'

Mutable fields:

List releases for a workload

curl "http://localhost:8000/v1/workloads/{workload_id}/releases?environment=production"

Optional filters:

Get the active release

This endpoint requires an environment query parameter.

curl "http://localhost:8000/v1/workloads/{workload_id}/active-release?environment=production"

{
  "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "environment": "production",
  "state": "active",
  "policy_bundle_id": null,
  "supersedes_release_id": null,
  "created_at": "2026-04-06T12:00:00Z",
  "created_by": "user:alice",
  "updated_at": "2026-04-06T12:05:00Z",
  "bindings": [
    {
      "binding_id": "b1a2b3c4-0000-0000-0000-000000000001",
      "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
      "asset_version_id": "e5f6a7b8-0000-0000-0000-000000000001",
      "role": "model_policy",
      "created_at": "2026-04-06T12:01:00Z",
      "created_by": "user:alice"
    }
  ],
  "valid_transitions": ["retired", "superseded"]
}

Create a lane binding

curl -X POST http://localhost:8000/v1/workloads/{workload_id}/lane-bindings \
  -H "Content-Type: application/json" \
  -d '{
    "lane": "default",
    "reason": "Standard serving lane"
  }'

{
  "binding_id": "lb1a2b3c-0000-0000-0000-000000000001",
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "lane": "default",
  "reason": "Standard serving lane",
  "effective_from": "2026-04-06T12:00:00Z",
  "created_at": "2026-04-06T12:00:00Z",
  "created_by": "user:alice"
}

List lane bindings

curl http://localhost:8000/v1/workloads/{workload_id}/lane-bindings

Lane posture and relaxation

Service lanes are ordered by governance rigor: standard < guided < restricted. Assigning a workload to a strictly lower lane than the posture it already carries — the active binding’s lane, or the most-recently-terminal binding’s lane when none is active — is a relaxation, and a relaxation is refused with 409 lane_relaxation_blocked_by_reachable_release while any release on the workload is in the active, approved, or superseded state. Those are exactly the states that can still reach active without a fresh approval, so they pin the posture the workload was governed under.

The honest remediation path is to clear that set first:

1. Retire rollback-eligible superseded releases (the superseded → retired transition, gated on the release-rollback permission).
2. Transition the active/approved releases to retired via revocation (revocation can land in superseded — retire those rows too; a retired release is the only terminal state that no longer blocks). The workload is out of service until a new release is activated — that downtime is the cost of the posture change, never silent.
3. Re-assign the lane once no release remains in active, approved, or superseded.

Publishing a new release alone does not change the lane binding: a new release is the governed path to new content reviewed under the current posture, never to changing the binding.

Two boundaries to know:

• Fail-closed predicate: the gate reads any gate-state release on the workload across every lane, so a release active on a lane other than the destination lane also refuses the move. Over-refusal is the accepted, fail-closed reading.
• Exemptions: a byte-identical re-send of the active lane is a bounded reuse (not a refusal), idempotency-key replays return the stored result, the first-ever lane assignment is ungated, equal or tighter posture is never blocked, and platform-internal authorities (the bundle generator, managed provisioning) own their own posture transitions.

Every refusal is durably audited (lane_binding.relaxation_refused) with the reason code and the from/to lanes, so the posture history stays traceable.

Create a principal binding

curl -X POST http://localhost:8000/v1/workloads/{workload_id}/principal-bindings \
  -H "Content-Type: application/json" \
  -d '{
    "actor_type": "user",
    "actor_ref": "user:alice",
    "access_mode": "interactive",
    "scope_ref": null
  }'

{
  "binding_id": "pb1a2b3c-0000-0000-0000-000000000001",
  "workload_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "actor_type": "user",
  "actor_ref": "user:alice",
  "access_mode": "interactive",
  "scope_ref": null,
  "created_at": "2026-04-06T12:00:00Z",
  "created_by": "user:alice"
}

List principal bindings

curl http://localhost:8000/v1/workloads/{workload_id}/principal-bindings

Related guides

• Releases
• Policies
• Triggers

Sandbox runtime authority

At runtime, the resolved sandbox remains authoritative for every execution path. Ordinary code_execution dispatch requires its dedicated capabilities.code_execution grant. Code-mode RPC and other ordinary task or agent plugins require tool use and tool allowance to be enabled, an exact plugin slug or declared tag in the sandbox family allowlist, and an effective side-effect class within the sandbox ceiling. Missing or malformed authority blocks before invocation and records a sandbox tool-authority evidence event. Raw URL task actions are treated as http_request operations with read_write side effects and must pass the same tool capability, allowance, family, and ceiling checks before an HTTP request is sent. Sandbox denial occurs before the task enters connection-secret resolution.