api

API

Designs and implements clean REST endpoints with Zod validation, consistent error handling, OpenAPI specs, and WebSocket protocols -- so every endpoint follows the same conventions.

Level	L1 Vibe Coder
Category	Domain Specialist
Model	Sonnet

---

What It Does

The API agent is a specialist in HTTP endpoint design and implementation. It encodes the conventions that make APIs consistent, predictable, and maintainable: RESTful URL structures, Zod schema validation at every boundary, structured error responses (never stack traces), proper status codes, and middleware patterns for cross-cutting concerns like authentication, logging, and rate limiting.

Without this agent, API endpoints accumulate inconsistencies over time. One endpoint returns { data: user }, another returns the user object directly. One validates with Zod, another uses manual if-checks. One returns 400 for validation errors, another returns 422. The API agent eliminates this drift by applying the same conventions to every endpoint: success responses wrapped in { data: T, meta?: {...} }, errors in { error: { code, message, details? } }, input validated with Zod schemas, and proper HTTP status codes (200 for reads, 201 for creates, 204 for deletes, 400 for validation, 404 for not found, 500 for server errors).

The agent also handles WebSocket protocol design for real-time features. It defines message formats with typed payloads ({ type: string, payload: unknown, timestamp: string }), connection lifecycle management, and reconnection strategies. For external API integrations (GitHub, Sentry, monitoring services), it implements proper HTTP clients with error handling, retry logic, and rate limit awareness.

When to Use It

• Adding a new endpoint: When you need a new REST endpoint with proper validation, error handling, and response formatting that matches your existing API conventions.
• Integrating an external API: When you need to connect to GitHub, Sentry, or any third-party service with proper error handling, retries, and rate limit management.
• Designing a WebSocket protocol: When you need real-time communication with typed message formats, connection lifecycle management, and reconnection logic.
• Standardizing existing endpoints: When your API has inconsistent response formats, error handling, or validation patterns and needs to be brought into alignment.