Generations

A Generation (gen_*) records one attempt to produce a Target. It reports its status, trigger, package name and version, errors, coded warnings, operation coverage, and generated file paths and sizes. One Project action can queue a Generation for each selected Target.

POST /projects/{project_id}/generate returns 202 with the selected Generations. Retrieve each one with GET /generations/{generation_id} while its status is queued or running. completed means its files are saved, and runtime_ms reports how long the run took. failed includes recorded errors. A successful Generation does not establish that repository delivery or a Draft is complete; inspect the Target's Draft for that state.

Files and coverage

A Generation reports its file_count. GET /generations/{generation_id}/files lists each generated file as a file object with its path, size, digest, encoding, and Git mode, ordered by path. Read one with GET /files/{file_id}. Generation responses never include file contents.

coverage reports generated, omitted, and total operation counts plus omitted_operations as METHOD/path values. It is null before generation finishes. Each warning has a stable code, a display message, and an operation when one operation is affected. Branch on code, not the message.

What caused the run

trigger is manual, spec_changed, config_changed, or preview. A source push or URL check uses spec_changed; a Project or Target configuration change uses config_changed. Each linked Generation records the spec_revision_id it consumed, so you can retrieve that source revision later. The package version is the version generated by this run.

For pull requests and release readiness, inspect the Target's Draft and Release. See Generation behavior for the full lifecycle, Release a breaking change for release decisions, and Preview Generations for source review.