WarmHub exposes a full MCP tool catalog for organizations, repositories, shapes, things, assertions, writes, subscriptions, actions, collections, and meta (capability discovery). In repo-scoped mode, orgName/repoName are omitted from all tool schemas. In global mode, they’re required on repo-level tools.
If you switch between the MCP tools and the TypeScript SDK, the names line up almost one-to-one. A few common pairs:
MCP tool
SDK method
warmhub_thing_head
client.thing.head(...)
warmhub_thing_query
client.thing.query(...)
warmhub_thing_get
client.thing.get(...)
warmhub_shape_list
client.shape.list(...)
warmhub_subscription_list
client.subscription.list(...)
warmhub_commit_submit
client.commit.apply(...) — note the verb differs
warmhub_capabilities
client.diagnostics.capabilities() — returns the backend API version, minimum supported SDK, and feature flags (not the tool catalog)
warmhub_repo_describe
no single method — client.repo.get + client.shape.list + client.repo.getStats cover repo metadata, shapes, and counts, but not the sampled data, query hints, wrefSyntax, or write contract / generated examples that warmhub_repo_describe also returns
Most tools follow the warmhub_<domain>_<verb> ↔ client.<domain>.<verb> pattern; the last three rows are the exceptions.
Orientation and capability discovery. The meta category covers five tools:
Tool
Description
warmhub_capabilities
Static, endpoint-scoped overview of the MCP tool catalog: tools grouped by category, a workflow cookbook, wref syntax, and a pointer to the full write operation contract. Read-only; no arguments.
warmhub_repo_describe
Per-repo live view: schema, shape descriptions, field types, summary stats, wref syntax, operation contract, and write examples generated from the repo’s own shapes. Documented under Repository Tools.
warmhub_use
No-op tool used to signal intent or context to the MCP host. Takes no arguments; returns an advisory noop note. Useful for structured agent workflows that declare what they are about to do before acting.
warmhub_channel
No-op tool used to establish or label a logical channel within a session. Takes no arguments; returns an advisory noop note.
warmhub_doctor
Diagnostic tool. Takes no arguments. Returns { ok: true, capabilities, hint }, where capabilities is a diagnostics payload containing apiVersion, minSupportedSdk, and features.
Call warmhub_capabilities first to orient on what tools exist; then call warmhub_repo_describe to learn the repo-specific shapes and write examples.
Takes no arguments. Returns a static orientation payload with the following fields:
Response Field
Type
Description
categories
object[]
One entry per tool category (org, repo, shape, thing-read, collection, commit, subscription, action, meta), each with name, description, and the tools (name, description, readOnly, openWorld, destructive, annotationJustification) advertised on the current endpoint.
cookbook
object[]
Common workflows as { task, steps: [{ tool, note }] } — e.g. discovering shapes, searching by content, writing first data.
usagePatterns
object[]
Query-discipline guidance — recommended patterns for reading, querying, and writing efficiently.
wrefSyntax
object
Local and canonical wref forms, version modifiers, path/name constraints, and write-path preview rules.
commitContractRef
object
Pointer to warmhub_repo_describe, which returns the full write operation contract, operation variants, and live write examples scoped to a specific repo.
The payload reflects the endpoint scope. On the repo-scoped endpoint (/mcp/:org/:repo), the following tools are omitted from categories:
Org tools (global only): the entire org category — warmhub_org_list, warmhub_org_get, warmhub_org_set_display_name, warmhub_org_set_description, warmhub_org_archive, warmhub_org_unarchive, and org member management tools
Org-scoped subscription tools (global only):warmhub_org_subscription_create and related org subscription management tools
Global-only repo tools:warmhub_repo_list and warmhub_repo_create
Call warmhub_capabilities first to orient an agent, then call warmhub_repo_describe for per-repo schema and write examples.
All organization tools are global only. The repo-scoped endpoint (/mcp/:org/:repo) excludes the entire org category, so none of these tools — including warmhub_org_set_display_name, warmhub_org_set_description, warmhub_org_archive, and warmhub_org_unarchive — are served there. Org-scoped subscription tools are likewise global only. Use the global endpoint (/mcp) for any organization operation.
Tool
Description
warmhub_org_list
List organizations (archived hidden by default). (global only)
warmhub_org_get
Get an organization by name. (global only)
warmhub_org_set_display_name
Set the human-readable display name for an organization. The display name must be non-empty. (global only)
warmhub_org_set_description
Set or clear an organization description. (global only)
Human-readable display name for the repo. Must be non-empty and non-whitespace if provided; max 100 characters. Defaults to the repo slug when omitted.
description
string
no
Repository description. Max 2000 characters.
visibility
string
no
"public" or "private". Defaults to "private".
Returns the created repo object (same shape as warmhub_repo_get). Only available on the global MCP endpoint.
The most important tool for agent bootstrapping. Returns:
Repository metadata
Shape definitions with field types and optional shape-level description
Per-shape queryHints with queryableFields, wrefFields, and suggested MCP query patterns
Per-field descriptions inlined into each field entry. Fields without descriptions appear as bare type strings (e.g. "string"); fields with descriptions appear as { "type": "number", "description": "Horizontal position" }. Descriptions are extracted from typed field objects.
When includeIndexedFields: true is passed, the response also includes an indexedFields block. The block exposes four state buckets — ready, building, failed, and other — each containing an array of field entries. Every entry carries the field’s state, associated timestamps, and backfill counters. Parse all four buckets when acting on index state: a field in building is not yet queryable, and a field in failed requires attention before structured queries against it will succeed.
Two tools cover the built-in Content shape — Readme, Agents, and the synthesized LlmsTxt — discriminated by a kind argument.
Tool
Description
warmhub_repo_content_get
Fetch repo Content markdown by kind. For readme/agents, returns a synthesized empty stub when nothing has been written — never null. kind: llms-txt always returns a synthesized response with the rendered sitemap and a structured refs field. Read-only.
warmhub_repo_content_set
Set Content/Readme or Content/Agents markdown (commits an add or revise operation). Writes to kind: llms-txt are rejected — it is synthesized and cannot be stored. Requires repo:write.
WarmHub no longer hosts README/AGENTS generation. To draft content, run the CLI command wh repo content prompt <org/repo> --kind readme to get an agent-ready prompt, let your own agent write the markdown, then persist it with warmhub_repo_content_set.
For kind: readme and kind: agents, returns the stored content thing after the first write. When nothing has been written yet, the response is a synthesized empty stub ({ synthesized: true, shape: "Content", name: "...", data: { content: "" }, active: true }).
For kind: llms-txt, always returns a synthesized response. data.content contains the full rendered markdown, and the response includes a refs field with partitioned outbound/inbound references; cross-org refs the caller cannot read are omitted. (MCP requests are always authenticated; for the anonymous reduced-body variant of llms.txt, see Content Shape.)
One of readme, agents, or llms-txt. llms-txt is read-only — set attempts are rejected.
content
string
yes
Markdown content to store
Returns the standard single-operation commit result: operationCount, one operations[] entry (name, operation, version, dataHash), plus optional committer, createdByEmail, and message metadata. Unlike warmhub_commit_submit, this helper does not return partial-result fields; rejected writes surface as tool errors.
List all items at HEAD with optional filters (shape, kind, glob match). Use to enumerate a repo’s current state; for fuzzy lookups use warmhub_thing_search.
warmhub_thing_get
Fetch one thing by wref. For many wrefs in one call use warmhub_thing_get_many; to resolve a wref’s canonical identity first use warmhub_wref_resolve.
warmhub_thing_graph
Get one thing and its embedded assertion/about/wref graph to a bounded depth.
warmhub_thing_get_many
Batch-fetch things by wref in one call — prefer over looping warmhub_thing_get. Missing wrefs are returned in a missing array.
warmhub_thing_history
List version history for a thing. Provide wref for one thing’s history, or shape/about to survey history across matching things. With about, resolveCollections:true includes assertions about Arc/Bond/Set/List collections containing the target identity.
warmhub_thing_about
List assertions whose about target resolves to the supplied target identity. For identity-scoped inputs, use resolveCollections:true to include assertions about Arc/Bond/Set/List collections containing the target; pinned @vN inputs stay version-exact. Use warmhub_thing_refs with direction:"inbound" for broader backlink discovery.
warmhub_thing_query
Query things by structured filters (shape, kind, about, glob match). Best for exact/structured lookups; for fuzzy or semantic search use warmhub_thing_search.
warmhub_thing_search
Full-text/vector/hybrid search across thing data. Best for fuzzy lookups; for exact field matches use warmhub_thing_query with a glob filter.
warmhub_thing_refs
List inbound or outbound refs for a target wref. Use direction:"inbound" to find what references X. Pair with warmhub_thing_get to resolve details.
warmhub_wref_resolve
Resolve a wref (local or canonical) to its canonical thing identity. Accepts cross-repo canonical wrefs; pair with warmhub_thing_get to fetch the resolved data.
"auto" (default) or "full". In "auto" mode, collections larger than 100 members return a summary (member count plus a truncated preview) instead of the full body; fixed-arity Arc/Bond collections and collections with 100 or fewer members keep their full body. Use "full" to force the complete body for large collections too.
In global mode, orgName/repoName may be omitted when wref is a durable id — a durable id routes itself to the repo that owns the target.
Returns the root thing with readable assertion about links and readable wref-typed fields embedded as objects. Refs the caller cannot read remain string wrefs, with no internal IDs or denial reasons exposed.
In global mode, orgName/repoName may be omitted when wref is a durable id.
Return things even when retracted at HEAD or at the requested version (mirrors warmhub_thing_get)
dataMode
string
no
"auto" (default) or "full". In "auto" mode, collections larger than 100 members return a summary (member count plus a truncated preview) instead of the full body; fixed-arity Arc/Bond collections and collections with 100 or fewer members keep their full body. Pass dataMode:"full" to force large collection bodies.
Missing wrefs are returned in a missing array. When a top-level version is supplied and the input wref is not already pinned, missing entries are version-qualified (Shape@vN or Shape/name@vN) so the round-trip is unambiguous; per-wref pins survive intact (no double-pinning). Duplicates in wrefs are not deduped — they count toward the 500-entry cap and produce duplicate items/missing entries.
Allow resolving retracted shape or about targets (does not filter results)
resolveCollections
boolean
no
With about, include assertion history for Arc/Bond/Set/List collections containing the target identity, including when the about wref is pinned
limit
integer
no
Max versions to return
cursor
string
no
Pagination cursor from previous response
At least one of wref, shape, or about is required.
In global mode, orgName/repoName may be omitted only when wref is a durable id. shape/about surveys and local wrefs always require orgName/repoName — a repo-less filter query is rejected.
By default, this tool returns assertions whose about target resolves to the supplied target identity. It does not expand collection member refs, so assertions about Arc, Bond, Set, or List collection things that contain the target appear only when resolveCollections:true is set on identity-scoped inputs: bare wrefs, @HEAD, or @ALL. Pinned @vN inputs stay version-exact and do not expand collection members.
For broader graph discovery, use warmhub_thing_refs with direction:"inbound" to find current things that reference the target through wref fields. Use warmhub_thing_about when you specifically need assertion records and about-target filtering.
Param
Type
Required
Description
wref
string
yes
Target thing wref
shape
string
no
Filter assertions by shape
match
string
no
Glob pattern to filter assertion wrefs
where
object[]
no
Typed field-value predicates ({ fieldPath, op, rhs }), ANDed, max 8. See Field-Value Predicates.
resolveCollections
boolean
no
Include assertions about Arc/Bond/Set/List collections containing the target entity for identity-scoped inputs; ignored for pinned @vN inputs
includeRetracted
boolean
no
Resolve a retracted target and include retracted assertions in the returned results, including within the single children layer when depth is also set.
depth
integer
no
When set, returns one level of child assertions for each top-level result. Values greater than 1 do not produce additional nesting — only one children layer is returned regardless of the value supplied. Each child entry has an empty children array.
Filter by kind. One of shape, thing, assertion, or collection.
match
string
no
Glob pattern to filter wrefs
where
object[]
no
Typed field-value predicates ({ fieldPath, op, rhs }), ANDed, max 8. See Field-Value Predicates.
count
boolean
no
Return count of matching items instead of the full result list
resolveCollections
boolean
no
When about is set, also include assertions about collections containing the target
includeRetracted
boolean
no
Include retracted entities
componentRef
string
no
Filter results to items owned by the given component (its Org/Name ref)
excludeComponents
boolean
no
Exclude component-owned items from results. Accepted alongside componentRef, but the two are mutually exclusive filters, so passing both returns no items.
Filter by kind. One of shape, thing, assertion, or collection.
about
string
no
Filter by about target (not supported with vector mode)
match
string
no
Glob pattern to filter wrefs
resolveCollections
boolean
no
When about is set, also include assertions about collections containing the target (text mode only)
mode
string
no
"text" (default), "vector", or "hybrid"
includeRetracted
boolean
no
Include retracted entities
componentRef
string
no
Filter results to items owned by the given component (its Org/Name ref)
excludeComponents
boolean
no
Exclude component-owned items from results. Accepted alongside componentRef, but the two are mutually exclusive filters, so passing both returns no items.
excludeInfraShapes
boolean
no
Hide internal infra shapes from results
limit
integer
no
Max results. Must be between 1 and 500.
cursor
string
no
Pagination cursor from previous response (text mode only — vector and hybrid reject cursor). When about or resolveCollections is set, pages may be sparse — paginate until nextCursor is absent.
Direction "inbound" returns things that reference the target wref. Direction "outbound" returns things the target wref references.
Use inbound refs as a broad discovery tool when you are unsure whether data points directly at a thing or at a collection containing it. Inbound refs are not a substitute for warmhub_thing_about when you need assertion-only results or assertion filters.
Cross-repo wref lookups (canonical forms wh:org/repo/Shape and wh:org/repo/Shape/name) require effective repo:read permission on the target repo. Public repos are readable by anyone. For private repos, callers without that access see an error — except warmhub_thing_search with a cross-repo about (returns { items: [] }) and warmhub_thing_get_many (puts unreadable wrefs into missing[]) — both to keep batch and search streaming-friendly.
The tool’s input schema contains the full structural contract for all ten operation variants. Call warmhub_repo_describe and inspect commitContract for the target repository’s shape-specific data fields and ready-to-use examples. The tool returns per-operation results; per-op failures show up as operations[] entries with status: "error" and partial: true. When returnRepoSeq: true is passed, a successful write also returns a top-level repoSeq field carrying the sequence allocated to this caller’s own write; it is omitted for noops and all-failed writes. Opinion-bearing assertions must be binary propositions.
See MCP Error Handling for the full failure taxonomy. Ambiguous append failures (a separate class from per-op failures) return a tool-result error with continuation recovery state; the failed append may have landed server-side, so inspect repository state before deciding whether to resume.
Param
Type
Required
Description
committer
string
no
Optional untyped wref identifying the actor on whose behalf the writes are made. It must identify an existing thing. Omit it to attribute the write to the authenticated user via createdByEmail.
componentRef
string
no
Attribute writes to an installed component, identified by its Org/Name ref. See component identity rules below.
message
string
no
Optional message recorded with each thing-version produced by this call
operations
array
yes
Operations array (non-empty). When resuming after an ambiguous append failure, pass only the operations that haven’t been acknowledged — inspect repository state with warmhub_thing_get / warmhub_thing_query to determine which landed.
streamId
string
no
When resuming after an ambiguous append failure, copy the streamId from the prior error’s continuation payload.
returnRepoSeq
boolean
no
Return the sequence allocated to this caller’s own successful write in a top-level repoSeq result field. No sequence is returned for noops or all-failed writes.
Component identity rules:
User tokens may claim components installed by that user.
Callers with org:configure for the org may claim any installed component in the org.
Action tokens derive the component from the running subscription and reject mismatched explicit values.
warnings.undeclaredFields lists top-level keys present in the submitted data but not declared in the target shape. When the list is capped, undeclaredFieldsTruncated: true is set and totalUndeclared reports the full count. warnings.coalescedWrefs lists optional wref fields whose resolver outcome was thing_absent and was coalesced to null — each entry carries fieldPath, wref, and reason; missing shapes and every other failure remain hard errors. When capped, coalescedWrefsTruncated: true is set with totalCoalescedWrefs. The struct is additive — an operation can carry either warning kind or both. Both warnings are informational; they do not turn the operation into a failure. See Optional Wref Fields.
For add operations, skipExisting: true returns noop when the target already exists instead of failing. For revise operations, expectedVersion applies the change only if the target is still at that version, otherwise it rejects with CONFLICT. A revise whose data matches the current version returns noop instead of creating a new version. See Conditional Operations for the full model.
Unauthorized component claims reject with FORBIDDEN.
Lists shapes in the repo. In repo-scoped mode, all parameters are optional — omit them to return every shape. In global mode, orgName and repoName are required.
Param
Type
Required
Description
orgName
string
yes (global)
Organization name. Omit in repo-scoped mode.
repoName
string
yes (global)
Repository name. Omit in repo-scoped mode.
match
string
no
Glob pattern to filter shape names by bare name (e.g. Sensor*), not by full wref.
componentRef
string
no
Return only shapes owned by this component, identified by its Org/Name ref (e.g. warmhub/veritas). Mutually exclusive with excludeComponents.
excludeComponents
boolean
no
Exclude all component-owned shapes from results. Mutually exclusive with componentRef — passing both returns no shapes.
Each item in the response includes a queryHints block (queryableFields, wrefFields, suggestedPatterns) to help you choose the right warmhub_thing_query, warmhub_thing_search, or warmhub_thing_refs pattern for that shape.
Both warmhub_shape_get and warmhub_shape_list include a queryHints block (queryableFields, wrefFields, suggestedPatterns) to help agents choose warmhub_thing_query, warmhub_thing_search, and warmhub_thing_refs patterns for each shape.
Generates write-operation templates for one or more shapes in the repo. Read-only tool in the commit category. For conceptual background see Generating Templates.
Param
Type
Required
Description
shapeNames
string
yes
Comma-separated shape names to generate templates for
kind
string
no
Filter templates to a specific kind. One of thing or assertion.
operation
string
no
Filter to a specific operation type. One of add, revise, or retract.
about
string
no
Populate the about field in generated assertion templates with this wref
✓ (deprecated — accepted with a deprecation warning)
✓
Triple
—
✓ (legacy, read-only)
Use create to make a collection and revise to change its membership; members, stats, and contains to read one; and diff to compare two collections or two versions of the same collection.
Tool
Description
warmhub_collection_create
Create a new named collection in the repo. Requires repo:write.
warmhub_collection_members
List the current members of a named collection.
warmhub_collection_contains
Check whether a named collection contains one or more given wrefs.
warmhub_collection_diff
Compute the diff between two versions of a named collection.
warmhub_collection_revise
Revise the membership of an existing named collection. Requires repo:write.
warmhub_collection_stats
Return summary statistics for a named collection (member count, version, last-modified metadata).
Collection type: "arc", "bond", "set", "list", or "pair" (deprecated — accepted with a deprecation warning; use "arc", "bond", "set", or "list" for new collections)
name
string
yes
Collection name (local wref segment)
members
string[]
no
Initial member wrefs
from
string
no
Source wref to copy members from
add
string[]
no
Wrefs to add to the initial member set
remove
string[]
no
Wrefs to remove from the initial member set
replaceMembers
string[]
no
Replace the full member list with these wrefs
shape
string
no
Selector: filter by shape
about
string
no
Selector: filter by about target
match
string
no
Selector: glob pattern to filter wrefs
componentRef
string
no
Selector: filter to items owned by the given component
where
object[]
no
Selector: typed field-value predicates
message
string
no
Message recorded with the write
committer
string
no
Wref identifying the actor on whose behalf the write is made
skipExisting
boolean
no
Return noop instead of failing when the collection already exists
orgName and repoName may be omitted when wref is a self-routing durable ID — the durable ID routes itself to the repo that owns the collection. cursor must be paired with limit.
Param
Type
Required
Description
orgName
string
no
Organization name. Required in global mode unless wref is a durable ID.
repoName
string
no
Repository name. Required in global mode unless wref is a durable ID.
wref
string
yes
Collection wref
version
integer
no
Pin the lookup to a specific collection version
limit
integer
no
Max members to return. Required when cursor is provided.
cursor
string
no
Pagination cursor from previous response. Must be paired with an explicit limit.
Check membership at a specific position. Valid for ordered collection types (Arc, Pair, List, and legacy Triple); rejected for unordered Set and Bond collections.
"webhook" or "cron". "webhook" is the supported value for new subscriptions; "cron" is accepted by the schema only so older callers receive a deterministic rejection.
eventType
string
no
Event type to subscribe to. One of commit, repo.renamed, thing.renamed, or shape.renamed. Defaults to commit when omitted.
shapeName
string
no
Shape to subscribe to. For commit subscriptions, provide either shapeName or filterJson.shape — except for shape lifecycle subscriptions, which omit both and rely on a {"kind":"shape", ...} filter. Not applicable for repo.renamed, thing.renamed, or shape.renamed subscriptions.
filterJson
object
no
Recursive subfilter/v1 commit-operation filter with operation, kind, shape, name, match, all, any, and not. Required for commit; rejected for metadata rename events.
webhookUrl
string
yes
Webhook endpoint URL
fallbackWebhookUrl
string
no
Optional fallback endpoint called after a terminal delivery failure
allowTraceReentry
boolean
no
Reentry policy for write-triggered subscriptions. Defaults to false
sourceRepoRef
string
no
Source repo (org/repo) for a cross-repo subscription. Must be in the same org as the home repo
notifyOnSuccess
boolean
no
Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only
For a commit subscription, omitted eventType defaults to commit, so this is a complete filter example:
{
"orgName": "acme",
"repoName": "signals",
"name": "new-signals",
"kind": "webhook",
"shapeName": "Signal",
"filterJson": {
"all": [
{ "operation": "add" },
{ "kind": "thing" }
]
},
"webhookUrl": "https://hooks.example.com/warmhub"
}
When both shapeName and filterJson.shape are present, they must identify the same shape. A structurally shape-only filter such as {"kind":"shape"} is the only commit form that needs neither binding. Metadata rename events reject shapeName, filterJson, and sourceRepoRef.
This global-only tool creates organization-owned automation. The caller must be
an organization owner or admin. It accepts no repoName, shape, filter, or
source repository.
Param
Type
Required
Description
orgName
string
yes
Organization name
name
string
yes
Subscription name
eventType
string
no
org.renamed, org.member_added, org.repo_created, or org.repo_published; defaults to org.renamed
kind
string
yes
"webhook"
webhookUrl
string
yes
Webhook endpoint URL
fallbackWebhookUrl
string
no
Optional fallback endpoint
allowTraceReentry
boolean
no
Allow another delivery in the same action trace
notifyOnSuccess
boolean
no
Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only
Replacement commit-subscription shape. Rejected for metadata-event and cross-repo subscriptions.
filterJson
object
no
Replacement recursive subfilter/v1 filter. Rejected for metadata-event and cross-repo subscriptions.
webhookUrl
string
no
Replacement webhook URL
fallbackWebhookUrl
string or null
no
Replacement fallback webhook URL. Use null to clear it
allowTraceReentry
boolean
no
Replacement reentry policy for write-triggered subscriptions
notifyOnSuccess
boolean
no
Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only
Updates patch only the fields supplied; omitted fields retain their current values. name, kind, and eventType cannot be changed. For commit subscriptions, the merged shapeName and filterJson.shape constraints must still agree and retain a valid shape binding (or a structurally shape-only filter).
Org-scoped subscription tools manage subscriptions at the organization level. The current org-scoped subscription type is fixed to the org.renamed event — these subscriptions fire when the organization is renamed. There is no event selector or filter to configure; the event type is hardcoded. These tools follow the same pause/resume/delete lifecycle as repo-scoped subscription tools.
Tool
Description
warmhub_org_subscription_create
Create a webhook subscription at the organization level. Fires on org.renamed events.
warmhub_org_subscription_list
List org-scoped subscriptions.
warmhub_org_subscription_get
Get org-scoped subscription metadata by name.
warmhub_org_subscription_pause
Pause an active org-scoped subscription.
warmhub_org_subscription_resume
Resume a paused org-scoped subscription.
warmhub_org_subscription_delete
Delete an org-scoped subscription.
warmhub_org_subscription_update
Update an existing org-scoped subscription’s webhook delivery config.
Creates a webhook subscription that fires when the organization is renamed (org.renamed). The event type is fixed and cannot be changed. Only the delivery configuration fields listed below are accepted; sending any other key returns an Invalid arguments error.
Param
Type
Required
Description
orgName
string
yes
Organization name
name
string
yes
Subscription name
kind
string
yes
"webhook"
webhookUrl
string
yes
Webhook endpoint URL
fallbackWebhookUrl
string
no
Optional fallback endpoint called after a terminal delivery failure
allowTraceReentry
boolean
no
Reentry policy. Defaults to false
notifyOnSuccess
boolean
no
Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only
componentRef
string
no
Attribute this subscription to an installed component, identified by its Org/Name ref (e.g. warmhub/veritas). See Component Tools for the component ref format.
Patches the webhook delivery configuration of an existing org-scoped subscription. Only delivery fields can be updated — org-scoped subscriptions have a fixed org.renamed event type with no shape or filter to edit. Sending filterJson or any other unsupported key returns an Invalid arguments error.
Param
Type
Required
Description
orgName
string
yes
Organization name
name
string
yes
Existing subscription name
webhookUrl
string
no
Replacement webhook URL
fallbackWebhookUrl
string or null
no
Replacement fallback webhook URL. Use null to clear it
allowTraceReentry
boolean
no
Replacement reentry policy
notifyOnSuccess
boolean
no
Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only
Get delivery feed for a subscription. Includes run status, attempt count, and error details.
warmhub_action_runs
List action runs in a repository.
warmhub_action_attempts
Get attempt history for a specific action run.
warmhub_action_notifications
List terminal action-failure notifications for a repo. Only runs that have reached a non-recoverable failure state appear in this feed.
warmhub_notifications
Alias for warmhub_action_notifications. Lists terminal action-failure notifications for the current repo endpoint. Available on both global and repo-scoped endpoints.
Filter by terminal outcome. Accepted values: succeeded or failed. failed matches runs in a terminal failure state (failed_terminal or dead_letter); it does not match every non-success state. Cannot be combined with status.
since
string
no
ISO datetime or unix timestamp. Cannot be combined with cursor.
limit
integer
no
Max results. Must be between 1 and 200.
cursor
string
no
Pagination cursor from previous response. Cannot be combined with since. When present, the response includes nextCursor when more results are available.
The combinations status+outcome and since+cursor are not accepted and will be rejected.
Returns terminal action-failure notifications for the repo. Only runs that have reached a non-recoverable failure state produce records in this feed — succeeded and suppressed runs do not appear. See Actions for the full HTTP contract, including the GET /api/repos/:orgName/:repoName/actions/notifications endpoint.
Aliases warmhub_action_notifications over the same backend. Returns terminal action-failure notifications for the repo — only runs that have reached a non-recoverable failure state produce records in this feed. Available on both global and repo-scoped endpoints; on the repo-scoped endpoint, orgName and repoName are omitted from the schema. See Actions for the full HTTP contract, including the GET /api/repos/:orgName/:repoName/actions/notifications endpoint.
Install a registered component (<org>/<name>) into the repo: applies its manifest (shapes, credential sets, subscriptions, seeds) and runs the optional setup handshake. Returns the install state plus any setup-deferred resources. Requires repo:write. Components whose manifests declare credentials or subscriptions require additional permissions — see the note below.
warmhub_component_uninstall
Uninstall a registered component (the wh component teardown operation): pauses its subscriptions, revokes its tokens, dispatches the optional uninstall callback, and marks the install record uninstalled. Frees the shape names the component claimed so a reinstall can reclaim them, while leaving the existing shapes and any seeded data in place. Non-destructive — reinstall revives the install. Requires repo:write.
