APIs are where a small AI-written change can break someone else's app: a renamed field, a stricter validator, a different error shape. This agent treats the contract as the product and reports the compatibility impact of each change explicitly.
When to use the API Engineer agent
- Adding new REST or GraphQL endpoints
- Changing an endpoint that mobile apps or partners already call
- Reviewing an API for security and consistency
- Integrating a third-party API
What is in the agent file
| Name | api-engineer |
|---|---|
| Tools | Read, Write, Edit, Grep, Glob, Bash. It can edit files and run commands, so review its diff. |
| Model | sonnet, up to 40 turns per task |
| Kit | Engineer kit, 109 lines |
How it works. Beyond its role statement, the file sets out 4 rules it follows: Breaking change classification; Severity rubric for API review; Contract defaults; Authorization.
What it reports. Every run ends in the same structure: Change summary, Contract, Compatibility, Validation performed, Findings, Remaining risks.
Excerpt from the agent file
The settings and opening instructions, as they appear in .claude/agents/api-engineer.md:
---
name: api-engineer
description: Designs and implements HTTP and GraphQL APIs — contracts, validation, error semantics, authentication, pagination, idempotency and backward compatibility. Invoke by name for new endpoints, API reviews, integration work, or when changing anything a client already depends on.
model: sonnet
maxTurns: 40
tools: Read, Write, Edit, Grep, Glob, Bash
---
You are an API Engineer. Your job is to design and implement APIs that clients can rely on, and to change existing ones without breaking them.
When given an API task:
1. Identify every existing consumer of what you are about to touch. Grep the repo for the route, the client SDK, and any generated types. An API with unknown consumers is one you cannot safely change.
2. Read the adjacent endpoints first. Naming, envelope shape, error format, auth mechanism and pagination style must match what is already there — an inconsistency is a permanent tax on every client.
3. Classify the change as additive or breaking before writing code (table below).
4. Design the contract: resource shape, status codes, error codes, pagination, idempotency.
5. Implement with validation at the trust boundary, authorization on the resource, and errors that clients can branch on.
6. Test the unhappy paths — invalid input, wrong role, cross-tenant id, duplicate submit, missing optional fields.
7. Document the contract and report the compatibility classification explicitly.The full file continues with the rules above and the exact report format. It is included in the Agentsforce kit.
Example requests
Name the agent to be sure Claude uses it, or describe the task and let its description trigger it:
- "Use api-engineer to add a paginated GET /orders endpoint that matches our existing style."
- "We want to rename customer_id to account_id. Is that breaking, and how do we roll it out?"
- "Use api-engineer to review the webhooks endpoint for auth and idempotency problems."
- "Design the GraphQL mutation for updating a team's billing email."
When to use a different agent
| If you need | Use instead |
|---|---|
| Database schema and migrations behind the API | Use database-engineer |
| Payment provider integration and webhooks for billing | Use payments-billing-engineer |
| Exposing an API to AI assistants as an MCP server | Use mcp-server-engineer |
Works well with
- Database Engineer: changes schemas and queries without risking your data
- Code Reviewer: checks what a change did, not whether a file looks fine
- Tech Lead: plans work instead of writing it
Related playbooks in the kit, which Claude loads when the task calls for them: rest-api-design, api-versioning, graphql-schema-design, auth-patterns.
How to get it
- Write your own: the free Subagent Generator drafts a starter api engineer file you can edit and save in
.claude/agents/. - Use the tested version: Agentsforce includes this agent with 54 other specialists and 89 playbooks for a one-time $49, installed with one command.
Frequently asked questions
Does it support both REST and GraphQL?
Yes. Its description covers HTTP and GraphQL APIs, and the kit includes separate playbooks for REST design and GraphQL schema design that it can draw on.
How does it handle breaking changes?
It classifies each change against a breaking-change table before writing it, and for breaking ones proposes a versioned or additive path instead of changing the contract in place.
Will it check authorization?
Yes. Its rule is that authorization is checked on the resource, not only authentication on the request, which is the gap that lets one user read another account's data.