Quickstart

You will start the server, apply a session that contains one workflow, start that workflow with some input, and read the result.

Before you begin

A JDK, version 25, to run the server from source
git
curl (any HTTP client works; the examples show plain HTTP requests as well)

There are no packaged releases yet. A native binary and a container image can be built from source, see Deployment.

1. Run the server

git clone https://github.com/infenia/yukta.git
cd yukta
./gradlew bootRun

The server listens on http://localhost:8080, on loopback only. Open that address for the web UI, or http://localhost:8080/swagger-ui.html for interactive API documentation.

2. Apply a session

A session groups workflows. This one holds a single workflow that reads a name from the start request and builds a greeting.

POST /api/sessions
Content-Type: application/json

{
  "sessionId": "demo",
  "name": "Quickstart",
  "description": "Greet a user",
  "initiator": "me",
  "projectPath": "/tmp",
  "workflows": {
    "greet": {
      "workflowId": "greet",
      "description": "Map the request payload into a greeting",
      "nodes": [
        { "nodeId": "trigger", "type": "API_TRIGGER", "config": {} },
        {
          "nodeId": "map",
          "type": "MAPPER",
          "config": {
            "mode": "PROJECTION",
            "mapping": { "greeting": "'Hello, ' + payload.name" }
          }
        },
        { "nodeId": "end", "type": "CONSOLE_TERMINAL", "config": {} }
      ],
      "edges": [
        { "source": "trigger", "target": "map" },
        { "source": "map", "target": "end" }
      ]
    }
  }
}

With curl, save the body as session.json and run:

curl -X POST http://localhost:8080/api/sessions \
  -H "Content-Type: application/json" -d @session.json

The workflow has one node of each role: API_TRIGGER receives the payload you send when you start it, MAPPER builds a new record from it, and CONSOLE_TERMINAL ends the branch by logging what arrives.

Sessions are held in memory by default, so apply them again after a restart. See Persistence to keep them on disk or in PostgreSQL.

3. Start the workflow

POST /api/workflow/start
Content-Type: application/json

{ "sessionId": "demo", "workflowId": "greet", "payload": { "name": "Ada" } }

curl -X POST http://localhost:8080/api/workflow/start \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"demo","workflowId":"greet","payload":{"name":"Ada"}}'

The server answers 202 Accepted with an execution id in data.executionId. The execution runs in the background.

4. Watch it and read the result

Poll the status:

GET /api/executions/{executionId}

{
  "status": 200,
  "message": "Workflow status retrieved successfully",
  "data": {
    "executionId": "3de8bcf2-24ee-400a-8bff-c586c610dbe4",
    "sessionId": "demo",
    "workflowId": "greet",
    "status": "SUCCESS",
    "tasks": [
      { "nodeId": "trigger", "module": "API_TRIGGER", "status": "SUCCESS" },
      { "nodeId": "map", "module": "MAPPER", "status": "SUCCESS" },
      { "nodeId": "end", "module": "CONSOLE_TERMINAL", "status": "SUCCESS" }
    ]
  }
}

The run has a status and every node has one. SUCCESS means the execution finished normally. To follow a run live instead of polling, open the status stream, which uses server-sent events:

curl -N http://localhost:8080/api/executions/{executionId}/status/stream

Read the logs

GET /api/sessions/demo/executions/{executionId}/logs

The log stream shows what each node produced as it ran:

[INFO] [trigger/API_TRIGGER] STDOUT: {name=Ada}
[INFO] [map/MAPPER] STDOUT: {greeting=Hello, Ada}

Read the result

Logs are text for people. The result is what reached the terminal node, kept whole and typed:

GET /api/sessions/demo/executions/{executionId}/results
Accept: application/json

{
  "executionId": "3de8bcf2-24ee-400a-8bff-c586c610dbe4",
  "complete": true,
  "status": "SUCCESS",
  "events": [
    { "kind": "RESULT", "nodeId": "end", "payload": { "greeting": "Hello, Ada" } },
    { "kind": "NODE_END", "nodeId": "end", "status": "SUCCESS" },
    { "kind": "EXECUTION_END" }
  ]
}

Responses show the fields used here; the server returns more, such as timestamps and cursors.

What just happened

Applying the session validated and stored the workflow.
Starting it checked the limits, took a slot and returned an execution id.
The trigger emitted one message carrying your payload. The mapper derived a new message from it, and the terminal received it as the result.
Every step produced events that the status, log and result streams carried to you.

Next steps

More examples

Ten workflows for CI, quality gates, data pipelines, retries, notifications and LLM agents.

Connect an AI agent

Point Claude or any MCP client at /mcp and let it create and run workflows.

Run operating-system commands

The process plugin refuses every command until you allow-list it.

Understand the model

Sessions, nodes, ports, messages and executions in depth.

Explore the REST API

Guides for every endpoint, plus an interactive endpoint reference.

Get started

Concepts

Building workflows

Plugin reference

Running and controlling

Interfaces

Operations

Reference

Before you begin

1. Run the server

2. Apply a session

3. Start the workflow

4. Watch it and read the result

Read the logs

Read the result

What just happened

Next steps

More examples

Connect an AI agent

Run operating-system commands

Understand the model

Explore the REST API

​Before you begin

​1. Run the server

​2. Apply a session

​3. Start the workflow

​4. Watch it and read the result

​Read the logs

​Read the result

​What just happened

​Next steps

More examples

Connect an AI agent

Run operating-system commands

Understand the model

Explore the REST API

Before you begin

1. Run the server

2. Apply a session

3. Start the workflow

4. Watch it and read the result

Read the logs

Read the result

What just happened

Next steps