Steps
One primitive to build any backend. Simple, composable, and multi-language.
One Primitive for Any Backend
A Step is the core primitive in Motia. Instead of juggling separate frameworks for APIs, background jobs, queues, or workflows, you define everything in one place: how it runs, when it runs, where it runs, and what it does.
Every Step file contains two parts:
- Config → defines when and how the Step runs, and gives it a unique
name
- Handler → the function that executes your business logic
Motia automatically discovers any file ending in .step.ts
, .step.js
, or _step.py
.
The filename tells Motia to load it, and the name
in the config
uniquely identifies the Step inside your system.
The Simplest Example
👉 That’s all you need to make a running API endpoint.
Motia will auto-discover this file and wire it into your backend.
Steps Work Together: Emit + Subscribe
Steps aren’t isolated. They communicate by emitting and subscribing to events.
This is the core of how you build backends with Motia.
Example Flow: API Step → Event Step
👉 With just two files, you have an API endpoint that triggers an event-driven workflow.
Triggers
Every Step has a type
that defines how it triggers:
Type | When it runs | Use case |
---|---|---|
api | HTTP request | REST APIs, webhooks |
event | Event emitted | Background jobs, workflows |
cron | Schedule | Cleanup, reports, reminders |
API Trigger
Runs when an HTTP request hits the path.
Example:
Config:
Property | Description |
---|---|
name | Unique identifier |
type | Set to 'api' |
path | URL path (supports :params ) |
method | GET, POST, PUT, DELETE |
bodySchema | Validate request body |
Handler: handler(req, ctx)
req
- Request withbody
,headers
,pathParams
,queryParams
ctx
- Context withlogger
,emit
,state
,streams
,traceId
- Returns
{ status, body, headers? }
Context Object
Every handler receives a ctx
object with these tools:
Property | Description |
---|---|
logger | Structured logging (info , warn , error ) |
emit | Trigger other Steps by emitting events |
state | Persistent key-value storage |
streams | Real-time data channels for clients |
traceId | Unique ID for tracing requests & workflows |
Core Functionality
State – Persistent Data
Key-value storage shared across Steps and workflows.
Logging – Structured & Contextual
For debugging, monitoring, and observability.
Streams – Real-Time Data
Push updates directly to connected clients.
Remember
- Steps are just files. Export a
config
andhandler
. - Motia auto-discovers and connects them.
- Combine Steps with emit + subscribe to build APIs, workflows, background jobs, or entire systems.