Writes
WarmHub does not currently mount a REST write endpoint. HTTP clients should use one of the supported write surfaces:
| Surface | Method |
|---|---|
| SDK | client.commit.apply(...) |
| CLI | wh commit submit |
| MCP | warmhub_commit_submit |
For validate-only evaluation, the TypeScript and Python SDKs call the dedicated
unbatched tRPC mutation POST /trpc/commit.validate. Its body is the complete
{ orgName, repoName, operations, ...options } input rather than a streamed
append. Prefer client.commit.validate(...) so operation normalization, exact
body sizing, decoding, cancellation, and errors remain typed. The endpoint
requires authentication and write authority, accepts at most 10,000 operations
and 4 MiB encoded, and returns a complete result or a request-level error—never a
partial response. It evaluates without creating repository state or a receipt.
For operation fields and examples, see Operations and the SDK AddOperation reference.
The write surfaces share one operation pipeline but expose results differently. For a full cross-surface comparison, see the Write Methods overview.
| Surface | Per-operation statuses | Top-level shape |
|---|---|---|
SDK (client.commit.apply(...)) | applied / noop / error in operations[] | JSON object with operationCount, operations[], optional partial/statusCounts, and receipts; partial: true when some operations fail and others succeed; raises an error when every submitted operation fails |
MCP (warmhub_commit_submit) | applied / noop / error in operations[] | Receipt-root payload with top-level fields event, eventRequestId, operations, outcome, requestDigest, schemaVersion, and submissionId; compatibility fields results and nested receipt are also present; partial MCP successes do not include partial or statusCounts aggregate fields |
CLI (wh commit submit, JSON mode) | applied / noop / error in operations[] | JSON object with operationCount, operations[], optional partial/statusCounts, and receipts |
| Validate-only | would_apply / noop / error | One ordered result per input; no repository state created |
Writes can be attributed to an installed component by passing componentRef (the component’s Org/Name) on the SDK or MCP call. See Component Identity for the token rules, action-token behavior, and current SDK/CLI surface coverage.
The REST HTTP API currently exposes repository read endpoints such as head, query, and about. Shape management is available through SDK, CLI, and commit-based workflows rather than REST shape endpoints.