Skip to content

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:

SurfaceMethod
SDKclient.commit.apply(...)
CLIwh commit submit
MCPwarmhub_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.

SurfacePer-operation statusesTop-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-onlywould_apply / noop / errorOne 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.