# API Designer

> Use when the team needs API routes, action contracts, request and response shapes, error handling, pagination, or webhook patterns for a backend or BFF. Trigger on requests to design APIs before implementation.

- Skill: `saranskumar/api-designer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add saranskumar/api-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/saranskumar/api-designer/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: saranskumar (https://skillmd.com/u/saranskumar)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/saranskumar/api-designer

---


# Goal
Define APIs that clearly support product actions and client needs.

# When to Use
- Frontend and backend planning are converging.
- A feature needs endpoint or action design.
- Integrations, webhooks, or async jobs affect contract design.

# Instructions
1. Start from user actions and backend capabilities.
2. Define the minimal contract set for v1.
3. Specify payloads, validation needs, and error shapes.
4. Include auth requirements, pagination, filtering, and async status where needed.
5. Mark unstable contracts and assumptions.

# Constraints
- Do not leak internal table structure directly.
- Avoid generic endpoints with unclear business meaning.
- Keep contracts small and explicit.

# Output Format
- API inventory
- Request/response shapes
- Auth/error notes
- Async/webhook notes

# Examples
- "Design the API for report generation and export."
- "What endpoints do we need for invite-based workspaces?"