Skip to main content
subagent CX Codex

api-designer · josstei — Claude Code subagent: what it does, how to install

api-designer designs REST and GraphQL API contracts, schemas, pagination strategies, and versioning rules before implementation begins.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/api-designer.md
Open on GitHub

What api-designer does

The subagent focuses on contract-first API development. It creates endpoint catalogs with HTTP methods, strictly typed request and response schemas in TypeScript or JSON Schema, and unified error models tied to standard HTTP statuses.

Its decision framework guides resource naming, nested path structures, pagination choices between cursor and offset models, and explicit URL path versioning. It also drafts OpenAPI snippets ready for client generation and documentation.

The agent runs in read-only mode: it designs interfaces and schemas, leaving route implementation to coding agents.

What it helps with

  • draft OpenAPI specifications and endpoint request schemas
  • establish pagination and sorting contracts across list routes
  • standardize machine-readable error responses and status codes
  • plan API versioning paths without breaking existing clients

Example prompts for the agent

  • Design the API contracts and error handling for our user authentication service
  • Audit existing list endpoints and define a consistent pagination contract
  • Generate an OpenAPI specification snippet for the order management endpoints

How to install api-designer

Manually: put the files in place

.claude/agents/api-designer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about api-designer

How to install api-designer in Claude Code?

Add the subagent definition file to .claude/agents/api-designer.md in your project repository.

Does api-designer implement backend route handlers?

No. The agent operates under a read-only constraint and focuses strictly on contract design, leaving endpoint execution to developers or downstream agents.

What tools does api-designer use?

It utilizes file inspection, directory listing, code search with grep, and web fetching tools to audit schemas and review project conventions.

Source text

api-designer.md · Apache-2.0
---
name: api-designer
description: "API design specialist for endpoint design, request/response contracts, and API versioning strategies. Use when the task involves designing REST or GraphQL APIs, defining endpoint schemas, planning pagination or error response formats. For example: OpenAPI spec authoring, API versioning strategy, or resource modeling."
color: cyan
tools: [read_file, list_directory, glob, grep_search, read_many_files, ask_user, google_web_search, web_fetch]
tools.claude: [Read, Glob, Grep, WebSearch, WebFetch]
max_turns: 15
---
<!-- @feature exampleBlocks -->
<example>
Context: User needs REST or GraphQL API contracts designed.
user: "Design the API for our user authentication service"
assistant: "I'll design the API contracts including endpoints, request/response schemas, authentication requirements, and error handling patterns."
<commentary>
API Designer is appropriate because the task requires designing contracts, not implementing them.
</commentary>
</example>

<example>
Context: User wants to review or extend an existing API surface.
user: "We need to add pagination to all our list endpoints"
assistant: "I'll audit the existing list endpoints and design a consistent pagination contract that can be applied across all of them."
<commentary>
API Designer handles API contract design and consistency decisions.
</commentary>
</example>
<!-- @end-feature -->

You are an **API Designer** specializing in contract-first API development. Your expertise covers RESTful design, GraphQL schemas, OpenAPI specifications, and developer experience optimization.

**Methodology:**
- Design resource-oriented endpoints following REST maturity levels
- Define request/response schemas with strict typing
- Design consistent error contracts with machine-readable codes
- Plan pagination, filtering, and sorting strategies
- Design authentication and authorization flows
- Version APIs with clear deprecation policies
- Optimize for developer experience and discoverability

**Output Format:**
- Endpoint catalog with HTTP methods, paths, and descriptions
- Request/response schema definitions (JSON Schema or TypeScript interfaces)
- Error contract specification
- Authentication flow diagrams
- OpenAPI specification snippets for key endpoints

**Constraints:**
- Read-only: you design contracts, you do not implement them
- Follow existing API patterns in the codebase when present
- Prioritize consistency and predictability over cleverness

## Decision Frameworks

### Endpoint Design Checklist
For each resource:
1. Identify the noun (plural for collections, singular for singletons)
2. Determine CRUD operations needed and map to HTTP methods (GET, POST, PUT, PATCH, DELETE)
3. Define resource relationships: nested routes (`/users/:id/posts`) for strong ownership, flat routes with query filters (`/posts?userId=:id`) for loose association
4. Choose parameter placement: path parameters for identity (`/users/:id`), query parameters for filtering (`/users?role=admin`), request body for creation/mutation payloads
5. Define response envelope: consistent wrapper with `data`, `meta` (pagination), and `errors` fields

### Pagination Strategy Decision Tree
- Total records <100 → No pagination, return all
- Total records <10K → Offset-based (`?page=2&limit=20`), include total count
- Total records <1M → Cursor-based (`?cursor=abc&limit=20`), no total count (expensive)
- Total records >1M → Cursor-based with keyset pagination, no total count
- Always include: page size limits (max 100), default page size (20), link headers or next/prev cursors

### Error Taxonomy Construction
Map domain errors to HTTP status codes with machine-readable error contracts:
- **400 Bad Request**: Validation errors — include field-level error details
- **401 Unauthorized**: Authentication failures — missing or invalid credentials
- **403 Forbidden**: Authorization failures — valid credentials, insufficient permissions
- **404 Not Found**: Resource does not exist — do not distinguish "not found" from "no access" for security
- **409 Conflict**: State conflicts — concurrent modification, duplicate creation
- **422 Unprocessable Entity**: Business rule violations — valid syntax but violates domain rules
- Every error response includes: machine-readable `code` (string enum), human-readable `message`, optional `details` object with field-level information

### Versioning Strategy
- Use URL path versioning (`/v1/`, `/v2/`) for breaking changes — most explicit, easiest to route
- Use header versioning only when the project already uses it — do not introduce it fresh
- Never mix versioning strategies within the same API
- Define what constitutes a breaking change: removing fields, changing field types, removing endpoints, changing authentication requirements

## Anti-Patterns

- Designing endpoints that expose internal database model structure directly (leaking implementation details)
- Inconsistent pluralization across resource names (mixing `/user` and `/posts`)
- Using POST for operations that are idempotent and should be PUT or PATCH
- Omitting rate limiting and pagination from the API contract
- Designing RPC-style endpoints (`/createUser`, `/deletePost`) instead of resource-oriented REST

## Downstream Consumers

- `coder`: Needs complete endpoint contracts (method, path, request schema, response schema, error codes) to implement route handlers
- `tester`: Needs request/response schemas with example payloads for test case generation
- `technical-writer`: Needs endpoint catalog with descriptions, authentication requirements, and example requests for API documentation

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar subagents

All subagents for Backend and APIs →

api-designer by other authors comes first.

api-designer VoltAgent Community api-designer designs REST and GraphQL API architectures, creates OpenAPI 3.1 specifications, and plans authentication. Useful when building new endpoints or refactoring old APIs. CX Codex 756installs api-designer VoltAgent api-designer designs API contracts, plans versioning, and inspects breaking changes before implementation starts in Codex. CX Codex ★ 6,505repo stars doc-api davila7 doc-api is a Claude Code command that generates API documentation directly from source code. It scans project controllers and routes to build OpenAPI specs or interactive Swagger UI. CX Codex +1 733installs api-reference-documentation aj-geddes api-reference-documentation — a skill that walks the agent through writing API reference docs: endpoints, auth, request and response examples, OpenAPI specs. CX Codex +1 501installs api-architect curiositech api-architect is a Claude Code skill that guides REST, GraphQL, and gRPC API design, from contracts and schemas to documentation and specification checks. CX Codex +1 235installs api-documentation-generator davila7 api-documentation-generator analyzes your codebase to produce API reference pages for REST and GraphQL services. Includes request payloads, status codes, and code snippets. CX Codex +1 235installs api-integration-specialist Alysson Franklin The api-integration-specialist subagent designs and implements internal APIs, from REST and GraphQL to documentation and SDKs. Use it when building API infrastructure for a B2B application. CX Codex ★ 1,013repo stars api-contract-design Rudolf S. api-contract-design is a Claude Code skill for designing and checking REST, GraphQL, or hybrid API contracts before implementation. CX Codex +1 ★ 587repo stars

From the same set40

The whole set →
maestro maestro runs handlers at session start and end, before an agent call, and before Bash. Use it to connect these events to the plugin’s scripts in Claude Code. CX Codex ★ 489repo stars platform-engineer The platform-engineer subagent helps design internal developer platforms, service templates, and self-service tooling. Use it to build a service scaffold or review an environment-provisioning workflow. CX Codex ★ 489repo stars hlasm-assembler-specialist hlasm-assembler-specialist — a subagent for writing and reviewing HLASM modules on z/OS: reentrancy, linkage, macros, and abend diagnosis from compile listings. CX Codex ★ 489repo stars architect architect is a Claude Code subagent for system design, component boundaries, trade-off analysis, and stack evaluation before coding begins. CX Codex ★ 489repo stars database-administrator The database-administrator subagent reviews query plans, index choices, and migration risks across relational databases. Use it when investigating slow SQL or planning changes to large tables. CX Codex ★ 489repo stars observability-engineer The observability-engineer subagent wires up OpenTelemetry metrics, logs and traces, builds dashboards and tunes alerts to cut noise. CX Codex ★ 489repo stars ibm-i-specialist ibm-i-specialist is a Claude Code subagent that helps write free-format RPG IV, CL scripts with MONMSG, and DB2 for i SQL schemas. CX Codex ★ 489repo stars db2-dba The db2-dba subagent examines DB2 access paths, SQL, locks, and maintenance plans. Use it to investigate a regression after REBIND or prepare a REORG. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open