Create API Routes

Learn how to create custom API routes in Medusa with AuthenticatedMedusaRequest and MedusaResponse.

API routes in Medusa are file-based HTTP endpoints that follow Next.js-style conventions. They automatically integrate with authentication, validation, and the dependency injection container.

Route Basics

Routes are defined in the src/api directory with a specific file structure:

src/api/
├── admin/              # Admin API routes (requires authentication)
│   └── brands/
│       ├── route.ts    # /admin/brands
│       └── [id]/
│           └── route.ts # /admin/brands/:id
└── store/              # Store API routes (public or customer auth)
    └── brands/
        └── route.ts

Creating a Basic Route

1. Create the Route File

   Create a route.ts file with named exports for HTTP methods:

   src/api/admin/brands/route.ts

   import {
     AuthenticatedMedusaRequest,
     MedusaResponse,
   } from "@medusajs/framework/http"
   
   export async function GET(
     req: AuthenticatedMedusaRequest,
     res: MedusaResponse
   ) {
     res.json({
       brands: [],
     })
   }
   
   export async function POST(
     req: AuthenticatedMedusaRequest,
     res: MedusaResponse
   ) {
     res.json({
       brand: { id: "brand_123" },
     })
   }
   

   Available HTTP methods: GET, POST, PUT, PATCH, DELETE

2. Use Dependency Injection

   Access services and modules via req.scope:

   import { BRAND_MODULE } from "../../../modules/brand"
   import { IBrandModuleService } from "../../../modules/brand/types"
   
   export async function GET(
     req: AuthenticatedMedusaRequest,
     res: MedusaResponse
   ) {
     const brandService = req.scope.resolve<IBrandModuleService>(
       BRAND_MODULE
     )
   
     const brands = await brandService.listBrands()
   
     res.json({ brands })
   }
   
3. Execute Workflows

   Most routes should execute workflows instead of calling services directly:

   import { createBrandWorkflow } from "../../../workflows/brand/create-brand"
   
   export async function POST(
     req: AuthenticatedMedusaRequest,
     res: MedusaResponse
   ) {
     const { result: brand } = await createBrandWorkflow(req.scope).run({
       input: req.body,
     })
   
     res.status(201).json({ brand })
   }
   

Complete CRUD Example

Here’s a full example implementing CRUD operations:

List Brands

src/api/admin/brands/route.ts

import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { ContainerRegistrationKeys } from "@medusajs/framework/utils"

export async function GET(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)

  const { data: brands, metadata } = await query.graph({
    entity: "brand",
    fields: req.queryConfig.fields,
    filters: req.filterableFields,
    pagination: req.queryConfig.pagination,
  })

  res.json({
    brands,
    count: metadata.count,
    offset: metadata.skip,
    limit: metadata.take,
  })
}

Create Brand

src/api/admin/brands/route.ts

import { createBrandWorkflow } from "../../../workflows/brand/create-brand"

export async function POST(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  const { result: brand } = await createBrandWorkflow(req.scope).run({
    input: {
      name: req.validatedBody.name,
      description: req.validatedBody.description,
    },
  })

  res.status(201).json({ brand })
}

Get Single Brand

src/api/admin/brands/[id]/route.ts

import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { ContainerRegistrationKeys } from "@medusajs/framework/utils"

export async function GET(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)

  const { data: brands } = await query.graph({
    entity: "brand",
    filters: { id: req.params.id },
    fields: req.queryConfig.fields,
  })

  if (!brands.length) {
    return res.status(404).json({
      message: `Brand with id ${req.params.id} not found`,
    })
  }

  res.json({ brand: brands[0] })
}

Update Brand

src/api/admin/brands/[id]/route.ts

import { updateBrandWorkflow } from "../../../../workflows/brand/update-brand"

export async function POST(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  const { result: brand } = await updateBrandWorkflow(req.scope).run({
    input: {
      id: req.params.id,
      ...req.validatedBody,
    },
  })

  res.json({ brand })
}

Delete Brand

src/api/admin/brands/[id]/route.ts

import { deleteBrandWorkflow } from "../../../../workflows/brand/delete-brand"

export async function DELETE(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  await deleteBrandWorkflow(req.scope).run({
    input: { ids: [req.params.id] },
  })

  res.json({
    id: req.params.id,
    object: "brand",
    deleted: true,
  })
}

Request Types

AuthenticatedMedusaRequest

Use for admin routes that require authentication:

import { AuthenticatedMedusaRequest } from "@medusajs/framework/http"

export async function GET(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  // Access authenticated user
  const userId = req.auth_context.actor_id
  
  // User is guaranteed to be authenticated
}

MedusaRequest

Use for public routes that don’t require authentication:

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  // No authentication required
}

Type Parameters

Add type parameters for request body and query params:

import { AuthenticatedMedusaRequest } from "@medusajs/framework/http"
import type { HttpTypes } from "@medusajs/framework/types"

interface CreateBrandBody {
  name: string
  description?: string
}

interface BrandQueryParams {
  fields?: string
}

export async function POST(
  req: AuthenticatedMedusaRequest<CreateBrandBody, BrandQueryParams>,
  res: MedusaResponse<HttpTypes.AdminBrandResponse>
) {
  const { name, description } = req.validatedBody
  // Type-safe access to body
}

Request Properties

req.scope

Dependency injection container:

const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
const logger = req.scope.resolve(ContainerRegistrationKeys.LOGGER)
const brandService = req.scope.resolve(BRAND_MODULE)

req.params

URL path parameters:

// Route: /admin/brands/[id]/route.ts
// URL: /admin/brands/brand_123
const brandId = req.params.id // "brand_123"

req.validatedBody

Validated request body (when using validators):

const { name, description } = req.validatedBody

req.validatedQuery

Validated query parameters:

const { limit, offset } = req.validatedQuery

req.filterableFields

Filters for querying:

const brands = await query.graph({
  entity: "brand",
  filters: req.filterableFields,
})

req.queryConfig

Query configuration:

const { fields, pagination } = req.queryConfig

req.auth_context

Authentication context (on AuthenticatedMedusaRequest):

const userId = req.auth_context.actor_id
const authType = req.auth_context.auth_identity_id

Response Methods

res.json()

Send JSON response:

res.json({ brand: { id: "brand_123" } })

res.status()

Set status code:

res.status(201).json({ brand })
res.status(404).json({ message: "Not found" })
res.status(204).send()

Using Query for Data Fetching

The Query service provides a powerful way to fetch related data:

import { ContainerRegistrationKeys } from "@medusajs/framework/utils"

export async function GET(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)

  const { data: brands } = await query.graph({
    entity: "brand",
    fields: [
      "id",
      "name",
      "description",
      "products.*",
      "products.variants.*",
    ],
    filters: {
      name: { $like: "%Nike%" },
    },
    pagination: {
      skip: 0,
      take: 20,
    },
  })

  res.json({ brands })
}

Error Handling

Use standard HTTP status codes and error responses:

import { MedusaError } from "@medusajs/framework/utils"

export async function GET(
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)

  const { data: brands } = await query.graph({
    entity: "brand",
    filters: { id: req.params.id },
  })

  if (!brands.length) {
    throw new MedusaError(
      MedusaError.Types.NOT_FOUND,
      `Brand with id ${req.params.id} was not found`
    )
  }

  res.json({ brand: brands[0] })
}

Best Practices

• Use AuthenticatedMedusaRequest for admin routes requiring authentication
• Execute workflows instead of calling services directly
• Use the Query service for complex data fetching
• Type your request and response for type safety
• Return appropriate HTTP status codes (200, 201, 204, 404, etc.)
• Use MedusaError for consistent error handling
• Keep route handlers thin - business logic belongs in workflows
• Access services via req.scope.resolve()

Next Steps

Create Workflows

Build business logic for your routes

Create Services

Implement module services