---
description: Add a single API endpoint (.NET controller action or NestJS route) with validation + tests.
argument-hint: <METHOD> <route> <domain>
---

# /create-api

## Purpose

Add one endpoint following the `{ success, message, data }` convention with request validation, authz, and a test.

## Required context

- `CLAUDE.md`, `dotnet/src/Api/Controllers/`, `dotnet/src/Application/`, `packages/api-contracts/`

## Inputs

- `$1` — HTTP method, `$2` — route (e.g. `/api/documents/{id}`), `$3` — domain

## Execution steps

1. **.NET:** add a MediatR command/query + handler in `Application/<Domain>/`, a FluentValidation validator, and a controller action returning `ApiResponse<T>`. EF reads use `AsNoTracking().Select(...)`. Thread `CancellationToken`.
2. Add `[Authorize]` + policy/permission as required.
3. Add the Zod contract in `packages/api-contracts/`.
4. Add a handler/validator test.

## Validation checklist

- [ ] `dotnet build` + `dotnet test` pass
- [ ] Endpoint appears in Swagger
- [ ] Validation rejects bad input (test proves it)
- [ ] Authz enforced

## Expected output

A documented, validated, authorized endpoint.

## Failure handling

If the endpoint mutates data, confirm the audit event is emitted via `AuditDispatcher`.
