# How to regenerate API clients without breaking callers
> API client generation should start from a reviewed OpenAPI contract, use a pinned generator, prove the output is reproducible, and compile real consumers before release. Learn the workflow for agent-run regeneration with Factory Droid Exec and review.
URL: https://factory.com/articles/api-client-generation-coding-agents
Published: 2026-09-25
Updated: 2026-10-23
To regenerate an API client safely, run a pinned generator and configuration against the reviewed OpenAPI contract in a clean workspace, run it twice to confirm the output does not change, then compile a representative consumer and run contract tests before release. The public method signatures decide the release, whatever the size of the generated diff.
Suppose a generator upgrade produces a large API client diff and renames one public method that an application calls. Generation succeeds, but the consumer no longer compiles. A coding agent must separate the mechanical regeneration from the compatibility decision that determines whether the client can be released.
Keep the service contract as the source of truth. Pin the generator and configuration, define which outputs belong in version control, and fix generator inputs rather than hand-editing emitted code. [OpenAPI Generator's usage guide](https://openapi-generator.tech/docs/usage/) documents the invocation options that a repository can reduce to one repeatable command.
## Bound the API client generation task
Start with the reviewed OpenAPI document, target language, generator name, generator version, configuration file, and exact command. State which generated directory may change and whether generated files are committed or published as a package.
Separate contract changes from generator upgrades when possible. If both move in one pull request, reviewers cannot easily tell whether a diff came from an API decision or a tooling change. When an endpoint changes, classify it as additive, deprecated, or breaking before regeneration.
Factory’s [AGENTS.md guidance](https://docs.factory.com/harness/agents-md) supports repository-scoped commands and completion checks. Put the canonical generation command and the rule against hand edits near the generated directory so a coding agent encounters them before making changes.
## Regenerate and test the artifact
Run generation from the pinned inputs in a clean workspace, then run it again and require no additional diff. Investigate changing timestamps, template versions, or local configuration when output keeps moving. A stable second run establishes repeatability for those inputs, not compatibility with an existing consumer.
The full regeneration path has a few fixed steps, and a failure at any one stops the release.
Reviewed OpenAPI contract"]
B["Pinned generator and config
clean workspace"]
C["Second run
no additional diff"]
D["Compile the client"]
E["Compile a real consumer
plus contract tests"]
F["Release decision
based on public API changes"]
A --> B --> C --> D --> E --> F
`}
/>
Compile the client and run contract-focused tests against a controlled server or mock. Test representative success and error responses, optional fields, pagination, and serialization boundaries. A successful generator command proves only that files were emitted.
For the renamed-method example, compile a representative consumer against the regenerated client. A client can compile internally while its public interface breaks callers. Add a check for the method signature and request serialization that the consumer depends on.
## Review API client generation as a release
Compare both the service contract and the generated public API with the previous release. Method names, required fields, nullability, and enum handling can change the consumer contract even when the server remains compatible. Decide whether to preserve the old interface through approved generator configuration or release a breaking client update with migration guidance.
Generated volume can hide a small consequential change. Ask the agent to summarize the contract delta, generator delta, dependency delta, and validation results separately. Keep the raw generated diff available, but give reviewers a short map to the files that define public behavior.
A short summary in a fixed shape gives reviewers that map.
| Delta | What to report |
| --- | --- |
| Contract | Endpoints added, deprecated, or broken |
| Generator | Version, template, and configuration changes |
| Dependencies | Runtime packages the client now pulls in |
| Validation | Commands run and their results |
Choose the client package version from the compatibility impact, not from the size of the generated diff. Publish only after the contract and generated artifact are both approved. If multiple language clients share one contract, update them in coordinated, separately testable changes rather than assuming one successful target proves the rest.
## How Factory runs client regeneration
Factory is a platform for running a software factory, where agents called Droids take work from a signal to a reviewed pull request. A contract change is a good signal for that path, because the regeneration steps are the same every time.
**Trigger on contract changes.** A custom GitHub automation in [Factory Automations](https://docs.factory.com/software-factory/automations) runs in GitHub Actions and can start on events such as a new push to a branch or a label change. A team can use one to regenerate clients whenever the reviewed contract moves.
**Run the command headless.** [Droid Exec](https://docs.factory.com/droid-exec/overview) runs the repository's generation command as one non-interactive pass. `--auto low` allows file edits, and `--auto medium` adds builds and tests, so the autonomy level can match the step. CI should still regenerate and fail when committed output is stale.
**Review templates like source.** Factory's [automated code review](https://docs.factory.com/software-factory/code-review-ci) posts inline comments on the pull request. A `review-guidelines` skill can ask it to treat handwritten templates and generator configuration with the same care as application code, and to flag hand edits in generated directories.
If multiple language clients share one contract, update them in coordinated, separately testable changes. A [Mission](https://docs.factory.com/missions/overview) can track each client as its own feature with validation at the end of each milestone.
## Frequently asked questions
### What is API client generation?
API client generation produces client libraries from a service contract such as an OpenAPI document, using a generator and configuration instead of hand-written code.
### Should generated client code be edited by hand?
No. Fix the generator inputs, templates, or configuration instead, and document the rule next to the generated directory so agents and people see it before editing.
### How do you know a regenerated client is compatible?
Compare the generated public API with the previous release and compile a representative consumer against it. Method names, required fields, nullability, and enum handling can break callers even when the server is compatible.
### How does Factory automate API client regeneration?
A Factory GitHub automation can start on events such as a push to a branch, Droid Exec runs the pinned generation command headless, and automated code review checks the pull request before release.
## Further reading
- [Protobuf compatibility](https://factory.com/articles/protobuf-compatibility-coding-agents)
- [Protecting API compatibility](https://factory.com/articles/api-compatibility-coding-agents)
- [Reviewing agent-generated pull requests](https://factory.com/articles/reviewing-agent-generated-pull-requests)
- [Test impact analysis](https://factory.com/articles/test-impact-analysis-coding-agents)
- [OpenAPI Generator usage](https://openapi-generator.tech/docs/usage/)