Quick Start

Everything in Orkestia is a workflow: a registered, schema-typed unit of work you can discover, start, and watch. This page shows the raw REST contract, then the typed SDKs.

Base URL & authentication

https://workflow-api.orkestia.dev

All calls carry a Bearer token; organization scope is resolved from the token:

-H "Authorization: Bearer $TOKEN"

Step 1 — Discover workflow types

GET /api/workflows/types

Returns the paginated catalog — the same universe this reference documents. Filter by prefix to explore a domain:

GET /api/workflows/types?prefix=control.

Step 2 — Get a workflow's schema

GET /api/workflows/types/control.text.replace/schema

Response (abridged):

{
  "workflow_type": "control.text.replace",
  "input_schema": {
    "fields": [
      { "name": "text",    "type": "string",  "required": true },
      { "name": "find",    "type": "string",  "required": true },
      { "name": "replace", "type": "string",  "required": false },
      { "name": "regex",   "type": "boolean", "required": false }
    ]
  }
}

Step 3 — Start a workflow

The workflow type goes in the body, not the path:

POST /api/workflows/start
{
  "workflow_type": "control.text.replace",
  "initial_data": {
    "text": "hello world",
    "find": "world",
    "replace": "orkestia"
  }
}

Response:

{
  "workflow_id": "3f6b2c1e-...",
  "state": "PENDING"
}

Step 4 — Watch it

# Current state + state_data
GET /api/workflows/{workflow_id}

# Full state history
GET /api/workflows/{workflow_id}/history

A workflow is done when its state is terminal (COMPLETED / FAILED for atomic workflows).

Step 5 — Recover

# Re-run a failed workflow from its failure point
POST /api/workflows/{workflow_id}/retry

# Resume a workflow parked in a waiting state
POST /api/workflows/{workflow_id}/resume

Typed SDKs

Both SDKs are generated from the same catalog as this reference — one typed binding per workflow.

TypeScript

import { LtIntegWorkflowsClient, control } from "@ltinteg/workflows-sdk";

const client = new LtIntegWorkflowsClient({
  baseUrl: "https://workflow-api.orkestia.dev",
  token: process.env.ORKESTIA_TOKEN,
});

const run = await control.text.startReplace(client, {
  text: "hello world",
  find: "world",
  replace: "orkestia",
});

Python

import os

from ltinteg_workflows_sdk import LtIntegWorkflowsClient
from ltinteg_workflows_sdk.control import text as control_text

client = LtIntegWorkflowsClient(
    base_url="https://workflow-api.orkestia.dev",
    token=os.environ["ORKESTIA_TOKEN"],
)

run = control_text.start_replace(client, text="hello world", find="world", replace="orkestia")

• TypeScript — @ltinteg/workflows-sdk (GitHub Packages).
• Python — ltinteg-workflows-sdk (wheel attached to each GitHub release).

MCP

Agents can do all of the above over MCP — discovery, schemas, start, watch — see the MCP client guides.

Error handling

Errors follow one shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "initial_data.subject is required",
    "details": {}
  }
}

Code	HTTP	Meaning
VALIDATION_ERROR	400	Input does not match the workflow's schema
UNAUTHORIZED	401	Invalid or missing token
FORBIDDEN	403	Token lacks access to this workflow/org
WORKFLOW_NOT_FOUND	404	Unknown workflow id or type
INTERNAL_ERROR	500	Server error