Build Your First Motia App

What You'll Build

A complete pet store backend system that grows with you:

• API Endpoints → Handle requests, return responses
• Background Jobs → Process tasks without blocking APIs
• Workflows → Coordinate complex business logic automatically
• AI Agents → Make intelligent decisions that drive your workflows
• Real-Time Streaming → Push live updates to clients as workflows execute

By the end, you'll have a production-ready backend that handles everything from simple CRUD to intelligent, real-time systems.

Before You Start

You'll need:

• Node.js installed (v18 or higher)
• Basic understanding of TypeScript/JavaScript/Python
• 10-20 minutes per tutorial

That's it. No database setup, no complex config, no separate services to run.

Your Journey

1. API Endpoints

What: Create HTTP endpoints that handle pet operations.

You'll learn:

• How to define API Steps
• Request validation with schemas
• Returning proper HTTP responses
• Testing endpoints in Workbench

Time: 10 minutes

2. Background Jobs

What: Add async tasks that run without blocking your APIs.

You'll learn:

• Event Steps that trigger from your APIs
• Cron Steps that run on a schedule
• How events connect your system
• Monitoring jobs in Workbench

Time: 15 minutes

3. Workflows

What: Coordinate complex processes with automatic transitions and validation.

You'll learn:

• Building workflow orchestrators
• Automatic vs manual transitions
• State validation and progression
• Chaining multiple actions together

Time: 20 minutes

4. AI Agents

What: Add intelligent decision-making to your workflows.

You'll learn:

• Content generation with AI
• Decision-making agents
• Integrating AI with workflows
• Building agentic routing

Time: 20 minutes

5. Real-Time Streaming

What: Push live updates to clients while your workflows run in the background.

You'll learn:

• Defining stream configurations
• Streaming from APIs that return immediately
• Background jobs that push progress updates
• AI agents that stream enrichment progress
• Connecting multiple steps to the same stream

Time: 20 minutes

The Example Project

All tutorials use the same project - a pet store backend that handles:

• Pet management → Create, update, list pets
• Adoption workflow → Guide pets through quarantine, health checks, and availability
• Feeding reminders → Set up schedules when pets arrive
• Health decisions → AI evaluates symptoms and recommends treatment
• Cleanup jobs → Remove soft-deleted pets on a schedule
• Real-time updates → Stream progress to clients as workflows execute

It's a real system with the kind of complexity you'll face building production backends.

Interactive Tutorials

Each guide includes an interactive tutorial you can run directly in Workbench. It walks you through the code, explains what's happening, and lets you test everything live.

Prefer reading? The written guides cover everything too. They're detailed, with code examples and explanations for every concept.

Ready?

Pick your starting point. If you're new to Motia, start with API Endpoints. If you've already covered the basics, jump to wherever you want to learn more.