> ## Documentation Index
> Fetch the complete documentation index at: https://yukta.infenia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Define a workflow in JSON

> Write a session with one workflow as JSON (nodes, edges, a terminal on every path), check it, apply it and start a run.

<dl />

**Use this when** you want a new workflow on the server. A workflow is plain JSON: a list of steps (`nodes`) and a list of arrows between them (`edges`), stored inside a [session](https://yukta.infenia.com/concepts/sessions-and-workflows.md).

**Prerequisites:** a running server. If it uses API keys, add `-H "X-API-Key: $YUKTA_API_KEY"` to every `curl`.

## Steps

**1. Pick a trigger**

A trigger starts the run. `API_TRIGGER` emits the payload of the start request, `SCHEDULE_TRIGGER` ticks on a timer ([Schedule a workflow](https://yukta.infenia.com/guides/build/schedule-a-workflow.md)) and `CONSTANT_SOURCE` emits fixed values.

**2. Add processors**

Chain the plugins that fetch, transform, route or decide. The type string is used exactly as listed in the [plugin reference](https://yukta.infenia.com/reference/plugins/overview.md). To see the options, ports and defaults of one plugin, ask the server:

```bash theme={"system"}
curl -s localhost:9858/api/plugins/MAPPER
```

**3. End every path with a terminal**

Every path must reach a terminal, such as `CONSOLE_TERMINAL`. A workflow with no terminal is refused.

**4. Write it down**

Save this as `session.json`. It builds a greeting from the start payload:

```json session.json theme={"system"}
{
  "sessionId": "demo",
  "name": "Demo",
  "description": "Greet a user",
  "initiator": "docs",
  "projectPath": "/tmp",
  "workflows": {
    "greet": {
      "workflowId": "greet",
      "description": "Build 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" }
      ]
    }
  }
}
```

The fields are in the [Workflow JSON reference](https://yukta.infenia.com/reference/workflow-json.md). Only the node's `engine` object is read by the server (retries, error routing, time limits: [Node options](https://yukta.infenia.com/reference/node-options.md)); everything else in `config` belongs to the plugin.

**5. Check it, then apply it**

The check takes one workflow (the object under `workflows`) and stores nothing; see [Validate and roll back](https://yukta.infenia.com/guides/build/validate-and-roll-back.md). Applying runs the same checks, so an invalid definition is never stored.

```bash theme={"system"}
curl -X POST localhost:9858/api/sessions -H 'Content-Type: application/json' -d @session.json
```

Applying replaces the whole session with the same `sessionId`: workflows you leave out are removed. To edit, read it with `GET /api/sessions/demo/config`, change it and send it back.

**6. Start a run**

```bash theme={"system"}
curl -s -X POST localhost:9858/api/workflow/start -H 'Content-Type: application/json' \
  -d '{"sessionId":"demo","workflowId":"greet","payload":{"name":"Ada"}}'
```

The answer is `202` with the new `executionId`.

## Verify it worked

```bash theme={"system"}
curl -s -H 'Accept: application/json' localhost:9858/api/sessions/demo/executions/$EXEC/results
```

`$EXEC` is the `executionId` from the start call. The answer has `"status": "SUCCESS"` and a `RESULT` event from node `end` whose `payload` is `{"greeting": "Hello, Ada"}`. If the apply call answers `400`, its message names the node and the option at fault.

## Variations

* **No input needed.** Start from `CONSTANT_SOURCE` instead of `API_TRIGGER`.
* **Group nodes in the UI.** Give nodes a `group`, or share an id prefix before the first dot (`lint`, `lint.fail`); display only.
* **Use the CLI or the web UI.** `yukta-cli session apply session.json` ([CLI reference](https://yukta.infenia.com/reference/cli.md)); the [web UI](https://yukta.infenia.com/guides/operate/use-the-web-ui.md) renders a form from each plugin's options and previews the graph.
* **Limits.** 500 nodes and 2000 edges per workflow; names and ids up to 256 characters. The newest 20 versions of a workflow are kept.

## Related

* [Route and branch](https://yukta.infenia.com/guides/build/route-and-branch.md) to send messages down different paths.
* [Use variables and expressions](https://yukta.infenia.com/guides/build/use-variables-and-expressions.md) to read message data and secrets in `config`.
* [Sessions and workflows](https://yukta.infenia.com/concepts/sessions-and-workflows.md) for how the pieces relate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.