API Basics

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

This guide covers the implemented Orqestra control-plane REST API: authentication, core resource operations, and the release flow that operators and developers use in practice.

Base URL and authentication

Base URL (development): http://localhost:8000

In local development, the control plane accepts requests without bearer authentication. In deployed environments, the control plane validates OIDC bearer tokens.


curl -H "Authorization: Bearer <your-token>" http://localhost:8000/v1/workloads

Health check


curl http://localhost:8000/healthz


{
  "status": "ok"
}

A note on workload identifiers

The workload routes still use the path placeholder {workload_id}:


/v1/workloads/{workload_id}

But workload and release payloads use the field name workload_id in JSON responses and release requests. The docs below follow that distinction explicitly.

List workloads

Retrieve all workloads:


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


[
  {
    "workload_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
    "slug": "customer-support-agent",
    "owner_ref": "team:platform",
    "status": "registered",
    "invocation_mode": "chat",
    "interface_config": null,
    "created_at": "2026-04-01T08:00:00Z",
    "created_by": "user:alice",
    "management_source": null
  }
]

management_source is null for an ordinary workload like this one, or "workspace_builtin" for the built-in knowledge assistant’s own workload — see the Workloads guide for what that means.

Optional filters:


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

Create an asset

Assets are the versioned building blocks that releases bind to workloads.


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


{
  "asset_id": "b2c3d4e5-6789-0abc-def1-234567890abc",
  "slug": "my-model-policy",
  "asset_kind": "model_policy",
  "owner_ref": "team:dev",
  "lifecycle_state": "active",
  "created_at": "2026-04-06T10:00:00Z",
  "created_by": "user:alice"
}

Common asset kinds

Kind	Description
`prompt_template`	Prompt templates and system instructions
`knowledge_base`	Governed source, retrieval tuning, and access contract
`model_policy`	Governed model routing and generation policy
`model_config`	Legacy routed model selection and generation parameters
`policy_bundle`	Governance rules and obligations
`tool_definition`	Tool configuration
`hook_definition`	Lifecycle hook definition
`mcp_server`	MCP server configuration
`skill`	Reusable capability definitions
`agent`	Agent configuration
`orchestration_flow`	Flow definitions used by triggers and releases
`memory`	Memory retention and recall settings
`guardrail_config`	Guardrail policy/config definitions

Create an asset version

Asset versions are immutable.


curl -X POST http://localhost:8000/v1/assets/b2c3d4e5-6789-0abc-def1-234567890abc/versions \
  -H "Content-Type: application/json" \
  -d '{
    "version_label": "v1",
    "content": {
      "provider_route": {
        "route_id": "your-provider-support-us",
        "provider": "your-provider",
        "model": "your-provider/your-model",
        "account_slot": "your-provider-prod",
        "region": "us-east-1",
        "residency": "us",
        "state": "approved",
        "sensitivity_tiers": ["public", "internal"],
        "capability_tags": ["chat", "tool_use"],
        "cost_class": "standard",
        "prompt_caching": "allowed",
        "logging": "redacted"
      },
      "fallback_routes": [],
      "supports_streaming": true,
      "supports_tool_use": true,
      "temperature": 0.2,
      "max_tokens": 800
    }
  }'


{
  "asset_version_id": "c3d4e5f6-7890-1abc-def2-34567890abcd",
  "asset_id": "b2c3d4e5-6789-0abc-def1-234567890abc",
  "version_label": "v1",
  "content": {
    "provider_route": {
      "route_id": "your-provider-support-us",
      "provider": "your-provider",
      "model": "your-provider/your-model",
      "account_slot": "your-provider-prod",
      "region": "us-east-1",
      "residency": "us",
      "state": "approved",
      "sensitivity_tiers": ["public", "internal"],
      "capability_tags": ["chat", "tool_use"],
      "cost_class": "standard",
      "prompt_caching": "allowed",
      "logging": "redacted"
    },
    "fallback_routes": [],
    "supports_streaming": true,
    "supports_tool_use": true,
    "temperature": 0.2,
    "max_tokens": 800
  },
  "artifact_ref": "assets/b2c3d4e5-6789-0abc-def1-234567890abc/c3d4e5f6-7890-1abc-def2-34567890abcd/content.json",
  "checksum": "sha256...",
  "created_at": "2026-04-06T10:05:00Z",
  "created_by": "user:alice"
}

Create a workload


curl -X POST http://localhost:8000/v1/workloads \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "customer-support-agent",
    "owner_ref": "team:platform",
    "invocation_mode": "chat"
  }'


{
  "workload_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
  "slug": "customer-support-agent",
  "owner_ref": "team:platform",
  "status": "registered",
  "invocation_mode": "chat",
  "interface_config": null,
  "created_at": "2026-04-06T10:08:00Z",
  "created_by": "user:alice"
}

Create a release and bind assets

Releases connect a workload (workload_id) to specific asset versions in a target environment.

Step 1: Create the release


curl -X POST http://localhost:8000/v1/releases \
  -H "Content-Type: application/json" \
  -d '{
    "workload_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
    "environment": "dev",
    "target_lane": "all"
  }'


{
  "release_id": "d4e5f6a7-8901-2bcd-ef34-567890abcdef",
  "workload_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
  "environment": "dev",
  "state": "draft",
  "policy_bundle_id": null,
  "supersedes_release_id": null,
  "created_at": "2026-04-06T10:10:00Z",
  "created_by": "user:alice",
  "updated_at": "2026-04-06T10:10:00Z"
}

Step 2: Bind an asset version


curl -X POST http://localhost:8000/v1/releases/d4e5f6a7-8901-2bcd-ef34-567890abcdef/bindings \
  -H "Content-Type: application/json" \
  -d '{
    "asset_version_id": "c3d4e5f6-7890-1abc-def2-34567890abcd",
    "role": "model_policy"
  }'


{
  "binding_id": "e5f6a7b8-9012-3cde-f456-7890abcdef01",
  "release_id": "d4e5f6a7-8901-2bcd-ef34-567890abcdef",
  "asset_version_id": "c3d4e5f6-7890-1abc-def2-34567890abcd",
  "role": "model_policy",
  "created_at": "2026-04-06T10:12:00Z",
  "created_by": "user:alice"
}

Step 3: Move the release through governance


# draft -> review_ready
curl -X POST http://localhost:8000/v1/releases/d4e5f6a7-8901-2bcd-ef34-567890abcdef/transition \
  -H "Content-Type: application/json" \
  -d '{"to_state": "review_ready"}'
 
# record at least one approval
curl -X POST http://localhost:8000/v1/releases/d4e5f6a7-8901-2bcd-ef34-567890abcdef/approvals \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "approved",
    "subject_kind": "release",
    "subject_ref": "d4e5f6a7-8901-2bcd-ef34-567890abcdef"
  }'
 
# review_ready -> approved
curl -X POST http://localhost:8000/v1/releases/d4e5f6a7-8901-2bcd-ef34-567890abcdef/transition \
  -H "Content-Type: application/json" \
  -d '{"to_state": "approved"}'
 
# approved -> active
curl -X POST http://localhost:8000/v1/releases/d4e5f6a7-8901-2bcd-ef34-567890abcdef/transition \
  -H "Content-Type: application/json" \
  -d '{"to_state": "active"}'

approved -> active also requires a policy_bundle binding. A model_policy binding is required when the bound flow uses provider-routed steps such as llm_call, agent, or embedding; legacy releases may continue to bind model_config.

Step 4: Verify the release


curl http://localhost:8000/v1/releases/d4e5f6a7-8901-2bcd-ef34-567890abcdef


{
  "release_id": "d4e5f6a7-8901-2bcd-ef34-567890abcdef",
  "workload_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
  "environment": "dev",
  "state": "approved",
  "policy_bundle_id": null,
  "supersedes_release_id": null,
  "bindings": [
    {
      "binding_id": "e5f6a7b8-9012-3cde-f456-7890abcdef01",
      "release_id": "d4e5f6a7-8901-2bcd-ef34-567890abcdef",
      "asset_version_id": "c3d4e5f6-7890-1abc-def2-34567890abcd",
      "role": "model_policy",
      "created_at": "2026-04-06T10:12:00Z",
      "created_by": "user:alice"
    }
  ],
  "valid_transitions": ["active", "retired"],
  "created_at": "2026-04-06T10:10:00Z",
  "created_by": "user:alice",
  "updated_at": "2026-04-06T10:15:00Z"
}

List responses and filtering

Most list endpoints currently return raw arrays, not paginated envelopes:

GET /v1/workloads
GET /v1/assets
GET /v1/releases
GET /v1/flows
GET /v1/workloads/{workload_id}/releases

Tenant listing is the main exception and supports limit and offset.

Error responses

The API returns structured errors with consistent HTTP status codes.

Status	Meaning	When it occurs
`400`	Bad Request	Malformed JSON, invalid asset content, or invalid flow structure
`404`	Not Found	Resource does not exist
`409`	Conflict	Duplicate slug or invalid state transition
`422`	Validation Error	Activation prerequisites or approval gates not satisfied
`500`	Internal Server Error	Unexpected server failure

An invalid transition response is structured:


{
  "detail": {
    "error": "invalid_transition",
    "current_state": "draft",
    "valid_transitions": ["review_ready"]
  }
}

An approval-gate failure is also structured:


{
  "detail": {
    "error": "approval_required",
    "message": "At least one approval record is required before transitioning to approved"
  }
}

Next steps

SDK Quickstart — Build and register flows with the Python SDK
Local Dev Setup — Run the full stack locally