Quickstart

Get started with Motia in under 60 seconds. This guide will help you create your first Motia application with HTTP endpoints and background jobs.

Prerequisites

Node.js 18+ — for TypeScript/JavaScript Steps
Python 3.10+ — optional, for Python Steps

Installation

Install the Motia CLI

brew tap MotiaDev/tap
brew install motia-cli

The CLI will automatically detect and install the iii engine if it’s not already on your system.

Create a new project

motia-cli create my-app
cd my-app

The CLI will prompt you to:

Choose a language (TypeScript, JavaScript, or Python)
Select a template (basic, api, or full-stack)

Start the iii engine

iii -c iii-config.yaml

This starts the Rust-based runtime that manages your APIs, queues, state, streams, and cron jobs.

The iii Console will be available at http://localhost:3113 for monitoring and debugging.

Your first Step

Let’s create a simple HTTP endpoint that returns a greeting.

TypeScript
Python

Create steps/hello.step.ts:

steps/hello.step.ts

export const config = {
  name: 'Hello',
  triggers: [
    {
      type: 'http',
      method: 'GET',
      path: '/hello',
    }
  ],
};

export const handler = async (req, ctx) => {
  const name = req.queryParams.name || 'World';
  return {
    status: 200,
    body: { message: `Hello, ${name}!` }
  };
};

Create steps/hello_step.py:

steps/hello_step.py

config = {
    "name": "Hello",
    "triggers": [
        {
            "type": "http",
            "method": "GET",
            "path": "/hello",
        }
    ],
}

async def handler(req, ctx):
    name = req.query_params.get("name", "World")
    return {
        "status": 200,
        "body": {"message": f"Hello, {name}!"}
    }

Test your endpoint

With the iii engine running, test your endpoint:

curl http://localhost:3111/hello?name=Motia

You should see:

{
  "message": "Hello, Motia!"
}

Add a background job

Now let’s add a queue-based background job that processes messages asynchronously.

TypeScript
Python

Create steps/process-message.step.ts:

steps/process-message.step.ts

export const config = {
  name: 'ProcessMessage',
  triggers: [
    {
      type: 'queue',
      topic: 'message.sent',
    }
  ],
};

export const handler = async (input, { logger }) => {
  logger.info('Processing message', input);
  // Process the message here
  await new Promise(resolve => setTimeout(resolve, 1000));
  logger.info('Message processed successfully');
};

Update steps/hello.step.ts to enqueue messages:

steps/hello.step.ts

export const config = {
  name: 'Hello',
  triggers: [
    {
      type: 'http',
      method: 'GET',
      path: '/hello',
    }
  ],
  enqueues: ['message.sent'] // Add this line
};

export const handler = async (req, { enqueue }) => {
  const name = req.queryParams.name || 'World';

  // Enqueue a background job
  await enqueue({
    topic: 'message.sent',
    data: { name, timestamp: new Date().toISOString() }
  });

  return {
    status: 200,
    body: { message: `Hello, ${name}!` }
  };
};

Create steps/process_message_step.py:

steps/process_message_step.py

import asyncio

config = {
    "name": "ProcessMessage",
    "triggers": [
        {
            "type": "queue",
            "topic": "message.sent",
        }
    ],
}

async def handler(input, ctx):
    ctx.logger.info("Processing message", input)
    # Process the message here
    await asyncio.sleep(1)
    ctx.logger.info("Message processed successfully")

Update steps/hello_step.py to enqueue messages:

steps/hello_step.py

from datetime import datetime

config = {
    "name": "Hello",
    "triggers": [
        {
            "type": "http",
            "method": "GET",
            "path": "/hello",
        }
    ],
    "enqueues": ["message.sent"]  # Add this line
}

async def handler(req, ctx):
    name = req.query_params.get("name", "World")

    # Enqueue a background job
    await ctx.enqueue({
        "topic": "message.sent",
        "data": {"name": name, "timestamp": datetime.now().isoformat()}
    })

    return {
        "status": 200,
        "body": {"message": f"Hello, {name}!"}
    }

Now when you call the endpoint, it will enqueue a background job that processes asynchronously:

curl http://localhost:3111/hello?name=Motia

Check the iii Console at http://localhost:3113 to see the background job being processed.

What you’ve learned

✅ How to install the Motia CLI and iii engine
✅ How to create a new Motia project
✅ How to create HTTP endpoints with Steps
✅ How to add background jobs with queue triggers
✅ How to enqueue messages from HTTP handlers

Next steps

Core concepts

Learn about Steps, triggers, and handlers in depth

Building APIs

Build production-ready REST APIs with validation

Background jobs

Master background job patterns and workflows

Examples

Explore more real-world examples

Get Started

Core Concepts

Triggers

Guides

Advanced

Quickstart

Quickstart

Prerequisites

Installation

Your first Step

Test your endpoint

Add a background job

What you’ve learned

Next steps

Core concepts

Building APIs

Background jobs

Examples

Build docs developers (and LLMs) love

Get Started

Core Concepts

Triggers

Guides

Advanced

​Quickstart

​Prerequisites

​Installation

​Your first Step

​Test your endpoint

​Add a background job

​What you’ve learned

​Next steps

Core concepts

Building APIs

Background jobs

Examples

Build docs developers (and LLMs) love

Quickstart

Prerequisites

Installation

Your first Step

Test your endpoint

Add a background job

What you’ve learned

Next steps