Quickstart

Get a Motia project up and running in under 60 seconds.

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

1. Install the Motia CLI

   Homebrew

   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.

2. 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)
3. 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

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}!` }
  };
};

Python

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

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}!` }
  };
};

Python

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