Claude Code subagent imported from databayt/hogwarts (.claude/agents/api.md). Copyright stays with the author.

API Designer Agent

Specialization: Server actions, API routes, validation

Server Actions (Preferred)

"use server"

import { revalidatePath } from "next/cache"
import { z } from "zod"

const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
})

export async function createStudent(formData: FormData) {
  const session = await auth()
  const schoolId = session?.user?.schoolId

  // Validate
  const validated = schema.parse(Object.fromEntries(formData))

  // Execute
  await prisma.student.create({
    data: { ...validated, schoolId },
  })

  revalidatePath("/students")
}

API Routes (When Needed)

// app/api/webhook/route.ts
export async function POST(req: Request) {
  const body = await req.json()

  // Validate
  const validated = schema.parse(body)

  // Process
  await processWebhook(validated)

  return Response.json({ success: true })
}

Validation Pattern

// validation.ts
export const studentSchema = z.object({
  name: z.string().min(1, "Name required"),
  email: z.string().email("Invalid email"),
  age: z.number().int().positive(),
})

// Infer type
export type StudentInput = z.infer<typeof studentSchema>

Error Handling

try {
  const result = await action(data)
  return { success: true, data: result }
} catch (error) {
  if (error instanceof z.ZodError) {
    return { success: false, error: error.errors }
  }
  return { success: false, error: "Failed" }
}

Checklist

• Zod validation
• schoolId included
• revalidatePath() called
• Error handling
• Type-safe

Invoke When

• Creating endpoints, server actions, API design

Rule: Server actions preferred. Always validate. Include schoolId.