api-steps

API Steps Guide

API Steps expose HTTP endpoints that can trigger workflows and emit events.

Creating API Steps

Steps need to be created in the steps folder, it can be in subfolders.

• Steps in TS and JS should end with .step.ts and .step.js respectively.
• Steps in Python should end with _step.py.

Definition

Defining an API Step is done by two elements. Configuration and Handler.

Schema Definition

• TypeScript/JavaScript: Motia uses Zod schemas for automatic validation of request/response data
• Python: Motia uses JSON Schema format. You can optionally use Pydantic models to generate JSON Schemas and handle manual validation in your handlers

Configuration

TypeScript/JavaScript: You need to export a config constant via export const config that is a ApiRouteConfig type.

Python: You need to define a config dictionary with the same properties as the TypeScript ApiRouteConfig.

export type ZodInput = ZodObject<any> | ZodArray<any>
export type StepSchemaInput = ZodInput | JsonSchema

export type Emit = string | { 
  /**
   * The topic name to emit to.
   */
  topic: string;

  /**
   * Optional label for the emission, could be used for documentation or UI.
   */
  label?: string;

  /**
   * This is purely for documentation purposes, 
   * it doesn't affect the execution of the step.
   * 
   * In Workbench, it will render differently based on this value.
   */
  conditional?: boolean;
}

export interface QueryParam {
  /**
   * The name of the query parameter
   */
  name: string
  /**
   * The description of the query parameter
   */
  description: string
}

export interface ApiRouteConfig {
  /**
   * Should always be api
   */
  type: 'api'

  /**
   * A unique name for this API step, used internally and for linking handlers.
   */
  name: string

  /**
   * Optional human-readable description.
   */
  description?: string

  /**
   * The URL path for this API endpoint (e.g., '/users/:id').
   */
  path: string

  /**
   * The HTTP method for this route.
   * POST, GET, PUT, DELETE, PATCH, OPTIONS, HEAD
   */
  method: ApiRouteMethod

  /**
   * Topics this API step can emit events to.
   * Important note: All emits in the handler need to be listed here.
   */
  emits: Emit[]

  /**
   * Optional: Topics that are virtually emitted, perhaps for documentation or lineage, 
   * but not strictly required for execution.
   * 
   * In Motia Workbench, they will show up as gray connections to other steps.
   */
  virtualEmits?: Emit[]

  /**
   * Optional: Virtually subscribed topics.
   * 
   * Used by API steps when we want to chain different HTTP requests
   * that could happen sequentially
   */
  virtualSubscribes?: string[]
  /**
   * Flows are used to group multiple steps to be visible in diagrams in Workbench
   */
  flows?: string[]

  /**
   * List of middlewares that will be executed BEFORE the handler is called
   */
  middleware?: ApiMiddleware<any, any, any>[]

  /**
   * Schema for the request body. Accepts either:
   * - Zod schema (ZodObject or ZodArray)
   * - JSON Schema object
   * 
   * Note: This is not validated automatically, you need to validate it in the handler.
   */
  bodySchema?: StepSchemaInput

  /**
   * Schema for response bodies. Accepts either:
   * - Zod schema (ZodObject or ZodArray)
   * - JSON Schema object
   * 
   * The key (number) is the HTTP status code this endpoint can return and
   * for each HTTP Status Code, you need to define a schema that defines the response body
   */
  responseSchema?: Record<number, StepSchemaInput>

  /**
   * Mostly for documentation purposes, it will show up in Endpoints section in Workbench
   */
  queryParams?: QueryParam[]

  /**
   * Files to include in the step bundle.
   * Needs to be relative to the step file.
   */
  includeFiles?: string[]
}