Hire an AI API platform engineer

Everything it can hand back

Your task sets the actual outputs. The specialist picks the methods that cover them.

• A resource list and one set of rules for naming, dates, IDs, paging and errors.
• A draft contract outline, or a review of yours with inconsistencies marked.
• A safe and breaking list for every change you gave it.
• A versioning and deprecation plan with steps, signals and a sunset rule.
• A rate limit and quota design, with the headers to send and the 429 response.
• An SDK, docs and quickstart plan, with checks to run on every spec change.

How it does the job well

• Leave deep identity and security design to a security specialist. Say so when it comes up.
• A published API is a contract you cannot silently break. Once a consumer integrates, their working code defines your compatibility surface. Additive changes are safe; changing or removing anything they rely on is a breaking change that requires a new version and a migration path.
• Design contract-first, review for the long haul. The spec comes before the implementation and gets scrutinized for naming consistency, resource modeling, and "could we live with this for a decade?" — because you will. Retrofitting a spec onto shipped code bakes in every inconsistency.
• Be consistent to the point of boredom. Field naming (pick snake_case or camelCase and never waver), date formats (ISO 8601, always), pagination style, error shape, and ID formats must be identical across every endpoint. Surprise is the enemy of DX.
• Deprecate with a runway, not a cliff. Announce, document the migration, set a sunset date far enough out to be humane, emit deprecation signals (headers, logs), and monitor remaining usage before you actually remove anything.
• Read the existing code, its conventions and its tests before changing anything. Match the project's patterns.
• Make the smallest change that fully solves the request. Keep unrelated refactors out.

Mistakes it avoids

• Claiming code works without running it or its tests.
• Inventing APIs, package versions or settings instead of checking the installed ones.
• Changing behaviour outside the request, such as reformatting whole files or renaming public interfaces.

What a good result looks like

An example, not your task: You are about to open an API to partners or customers and want the contract right before the first user.

• Resources and conventions. Each resource and the single set of rules for names, dates, IDs, paging and errors.
• Contract draft or review. An endpoint outline, or your spec with each inconsistency marked.
• Compatibility list. Each proposed change marked safe or breaking, with the reason and next step.
• Versioning and deprecation plan. The version rule and the steps from announcement to sunset, with signals and a usage watch.
• Gateway rules. Sign-in, rate limits, quotas, the headers to send and the reply when a limit is hit.
• SDK, docs and quickstart. How SDKs and docs are made from the spec, and the path to a first successful call.

How the work is checked

• The changed files build, and the relevant tests and linters pass. The commands and results are shown.
• Each change is explained in one line with its reason, and risky areas are named.
• Any check that could not run is reported as NOT_RUN with what it needs.
• States which checks passed, failed or could not run, and names missing inputs.

These checks have not been run against a model yet. Your AI uses them to check its own work.

A second opinion

Before it hands back, your AI reviews the draft the way Kent Beck and Margaret Hamilton would. This is a way of reviewing the work. It does not mean they wrote or endorse it.

Capabilities

• Model the resources. It lists the things the API handles, how they relate and how they change over time, before it names any endpoint.
• Fix the shared rules. It sets one style for names, dates, IDs, paging, errors, retries and sign-in, and checks every endpoint against it.
• Sort each change. It marks every change safe or breaking, using the rules in the profile, and says why.
• Plan versions and deprecation. Breaking changes get a new major version, a migration guide, warning headers, a usage watch and a sunset date.
• Design the gateway rules. It plans sign-in, rate limits, quotas and error replies, including the headers clients need.
• Plan SDKs, docs and quickstart. It plans typed SDKs and docs made from the spec, and a short path to a first successful call.
• List the checks. It lists automatic checks for CI that catch breaking changes before release.

How the role works

1. Checks your task, context and available tools.
2. Picks the methods needed and prepares a work plan.
3. Carries out supported tasks, with each method's limits and review gates.
4. Checks the real deliverables and corrects supported faults.
5. Hands back files, evidence and unresolved gaps.

Your specialist's working setup

Download the base specialist without a task form or account. README.md and SETUP.md explain how to use the folder. SOUL.md defines its scope. INTAKE.md asks missing questions inside your AI. PLAYBOOK.md, SKILLS.md, BEST_PRACTICES.md, CHECKS.md and HANDOFF.md guide the work and its checked deliverables.

Complete associated skills, supporting files and licences are included. Choose only the methods needed for the actual task. Keep context, working files and accepted feedback in your AI project.

Use this specialist through MCP or the API

Call prepare_specialist with role_id engineering-api-platform-engineer only. No task is required to load it. Your AI asks what job you need done, what you want back and which relevant context it can use.

For task-led hiring, call find_specialist, explain the suggested specialists and let the user accept or change the team.

Complete ZIP: Download base specialist. API: GET /api/v1/specialists/engineering-api-platform-engineer/pack. The host AI supplies its own model, tools and execution; a pack does not connect accounts or run a task.

Inputs and helpful context

The specialist starts from the task brief. Only active methods require their inputs.

For the primary method, when used

• What the API does, who will call it and whether it is public, partner or internal.
• Your current spec or a list of endpoints, if you have one (optional).
• The changes you are considering, such as a rename, a new field or a removal (optional).
• How many outside developers use it and how they integrate, if known (optional).
• The languages your developers use, so the SDK plan targets them.
• Your sign-in method and any limits you already enforce.

Helpful context (optional)

• Your existing OpenAPI file.
• Usage logs showing which developers call which endpoints.
• Past support tickets about errors and limits.

Tools and access

• Claude, ChatGPT or Gemini with file upload: You can attach a full OpenAPI file and get a line-by-line review.
• An OpenAPI validator: It catches errors in a spec that reading cannot, such as a missing reference.

Functions and deliverables

• API platform engineer agent: Get a plan for a public or partner API with contract rules, a breaking-change list, a versioning policy, rate limits and an SDK plan.
  • A resource list and one set of rules for naming, dates, IDs, paging and errors.
  • A draft contract outline, or a review of yours with inconsistencies marked.
  • A safe and breaking list for every change you gave it.
  • A versioning and deprecation plan with steps, signals and a sunset rule.
  • A rate limit and quota design, with the headers to send and the 429 response.
  • An SDK, docs and quickstart plan, with checks to run on every spec change.
  Source: Michael Sitarzewski and Agency Agents contributors.
• API design reviewer: Give it your API spec. Get a scorecard, flagged breaking changes and fixes for naming and errors.
  • A letter grade with a scorecard
  • A list of naming, URL and error format problems
  • A list of breaking changes between two versions
  • Fixes to make, then a re-check until the results pass
  Source: Alireza Rezvani.
• API spec writer: Share routes, code or an API description. Get an OpenAPI or Swagger spec with schemas, errors and sign-in rules to validate.
  • A complete OpenAPI or Swagger file
  • Endpoints with request and response shapes
  • Security setup
  • Reusable data schemas
  Source: sickn33.
• API designer: Design a clear, stable API for your code. Say what it must do and who calls it. You get a written contract with types and error shapes.
  • A written contract for the interface: its actions, their typed inputs and results, and the errors each can return
  • Clear names, types and error shapes
  • Notes on what to hide
  • A plan for changing it later
  Source: Addy Osmani.
• AI project context organiser: Share your project and next task. Get a short rules file, a focused file list and a clear handoff for later sessions.
  • A ready rules file for your project
  • A list of which files to load for each task
  • Rules for when to reset or trim the session
  • A checklist for spotting drifting answers
  Source: Addy Osmani.
• Kent Beck: Plan a software change using Kent Beck’s recorded approach. List the cases, take small steps and keep code tidying separate from new behaviour.
  • Your problem worked on the way Kent Beck would: their questions, their method, their push-back
  • The answer or the work, in Kent Beck's voice, using their ideas by name
  • Anything that goes beyond their public record, marked
  • One suggested next step
• Margaret Hamilton: Review a system failure plan using Margaret Hamilton’s recorded approach. Check handoffs, priorities, warnings and what happens when people make mistakes.
  • Your problem worked on the way Margaret Hamilton would: their questions, their method, their push-back
  • The answer or the work, in Margaret Hamilton's voice, using their ideas by name
  • Anything that goes beyond their public record, marked
  • One suggested next step

Tasks you can use it for

• You are about to open an API to partners or customers and want the contract right before the first user.
• Your team wants to rename a field and needs to know if it breaks anyone.
• You need a policy for versions, deprecation and sunset dates that you can publish.
• Partners complain about vague errors, surprise limits or inconsistent field names.

Limits to check before starting

• You are designing a simple REST API for your own app only. Use the REST API designer.
• You have code and only need an OpenAPI file written from it. Use the API spec writer.
• You want one planned change checked before you ship it. Use the Breaking change reviewer.
• You need the database and services behind the API. Use the Backend Architect agent.
• You need live debugging of a failing API or production changes. Ask an engineer with access to your systems.

Best way to use this role

Give it one clear outcome, the actual files and a definition of done. Keep the work in one AI project so it can reuse checked context and earlier files.

• Download the pack from this page and add it to your AI as a skill. Or paste SKILL.md into a new chat, then paste references/source-agent.md after it.
• Paste your spec or endpoint list. If you have none, describe the resources the API handles and who calls it.
• Add the changes you are weighing. Say "Review these changes for breaking impact" or "Draft the contract rules."
• Your AI asks once for anything missing. Unknowns such as user counts stay marked as unknown.
• Read the breaking-change list first. Any change marked breaking needs the version plan before it ships.
• Have an engineer check the draft with an OpenAPI validator and a spec-diff tool. The agent does not run them.

Read it as data

Read the complete role setup as JSON. Connect your AI to the AI Blocks MCP library and read aiblocks://roles/engineering-api-platform-engineer for its role instructions and pinned sources.

This is a prepared AI role. No task has run. Your AI carries out authorized work using its available tools and reports the actual deliverables and checks.