Workflow Types & Registry

Everything Orkestia can do is a workflow type — a registered, typed, versioned capability. The registry is the merged catalog of every type the platform knows about, assembled at boot from the libraries installed in your environment. This page explains how that catalog is organized and how you browse it. It does not enumerate individual workflows — the authoritative, always-current per-workflow reference lives at reference.orkestia.dev.

How the registry is built

The engine has no hand-maintained list of workflows. Each library declares its workflows through a plugin entry point; at boot, the engine discovers every entry point across every installed library and merges them into a single workflow index — the runtime registry that all surfaces (REST API, MCP, SDKs, dashboard) read from.

This matters for two reasons:

• Capabilities are additive. Installing a new library makes its namespace appear in discovery with no config change. The catalog you see reflects what is actually installed and registered, not a static document.
• Discovery is the source of truth. Always quote a workflow by the exact name discovery returns. Names are declared by the engine — never invent dotted variants, and refresh discovery before relying on a name.

Naming: dotted, namespaced, predictable

Every type has a dotted name. The canonical shape for an atomic workflow is:

{provider}.{service}.{operation}

So aws.s3.create_bucket is "create one S3 bucket on AWS" — a single, deterministic operation following the 3-state pattern (PENDING → COMPLETED | FAILED). Operation-segment style varies by library (the cloud ports use snake_case; some app libraries use kebab-case) — one more reason to quote names exactly as discovery returns them.

Higher-tier and app-scoped workflows group under a domain namespace instead of a provider — the first segment names the Orkestia app or business domain rather than a cloud:

Every type carries a typed contract

A registry entry is more than a name. Each type declares schemas the engine enforces, so bad input fails fast and outputs are a stable contract for downstream steps and callers. When you fetch a type's schema, the contract comes back as two flat arrays plus a set of capability flags:

Each entry in fields[] and outputs[] is a descriptor — name, type, required, description, an optional default, and an optional source (where a value can be fetched from). The declared type is one of the engine's field types: string, integer, float, boolean, list, dict, json, datetime, email, uuid. A type with no declared inputs comes back with an empty fields[] and a note. For the exact descriptor JSON, see the schema contract reference and reference.orkestia.dev.

Input validation is strict: a typo like emial against a schema with email is rejected loudly rather than silently ignored. Only the platform trace-correlation fields (trace_id, span_id, external_trace_id) are exempt. Full mechanics — the filter-then-validate output rule, the underscore-key handling, and the exception model — are in the schema contract reference.

The discovery loop

Whichever surface you drive Orkestia from — dashboard, SDK, REST API, or an AI agent over MCP — browsing the registry is the same four-call loop. Never guess inputs; ask the registry.

Over MCP

The MCP server exposes the registry directly to AI agents. The catalog tools are read-only and scope to your authenticated organization automatically.

list_workflow_namespaces()            → the domains you can use
list_workflow_types(prefix="aws.")    → operations within a namespace
get_workflow_schema("aws.s3.create_bucket")
                                      → fields[] + outputs[]; has_prerequisites, prerequisite_variants
get_workflow_prerequisites("aws.s3.create_bucket", variant=...)
                                      → setup guide (e.g. the connection to create)

Data lookups (resolving IDs, listing resources) are themselves data workflows — read-only types whose names usually contain load, list, fetch, get, or query. Discover them with a namespace prefix and read their terminal output. See MCP integration.

Over the SDKs / API

The TypeScript and Python SDKs are generated from these same registry schemas, so a type's inputs and outputs arrive fully typed in your editor. The REST API exposes the equivalent catalog endpoints. Pick the surface that fits; the loop is identical.

// TypeScript SDK — discover, then start with typed inputs
const types = await client.workflows.list({ prefix: "registry." })
const schema = await client.workflows.schema("registry.image.resolve")
const run = await client.workflows.start("registry.image.resolve", {
  repository_id: "rr_01HXZ...",
  tag: "prod",
})

The aggregated registry

Beyond per-type discovery, Orkestia exposes the whole index as a browsable catalog — the merged set of namespaces and types across all installed libraries, with their schemas and prerequisite flags. This is what powers:

Where to go next