Reference
Reference
The Reference section is the lookup layer of the Orkestia documentation. Where the Concepts explain what the platform is and the Guides walk through how to accomplish a task, the Reference answers the precise questions you reach for mid-build: what is this workflow called, what inputs does it take, what does the MCP tool return, which metric do I query?
What's here
Workflow Types & Registry
The naming contract ({provider}.{service}.{operation}), namespaces, atomic vs. composed (virtual) workflows, the 3-state lifecycle, and how the registry is discovered and queried.
MCP Integration
The Model Context Protocol surface that lets AI agents discover and run capabilities: the discovery → schema → prerequisites → start → watch loop, and the full tool inventory.
API & Tooling
REST entry points, the request-context contract (auth → org → validation), and the operational surfaces for connections, runners, and identity.
SDKs
@ltinteg/workflows-sdk (Node), ltinteg-workflows-sdk (Python), @orkestia/auth (end-user PKCE / OAuth).
App Data
Declare, instances, Data API, PostgREST, Query. Live types at reference.orkestia.dev under data.appdata.* and appdata.*.
App Host
Claim, release, web.deploy, database.attach, addon.apply (Nostr Buzz), apphost.file.* (Files on site MinIO). Catalog prefix apphost.*.
How to read this section
Orkestia's reference surfaces follow one design principle: capabilities are declared, never invented. A workflow type is a registered capability with a stable name and a typed input schema; a workflow run is an execution of that capability with its own workflow_id. Every reference page describes the contract; the catalog and the live MCP/REST discovery calls return the concrete, current values.
- Catalog / Discovery
- Workflow Typeregistered capability
- Typed input contract
- Workflow Runworkflow_id
- Lumenstate + observability
- Catalog / Discovery→ list_workflow_types →Workflow Type
- Workflow Type→ get_workflow_schema →Typed input contract
- Typed input contract→ start_workflow →Workflow Run
- Workflow Run→ transitions →Lumen
list_workflow_types() and get_workflow_schema(<type>) over MCP. The registry is the only authority that reflects what is actually deployed for your organization.The naming contract
Atomic workflows follow a strict, predictable name shape so that agents and humans can reason about a capability before ever calling it:
| Segment | Meaning | Example |
|---|---|---|
provider | The cloud or external system | aws, gcp, github |
service | The service or resource family | ec2, s3, iam |
operation | The single operation performed | create, describe, delete |
A fully qualified type therefore reads as provider.service.operation. Composed business processes (DAGs) and AI-designed virtual workflows reuse these atomic types as nodes. See Workflow Types & Registry for the full model and Virtual Workflows for how compositions compile down to deterministic execution.
Privacy posture of the reference surfaces
The reference surfaces are intentionally narrow about what they expose. Orkestia operates under Zero Code Custody: execution happens inside your own cloud accounts, and the platform orchestrates and retains only workflow state and observability data (Lumen). The registry describes capabilities and the schemas describe input shapes — neither carries your source, your secrets, or the contents of resources in your accounts.
has_prerequisites: true, the prerequisites call returns a setup guide with the platform identity already filled in — see MCP Integration.Related sections
Typed decisions with TypeSafe
Put TypeSafe Jev in front of compositions, Staff actors, DGI designs, and cluster actions — closed-set answers, not chat
Workflow Types & Registry
How the Orkestia workflow registry is structured — namespaces, dotted naming, typed schemas, prerequisites, and the discovery loop that lets humans, SDKs, and AI agents browse capabilities