Writes
WarmHub has one HTTP write route: the NDJSON streaming submission route
POST /api/graphs/:orgName/:graphName/streams/:streamId/submissions, which takes
one operation per line. It is enabled per graph and answers 404 where it
is not enabled; see Endpoints. Otherwise, HTTP clients
should use one of the supported write surfaces:
| Surface | Method |
|---|---|
| SDK | client.commit.apply(...) |
| CLI | wh commit submit |
| MCP | warmhub_thing_create and the other write tools |
For validate-only evaluation, use client.commit.validate(...) in the TypeScript SDK, client.open_graph(...).validate(...) in the Python SDK, wh commit submit --dry-run in the CLI, or the warmhub_commit_validate MCP tool. Validate-only evaluation requires write authority. It checks your operations without creating graph state or a receipt, and returns a complete result or a request-level error—never a partial response. The SDK and CLI accept at most 10,000 operations and 4 MiB encoded per preview. For full details, see the SDK write methods reference and Validate without committing.
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 Operation Results.
| 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_thing_create and the other write tools) | applied / noop / error in receipt.operations[] | Structured success payload containing a receipt object; per-operation outcomes are found under receipt.operations[]; for the exact fields returned, see the MCP tools reference |
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 graph 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 graph read endpoints such as head, query, and about. Shape management is available through SDK, CLI, and commit-based workflows rather than REST shape endpoints.