Skip to main content
subagent CX Codex

api-designer · voltagent/awesome-codex-subagents — Codex subagent: what it does, how to install

api-designer designs API contracts, plans versioning, and inspects breaking changes before implementation starts in Codex.

MIT ★ 6,505 updated 2026-10-05

Install into Codex · Manually: put the files in place All methods and platforms ↓
.codex/agents/api-designer.toml
Open on GitHub

What api-designer does

This subagent treats APIs as durable contracts between independently evolving producers and consumers. It maps actor flows, checks service ownership boundaries, and drafts the smallest schema needed to satisfy product requirements. Core checks cover error taxonomy, request validation, tenant scoping, idempotency keys, and pagination patterns.

The review stage separates transport payloads from database storage schemas to prevent accidental coupling. For each critical endpoint, it produces canonical success and failure responses while mapping out concrete migration steps for field deprecations. The subagent will not write implementation code unless the parent agent explicitly requests it.

What it helps with

  • draft new API contracts before backend implementation starts
  • spot client-breaking changes in existing endpoint schemas
  • define idempotency and retry semantics for mutating actions
  • plan deprecation paths and field migrations across client releases

Example prompts for the agent

  • Review our checkout endpoint payload for backwards compatibility issues
  • Draft an API contract for organization billing with tenant scoping rules
  • Define standard error codes and pagination parameters for the search API

How to install api-designer

Manually: put the files in place

.codex/agents/api-designer.toml

Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

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 Codex?

Add the subagent definition file to your workspace at .codex/agents/api-designer.toml.

What does api-designer do?

It maps domain resources, reviews schema clarity, inspects breaking changes, and delivers API contract drafts with migration notes.

Does api-designer generate endpoint implementation code?

No, it focuses strictly on contract design and boundary validation. It avoids coding unless the parent agent specifically asks for implementation.

Source text

api-designer.toml · MIT
# api-designer

Use when a task needs API contract design, evolution planning, or compatibility review before implementation starts.

Design APIs as long-lived contracts between independently evolving producers and consumers.

Working mode:
1. Map actor flows, ownership boundaries, and current contract surface.
2. Propose the smallest contract that supports the required behavior.
3. Evaluate compatibility, migration, and operational consequences before coding.

Focus on:
- resource and endpoint modeling aligned to domain boundaries
- request and response schema clarity
- validation semantics and error model consistency
- auth, authorization, and tenant-scoping expectations in the contract
- pagination, filtering, sorting, and partial response strategy where relevant
- idempotency and retry behavior for mutating operations
- versioning and deprecation strategy
- observability-relevant contract signals (correlation keys, stable error codes)

Architecture checks:
- ensure contract behavior is explicit, not framework-default ambiguity
- isolate transport contract from internal storage schema where possible
- identify client-breaking changes and hidden coupling
- call out where "one endpoint" would blur ownership and increase long-term cost

Quality checks:
- provide one canonical success response and one canonical failure response per critical operation
- confirm field optionality/nullability reflects real behavior
- verify error taxonomy is actionable for clients
- describe migration path for changed fields or semantics

Return:
- proposed contract changes or new contract draft
- rationale tied to domain and client impact
- compatibility and migration notes
- unresolved product decisions that block safe implementation

Do not implement code unless explicitly asked by the parent agent.

© VoltAgent · MIT · VoltAgent/awesome-codex-subagents

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 josstei api-designer designs REST and GraphQL API contracts, schemas, pagination strategies, and versioning rules before implementation begins. CX Codex ★ 489repo stars api-design-patterns bobmatnyc The api-design-patterns skill for Claude Code is an architectural reference for REST, GraphQL, and gRPC, guiding endpoint structure, pagination, versioning, and error payloads. CX Codex +1 585installs graphql-schema-designer patricio0312rev graphql-schema-designer is a Claude Code skill for shaping GraphQL APIs with types, queries, mutations, subscriptions, and resolvers. It activates for requests about schema design, GraphQL setup, or Apollo Server. CX Codex +1 230installs API Designer daffy0208 API Designer guides REST and GraphQL design with consistent resource naming, standard error formats, and pagination patterns. CX Codex +1 204installs api-and-interface-design addyosmani api-and-interface-design guides API and module-boundary design with explicit contracts, validation, and consistent errors. Use it for REST, GraphQL, or public interfaces. CX Codex +1 79,800installs public-api-design-review Samuel Berthe public-api-design-review runs a REST API surface, shipped or still on paper, through an eight-part checklist and splits every finding into Must-change or Improvement. CX Codex +1 10,200installs data360-schema-get forcedotcom data360-schema-get — a skill for Claude Code and other AI editors that retrieves schema definitions for Data Lake Objects (DLO) and Data Model Objects (DMO) from Salesforce Data Cloud via REST API. CX Codex +1 5,100installs

From the same set176

The whole set →
graphql-architect graphql-architect — a subagent that audits GraphQL schemas for architectural flaws, performance risks, and security gaps. Guides schema evolution, resolver design, and federation without breaking clients. CX Codex ★ 6,505repo stars fullstack-developer fullstack-developer handles bounded cross-layer features from user actions down to backend effects and UI updates. Useful when a single worker needs to own the full integration path. CX Codex ★ 6,505repo stars frontend-developer frontend-developer — a scoped subagent for frontend changes and UI bug fixes, with checks for state integrity, accessibility, and nearby regressions. CX Codex ★ 6,505repo stars electron-pro electron-pro — a subagent for Electron development: helps map responsibility across main, preload, and renderer processes, design IPC bridges, verify security boundaries, and validate packaging assumptions. CX Codex ★ 6,505repo stars design-bridge design-bridge converts DESIGN.md documents into precise, structured UI instructions for implementation agents. CX Codex ★ 6,505repo stars code-mapper The code-mapper subagent maps code paths, ownership boundaries, and execution flow before edits. Use it when behavior is spread across several layers. CX Codex ★ 6,505repo stars backend-developer backend-developer is a Codex subagent for scoped backend implementation and bug fixes once the owning code path is known. It checks a success case and a high-risk failure path. CX Codex ★ 6,505repo stars healthcare-admin This Codex subagent handles healthcare administration work, including medical coding, compliance reviews, and payer contract analysis. Use it when a task concerns healthcare operations rather than general software development. CX Codex ★ 6,505repo stars

Project sponsors

Companies that keep this analytics open