HTTP trigger

HTTP triggers allow you to expose workflows as HTTP endpoints, enabling you to build REST APIs, webhooks, and HTTP-based integrations.

Basic usage

TypeScript
Python

import { step, http } from 'motia'
import { z } from 'zod'

export const config = step({
  name: 'get-user',
  triggers: [http('GET', '/users/:id')],
})

export const handler = async (input, ctx) => {
  const userId = input.request.pathParams.id
  
  return {
    status: 200,
    body: { id: userId, name: 'John Doe' },
  }
}

from motia import step, http

config = step(
    name='get-user',
    triggers=[http('GET', '/users/:id')],
)

async def handler(input, ctx):
    user_id = input['request']['pathParams']['id']
    
    return {
        'status': 200,
        'body': {'id': user_id, 'name': 'John Doe'},
    }

HTTP methods

HTTP triggers support all standard HTTP methods:

TypeScript
Python

import { step, http } from 'motia'

export const config = step({
  name: 'api-endpoints',
  triggers: [
    http('GET', '/items'),
    http('POST', '/items'),
    http('PUT', '/items/:id'),
    http('DELETE', '/items/:id'),
    http('PATCH', '/items/:id'),
  ],
})

from motia import step, http

config = step(
    name='api-endpoints',
    triggers=[
        http('GET', '/items'),
        http('POST', '/items'),
        http('PUT', '/items/:id'),
        http('DELETE', '/items/:id'),
        http('PATCH', '/items/:id'),
    ],
)

Request handling

Path parameters

Extract dynamic values from the URL path:

TypeScript
Python

import { step, http } from 'motia'

export const config = step({
  name: 'get-item',
  triggers: [http('GET', '/items/:id')],
})

export const handler = async (input, ctx) => {
  const { id } = input.request.pathParams
  
  return {
    status: 200,
    body: { id, name: 'Item' },
  }
}

from motia import step, http

config = step(
    name='get-item',
    triggers=[http('GET', '/items/:id')],
)

async def handler(input, ctx):
    item_id = input['request']['pathParams']['id']
    
    return {
        'status': 200,
        'body': {'id': item_id, 'name': 'Item'},
    }

Query parameters

Access query string parameters:

TypeScript
Python

import { step, http } from 'motia'

export const config = step({
  name: 'search-items',
  triggers: [
    http('GET', '/search', {
      queryParams: [
        { name: 'q', description: 'Search query' },
        { name: 'limit', description: 'Results limit' },
      ],
    }),
  ],
})

export const handler = async (input, ctx) => {
  const { q, limit } = input.request.queryParams
  
  return {
    status: 200,
    body: { query: q, limit: limit || '10' },
  }
}

from motia import step, http

config = step(
    name='search-items',
    triggers=[
        http(
            'GET',
            '/search',
            query_params=[
                {'name': 'q', 'description': 'Search query'},
                {'name': 'limit', 'description': 'Results limit'},
            ],
        ),
    ],
)

async def handler(input, ctx):
    q = input['request']['queryParams'].get('q')
    limit = input['request']['queryParams'].get('limit', '10')
    
    return {
        'status': 200,
        'body': {'query': q, 'limit': limit},
    }

Request body

Handle POST/PUT/PATCH request bodies with schema validation:

TypeScript
Python

import { step, http } from 'motia'
import { z } from 'zod'

const createItemSchema = z.object({
  name: z.string(),
  price: z.number(),
  description: z.string().optional(),
})

export const config = step({
  name: 'create-item',
  triggers: [
    http('POST', '/items', {
      bodySchema: createItemSchema,
    }),
  ],
})

export const handler = async (input, ctx) => {
  const { name, price, description } = input.request.body
  
  return {
    status: 201,
    body: {
      id: 'item-123',
      name,
      price,
      description,
      created: true,
    },
  }
}

from motia import step, http

config = step(
    name='create-item',
    triggers=[
        http(
            'POST',
            '/items',
            body_schema={
                'type': 'object',
                'properties': {
                    'name': {'type': 'string'},
                    'price': {'type': 'number'},
                    'description': {'type': 'string'},
                },
                'required': ['name', 'price'],
            },
        ),
    ],
)

async def handler(input, ctx):
    body = input['request']['body']
    
    return {
        'status': 201,
        'body': {
            'id': 'item-123',
            'name': body['name'],
            'price': body['price'],
            'created': True,
        },
    }

Headers

Access request headers:

TypeScript
Python

export const handler = async (input, ctx) => {
  const authHeader = input.request.headers['authorization']
  const contentType = input.request.headers['content-type']
  
  return {
    status: 200,
    body: { authenticated: !!authHeader },
  }
}

async def handler(input, ctx):
    auth_header = input['request']['headers'].get('authorization')
    content_type = input['request']['headers'].get('content-type')
    
    return {
        'status': 200,
        'body': {'authenticated': bool(auth_header)},
    }

Response handling

Status codes

Return different HTTP status codes:

TypeScript
Python

export const handler = async (input, ctx) => {
  const { id } = input.request.pathParams
  
  // Simulate item not found
  if (id === 'missing') {
    return {
      status: 404,
      body: { error: 'Item not found' },
    }
  }
  
  return {
    status: 200,
    body: { id, name: 'Found Item' },
  }
}

async def handler(input, ctx):
    item_id = input['request']['pathParams']['id']
    
    # Simulate item not found
    if item_id == 'missing':
        return {
            'status': 404,
            'body': {'error': 'Item not found'},
        }
    
    return {
        'status': 200,
        'body': {'id': item_id, 'name': 'Found Item'},
    }

Response headers

Set custom response headers:

TypeScript
Python

export const handler = async (input, ctx) => {
  return {
    status: 200,
    headers: {
      'X-Custom-Header': 'value',
      'Cache-Control': 'max-age=3600',
    },
    body: { message: 'Success' },
  }
}

async def handler(input, ctx):
    return {
        'status': 200,
        'headers': {
            'X-Custom-Header': 'value',
            'Cache-Control': 'max-age=3600',
        },
        'body': {'message': 'Success'},
    }

Response schema

Define response schemas for type safety:

TypeScript
Python

import { step, http } from 'motia'
import { z } from 'zod'

const successSchema = z.object({
  id: z.string(),
  name: z.string(),
})

const errorSchema = z.object({
  error: z.string(),
})

export const config = step({
  name: 'typed-response',
  triggers: [
    http('GET', '/items/:id', {
      responseSchema: {
        200: successSchema,
        404: errorSchema,
      },
    }),
  ],
})

from motia import step, http

config = step(
    name='typed-response',
    triggers=[
        http(
            'GET',
            '/items/:id',
            response_schema={
                200: {
                    'type': 'object',
                    'properties': {
                        'id': {'type': 'string'},
                        'name': {'type': 'string'},
                    },
                },
                404: {
                    'type': 'object',
                    'properties': {
                        'error': {'type': 'string'},
                    },
                },
            },
        ),
    ],
)

Middleware

Add middleware functions for cross-cutting concerns:

TypeScript
Python

import { step, http } from 'motia'
import type { ApiMiddleware } from 'motia'

const authMiddleware: ApiMiddleware = async (req, ctx, next) => {
  const token = req.request.headers['authorization']
  
  if (!token) {
    return {
      status: 401,
      body: { error: 'Unauthorized' },
    }
  }
  
  return await next()
}

const loggingMiddleware: ApiMiddleware = async (req, ctx, next) => {
  ctx.logger.info('Request received', {
    method: req.request.method,
    path: ctx.trigger.path,
  })
  
  return await next()
}

export const config = step({
  name: 'protected-endpoint',
  triggers: [
    http('GET', '/protected', {
      middleware: [loggingMiddleware, authMiddleware],
    }),
  ],
})

from motia import step, http

async def auth_middleware(req, ctx, next):
    token = req['request']['headers'].get('authorization')
    
    if not token:
        return {
            'status': 401,
            'body': {'error': 'Unauthorized'},
        }
    
    return await next()

async def logging_middleware(req, ctx, next):
    ctx.logger.info('Request received', {
        'method': req['request']['method'],
        'path': ctx.trigger['path'],
    })
    
    return await next()

config = step(
    name='protected-endpoint',
    triggers=[
        http(
            'GET',
            '/protected',
            middleware=[logging_middleware, auth_middleware],
        ),
    ],
)

Conditional triggers

Use conditions to selectively execute handlers:

TypeScript
Python

import { step, http } from 'motia'

export const config = step({
  name: 'conditional-api',
  triggers: [
    http(
      'POST',
      '/webhooks',
      undefined,
      (input, ctx) => {
        const signature = input.request.headers['x-webhook-signature']
        return !!signature
      },
    ),
  ],
})

from motia import step, http

def webhook_condition(input, ctx):
    signature = input['request']['headers'].get('x-webhook-signature')
    return bool(signature)

config = step(
    name='conditional-api',
    triggers=[
        http('POST', '/webhooks', condition=webhook_condition),
    ],
)

Configuration options

method

string

required

HTTP method: GET, POST, PUT, DELETE, PATCH, OPTIONS, or HEAD

path

string

required

URL path pattern. Supports path parameters with :param syntax (e.g., /users/:id)

bodySchema

ZodSchema | JsonSchema

Schema for validating request body. Automatically validates incoming requests

responseSchema

Record<number, Schema>

Map of status codes to response schemas for type safety and documentation

queryParams

QueryParam[]

Array of query parameter definitions:

name (string): Parameter name
description (string): Parameter description

middleware

ApiMiddleware[]

Array of middleware functions executed before the handler. Each middleware can:

Modify the request
Return early with a response
Call next() to continue the chain

condition

function

Optional function (input, ctx) => boolean to conditionally execute the handler

Use cases

REST API

Build a complete REST API:

import { step, http } from 'motia'
import { z } from 'zod'

const itemSchema = z.object({
  name: z.string(),
  price: z.number(),
})

export const config = step({
  name: 'items-api',
  triggers: [
    http('GET', '/items'),
    http('GET', '/items/:id'),
    http('POST', '/items', { bodySchema: itemSchema }),
    http('PUT', '/items/:id', { bodySchema: itemSchema }),
    http('DELETE', '/items/:id'),
  ],
})

Webhook receiver

Receive webhooks from external services:

import { step, http } from 'motia'
import { z } from 'zod'

const webhookSchema = z.object({
  event: z.string(),
  data: z.record(z.unknown()),
})

export const config = step({
  name: 'github-webhook',
  triggers: [
    http('POST', '/webhooks/github', {
      bodySchema: webhookSchema,
    }),
  ],
})

export const handler = async (input, ctx) => {
  const { event, data } = input.request.body
  
  ctx.logger.info('Webhook received', { event })
  
  // Process webhook
  await ctx.enqueue({
    topic: 'webhook-events',
    data: { event, data },
  })
  
  return {
    status: 200,
    body: { received: true },
  }
}

File upload

Handle file uploads:

export const config = step({
  name: 'upload-file',
  triggers: [http('POST', '/upload')],
})

export const handler = async (input, ctx) => {
  const file = input.request.body
  
  // Process file
  ctx.logger.info('File uploaded', {
    size: file.length,
  })
  
  return {
    status: 201,
    body: { uploaded: true, fileId: 'file-123' },
  }
}

Get Started

Core Concepts

Triggers

Guides

Advanced

HTTP trigger

Basic usage

HTTP methods

Request handling

Path parameters

Query parameters

Request body

Headers

Response handling

Status codes

Response headers

Response schema

Middleware

Conditional triggers

Configuration options

Use cases

REST API

Webhook receiver

File upload

Build docs developers (and LLMs) love

Get Started

Core Concepts

Triggers

Guides

Advanced

​Basic usage

​HTTP methods

​Request handling

​Path parameters

​Query parameters

​Request body

​Headers

​Response handling

​Status codes

​Response headers

​Response schema

​Middleware

​Conditional triggers

​Configuration options

​Use cases

​REST API

​Webhook receiver

​File upload

Build docs developers (and LLMs) love

Basic usage

HTTP methods

Request handling

Path parameters

Query parameters

Request body

Headers

Response handling

Status codes

Response headers

Response schema

Middleware

Conditional triggers

Configuration options

Use cases

REST API

Webhook receiver

File upload