FORGE Builds API Reference

Reference the Starfire FORGE build resource, asynchronous build states, repository/project context, cancellation, validation, and artifact results.

FORGE Builds API reference

The Builds API exposes FORGE as an asynchronous developer resource instead of forcing a generated software project into one oversized synchronous response.

Resource model

The Alpha v1 architecture includes a build resource family conceptually similar to:

POST /v1/builds
GET  /v1/builds/{build_id}
POST /v1/builds/{build_id}/cancel

Use the active OpenAPI/Developer Portal for the exact request and response schema.

Create a build

A build request can include concepts such as:

• project goal
• project or organization context
• repository/source revision
• build/model preference
• constraints and protected interfaces
• validation expectations
• packaging options

The response should identify the created build and initial state.

Build status

Expect a multi-stage lifecycle such as planning, preparing, generating, validating, repairing, packaging, and a terminal completed/failed/cancelled state.

Result artifacts

A successful build returns or references durable artifact resources rather than embedding an entire project archive directly in the create response.

Validation metadata

Where exposed, inspect validation state separately from generation. A build that could not run the requested validator should not be treated as equivalent to a fully validated project.

Repository context

When modifying an existing codebase, pass or associate the supported repository/project source reference instead of copying an entire repository into a prompt string.

Cancel

Cancellation stops future build work where possible. It does not roll back external actions already completed and does not convert partial workspace state into a valid artifact automatically.

Usage

FORGE builds can make multiple model and tool calls. Account for credits, concurrency, duration, and artifact/storage limits.

FORGE Build Mode

Understand the build lifecycle behind the API resource.