If you've ever wired together a chain of API calls with retry logic, state tracking, and error handling stitched into application code, you know how quickly that complexity spirals. StateLayer replaces all of that with a declarative workflow graph that the platform executes, monitors, and recovers for you.

This guide walks you through creating and running your first workflow — from zero to a working execution in about five minutes.

What Is a Workflow?

A workflow in StateLayer is a directed graph of steps. Each step performs a discrete unit of work — calling an HTTP endpoint, evaluating a condition, transforming data, or waiting for an external signal. Steps are connected by transitions that define the execution path based on each step's outcome.

The platform manages the full lifecycle:

Versioning — every change produces an immutable version. Draft versions are editable; published versions are locked and runnable.
Execution — the runtime walks the graph, hydrates each step with its inputs, executes it, and follows the appropriate transition.
Resilience — retries, timeouts, and error transitions are first-class concepts, not afterthoughts.

You define the graph as a JSON structure (or visually in the builder UI), and StateLayer handles everything else.

Creating Your First Workflow

Let's create a simple two-step workflow: an HTTP call followed by a logging step. Start by creating a new workflow via the API:

curl -X POST https://api.statelayer.io/v1/workflows \
  -H "X-API-Key: $API_KEY" \
  -H "X-Environment-Id: $ENV_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-world",
    "description": "My first StateLayer workflow"
  }'

The response includes the workflow ID and an initial draft version. Next, update the draft's structure with your steps:

curl -X PUT https://api.statelayer.io/v1/workflows/$WORKFLOW_ID/versions/$VERSION_ID/structure \
  -H "X-API-Key: $API_KEY" \
  -H "X-Environment-Id: $ENV_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "startStep": "fetch-data",
    "steps": {
      "fetch-data": {
        "type": "system:http-request",
        "config": {
          "method": "GET",
          "url": "https://jsonplaceholder.typicode.com/posts/1"
        },
        "transitions": {
          "default": "finish"
        }
      },
      "finish": {
        "type": "system:end",
        "config": {}
      }
    }
  }'

Once you're happy with the structure, publish the version to make it runnable:

curl -X POST https://api.statelayer.io/v1/workflows/$WORKFLOW_ID/versions/$VERSION_ID/publish \
  -H "X-API-Key: $API_KEY" \
  -H "X-Environment-Id: $ENV_ID"

Running Your Workflow

With a published version in place, trigger an execution:

curl -X POST https://api.statelayer.io/v1/workflows/$WORKFLOW_ID/execute \
  -H "X-API-Key: $API_KEY" \
  -H "X-Environment-Id: $ENV_ID" \
  -H "Content-Type: application/json" \
  -d '{ "input": {} }'

StateLayer creates a new instance, walks the graph starting at fetch-data, executes the HTTP request, follows the default transition to finish, and completes the run. You can poll the instance endpoint or use the dashboard to watch it happen in real time.

Check the instance status:

curl https://api.statelayer.io/v1/instances/$INSTANCE_ID \
  -H "X-API-Key: $API_KEY" \
  -H "X-Environment-Id: $ENV_ID"

The response includes the current state, step-by-step outputs, and timing information for every step that executed.

Next Steps

You've just built, published, and executed a complete workflow. From here you can explore condition steps to add branching logic, signals for event-driven pauses, and custom nodes from the registry to plug in your own business logic. Check out the Advanced Patterns section of the blog for deeper dives into retry strategies, parallel execution, and integration-driven workflows.