---
name: api-design
description: >
  Design or modify API routes, validated request/response schemas, error contracts, and API documentation within the existing project stack.
scope: global
---

# API design

1. Inspect the existing transport, schema library, auth, and error conventions.
   Keep domain logic independent of HTTP/framework request objects where practical.
2. Define inputs, outputs, status codes, authorization, and meaningful payload limits.
   Use runtime validation at untrusted boundaries; TypeScript interfaces alone do
   not validate requests. Derive limits from product needs and resource budgets.
3. Implement the route using existing services and data access patterns. Reuse
   existing dependency injection; do not introduce layers or repositories by default.
4. Preserve HTTP semantics and the project's error shape. Use Problem Details
   when adopting that format; otherwise document the existing structured contract.
   Serialize timestamps consistently with explicit timezone information.
5. Verify changed contracts and failure behavior under
   [shared verification](../../protocols/workflow.md#verification).

Read [security guidance](../app-security/SKILL.md) for affected untrusted boundaries,
not as a mandatory second audit. Validation and authorization failures reject the
request. A dependency fallback requires an explicit behavior contract; never infer
"fail open" merely because an endpoint is internal.