ComfyUI-OpenClaw/docs/release/api_contract.md

OpenClaw API Contract (v1)

Status: normative Version: 1.0.15 Date: 2026-07-10

This document defines the public API contract for OpenClaw. It serves as the authoritative baseline for client compatibility and breaking change policies.

0. Tenant Boundary Context

Default behavior remains single-tenant compatible (tenant_id=default).

When OPENCLAW_MULTI_TENANT_ENABLED=1:

• tenant context may be supplied by token context and/or request header (X-OpenClaw-Tenant-Id, configurable)
• token/header mismatch is rejected with 403 (tenant_mismatch)
• connector installation resolution is tenant-scoped and rejects cross-tenant matches fail-closed (diagnostic conflict path)
• current admin/API handlers keep compatibility behavior by defaulting missing tenant context to default tenant

1. Route Inventory

All new integrations should use the /openclaw/ prefix. Use of /moltbot/ is deprecated.

1.0 UI Entry Points

Base Path: /openclaw/

Method	Path	Legacy Path	Auth	Description
GET	/admin	/moltbot/admin	None*	Standalone remote admin console HTML shell (mobile-friendly).

* The page shell can be loaded directly, but all backend write operations from the console still enforce Admin token and remote-admin policy.

1.1 Core Observability & System

Base Path: /openclaw/

Method	Path	Legacy Path	Auth	Description
GET	/health	/moltbot/health	None	System status, uptime, dependencies, and startup lifecycle diagnostics.
GET	/capabilities	/moltbot/capabilities	None	Feature flags and supported extensions (includes optional UX/runtime features such as assist streaming support).
GET	/logs/tail	/moltbot/logs/tail	Observability	Tail recent log lines (rate-limited).
GET	/trace/{prompt_id}	/moltbot/trace/{id}	Observability	Get execution trace by prompt ID.
GET	/events	/moltbot/events	Observability	List recent job lifecycle events (JSON polling fallback; includes pagination/scan diagnostics).
GET	/events/stream	/moltbot/events/stream	Observability	SSE stream of job lifecycle events with resume support.
GET	/config	/moltbot/config	Observability	Read-only view of sanitized provider config.
PUT	/config	/moltbot/config	Admin	Update system configuration.
GET	/jobs	/moltbot/jobs	Admin	List recent jobs through the versioned bounded in-process jobs read model.
POST	/preflight	/moltbot/preflight	Admin	Analyze a workflow or API prompt payload for missing nodes/models and portability diagnostics.
GET	/preflight/inventory	/moltbot/preflight/inventory	Admin	Snapshot-first inventory of nodes/models for operator diagnostics, including refresh-state metadata.

Jobs list contract:

• GET /openclaw/jobs and its browser/legacy aliases are Admin-only and return contract_version: 1 from the bounded in-process ComfyUI jobs adapter.
• Supported query fields are status, workflow_id, sort_by, sort_order, limit, and offset. Status values are pending, in_progress, completed, failed, and cancelled; sorting supports created_at or execution_duration with asc/desc.
• The default/maximum page sizes are 50/200 and the source/offset window is capped at 10,000. Successful responses contain only ok, contract_version, jobs, pagination, source, and scan at the top level.
• Job summaries allow only id, status, bounded priority/timestamps, outputs_count, and bounded workflow_id. preview_output is never included, and list responses never include raw prompts, workflows, execution errors, tracebacks, current inputs/outputs, tenant/client/trace identifiers, reasoning, or internal content.
• An authoritative empty snapshot is HTTP 200 with jobs: []. Missing host helpers use HTTP 501 jobs_host_contract_unsupported; unavailable or malformed snapshots use HTTP 503 jobs_backend_unavailable. These failures are never converted into empty success.

Reasoning-content redaction contract:

• operator-visible trace and events payloads strip provider reasoning / thinking-like fields and explicitly marked internal maintenance/helper content by default
• audit event payload/meta fields follow the same internal-content and reasoning-like redaction boundary before retention
• privileged reveal is opt-in only and requires:
  • request header X-OpenClaw-Debug-Reveal-Reasoning: 1 or query debug_reasoning=1
  • server-side enablement via OPENCLAW_DEBUG_REASONING_REVEAL=1
  • admin authorization
  • loopback source
  • non-hardened runtime profile
  • deployment profile local or lan
• clients MUST treat reveal behavior as debug-only and MUST NOT depend on reasoning payload presence in normal operation
• explicitly marked internal maintenance/helper content has no public or debug reveal path

Inventory diagnostics contract:

• /preflight/inventory is snapshot-first and may return before deep scan work finishes
• clients SHOULD treat snapshot_ts, scan_state, stale, and last_error as first-class diagnostics fields rather than assuming a blocking full-rescan model

Preflight workflow diagnostics contract:

• POST /openclaw/preflight accepts both API prompt dictionaries and frontend workflow JSON when supplied by operator tooling
• response summaries distinguish actionable missing_nodes / missing_models from suppressed_missing_nodes / suppressed_missing_models
• suppressed findings represent muted or bypassed root nodes or subgraph branches when the submitted workflow shape provides enough frontend ancestry metadata
• clients SHOULD display suppressed findings as informational context rather than blocking workflow readiness

History and output-ref contract:

• history/output consumers SHOULD treat the normalized output-ref contract as media-aware
• current previewable output groups are images, video, audio, 3d, bounded inline text, and allowlisted file-backed text refs from the host files key
• file-like refs that can be represented through /view remain on the bounded /history + /view preview path
• file-backed text admission is limited to .txt, .md, .markdown, .json, .csv, .yaml, .yml, .xml, and .log; clients MUST build the URL from normalized filename/subfolder/type fields rather than trust a history-provided URL
• browser text previews MUST remain same-origin /view GET requests, reject redirects and active/ambiguous MIME types, use strict UTF-8, stream at most 64 KiB within 5 seconds, display at most 4,096 characters, and degrade to a source link when safe streaming is unavailable
• fetched text MUST be inserted as literal text; HTML, Markdown, SVG/XML, ANSI, or script interpretation is not part of this contract
• asset_hash / hash metadata is optional because current ComfyUI host asset hashing is opt-in through --enable-asset-hashing; clients MUST NOT require hashes for normal filename-backed previews
• refs with asset_hash or hash values, when host metadata provides them, preview through /view?filename=blake3:...
• refs that only expose upstream asset-service identifiers remain explicit asset_api_required states; clients MUST NOT silently infer direct /api/assets fetching from that marker
• HDR .exr / .hdr image refs remain image refs but should be rendered as explicit source-preview fallback links unless the client implements a safe HDR-specific viewer
• legacy callback/image-only consumers may continue using image-only extraction paths; non-image media refs should be rendered as explicit fallback/link/text surfaces unless the client implements a safe media-specific renderer

1.2 Webhooks & Triggers

Auth: Requires configured webhook secret or Admin Token.

Method	Path	Legacy Path	Auth	Description
POST	/webhook	/moltbot/webhook	Webhook Secret	Receive external alerts (schema validation only).
POST	/webhook/submit	/moltbot/webhook/submit	Webhook Secret	Validate and submit job from webhook payload.
POST	/webhook/validate	/moltbot/webhook/validate	Webhook Secret	Dry-run validation of webhook payload.
POST	/triggers/fire	/moltbot/triggers/fire	Admin	Fire an ad-hoc workflow trigger from external system.

ComfyUI prompt submission interoperability:

• OpenClaw-generated ComfyUI /prompt payloads include extra_data.comfy_usage_source = "comfyui-openclaw" when the caller has not supplied a value
• caller-provided extra_data.comfy_usage_source is preserved
• attribution is a stable product identifier and MUST NOT include prompt text, tenant ids, trace ids, URLs, tokens, or secrets
• existing extra_data.openclaw and legacy extra_data.moltbot metadata remain caller-owned except for OpenClaw tenant metadata insertion under extra_data.openclaw.tenant_id

1.3 Assist, LLM & Chat

Assist Base Path: /openclaw/assist/

Method	Path	Legacy Path	Auth	Description
GET	/assist/planner/profiles	/moltbot/assist/planner/profiles	Admin/Local	List active planner profiles from registry for UI/node alignment.
POST	/assist/planner	/moltbot/assist/planner	Admin/Local	Planner structured prompt generation.
POST	/assist/refiner	/moltbot/assist/refiner	Admin/Local	Prompt refinement with optional image context.
POST	/assist/planner/stream	/moltbot/assist/planner/stream	Admin/Local	Optional SSE-style planner streaming response (text/event-stream) with staged progress + final payload.
POST	/assist/refiner/stream	/moltbot/assist/refiner/stream	Admin/Local	Optional SSE-style refiner streaming response (text/event-stream) with staged progress + final payload.

Assist payload redaction contract:

• structured assist responses preserve final operator-visible answer fields but strip provider reasoning / chain-of-thought style fields and explicitly marked internal maintenance/helper content by default
• when the privileged reveal gate is allowed, debug reasoning is exposed only in a separate debug payload and not merged back into the normal structured answer fields
• explicitly marked internal maintenance/helper content is not exposed by the privileged reasoning reveal gate

1.3B Connector Installation Diagnostics

Base Path: /openclaw/connector/ Auth: Admin Token Required

Method	Path	Legacy Path	Auth	Description
GET	/connector/installations	/moltbot/connector/installations	Admin	List redacted connector installations with lifecycle diagnostics.
GET	/connector/installations/{installation_id}	/moltbot/connector/installations/{installation_id}	Admin	Get one redacted connector installation record.
GET	/connector/installations/resolve	/moltbot/connector/installations/resolve	Admin	Run fail-closed workspace resolution diagnostics (platform, workspace_id).
GET	/connector/installations/audit	/moltbot/connector/installations/audit	Admin	List installation lifecycle audit evidence (redacted).
GET	/connector/extraction-contract	/moltbot/connector/extraction-contract	Admin	Get the machine-readable connector extraction recommendation, seam families, static service-env SecretRef propagation policy, and current blockers.

Connector diagnostics contract notes:

• installation records may expose operator-safe health metadata under installation.metadata.health (for example ok, invalid_token, revoked, degraded) without exposing token material
• /connector/installations diagnostics may include aggregate health_counts in addition to lifecycle status_counts
• /connector/installations/resolve may expose a stable health_code alongside the legacy reject_reason so clients can distinguish workspace_unbound vs token-health failures without parsing status text
• /connector/extraction-contract is structural packaging metadata and static service-env SecretRef policy only; clients MUST NOT treat it as a live installation-health, live environment dump, or token-status feed

1.3C Model Management & Installations

Base Path: /openclaw/ Auth: Admin Token Required

Method	Path	Legacy Path	Auth	Description
GET	/models/search	/moltbot/models/search	Admin	Search normalized model entries across managed installs and catalog sources.
POST	/models/downloads	/moltbot/models/downloads	Admin	Create a managed model download task with progress/cancel lifecycle.
GET	/models/downloads	/moltbot/models/downloads	Admin	List model download tasks with snapshot or delta cursor semantics (since_seq).
GET	/models/downloads/{task_id}	/moltbot/models/downloads/{task_id}	Admin	Get one model download task by id.
POST	/models/downloads/{task_id}/cancel	/moltbot/models/downloads/{task_id}/cancel	Admin	Cancel a queued or running model download task.
POST	/models/import	/moltbot/models/import	Admin	Import a completed managed download into the bounded install root after provenance and hash verification.
GET	/models/installations	/moltbot/models/installations	Admin	List managed model installations.

Model-manager contract notes:

• /models/downloads supports since_seq cursor polling and may return deterministic delta metadata (requested_since_seq, effective_since_seq, next_since_seq, truncation/reset hints) alongside the task list
• model_type values SHOULD use current ComfyUI folder keys where applicable, including text_encoders, diffusion_models, clip_vision, style_models, upscale_models, vae_approx, gligen, latent_upscale_models, hypernetworks, photomaker, model_patches, audio_encoders, background_removal, frame_interpolation, geometry_estimation, optical_flow, and detection
• legacy aliases such as ckpt, checkpoints, loras, controlnets, clip, text_encoder, unet, diffusion_model, upscale_model, latent_upscale_model, hypernetwork, model_patch, and audio_encoder are normalized before filtering or import destination resolution
• current ComfyUI folder keys that are not managed model-file destinations fail closed for download creation: configs (configuration YAML), diffusers (folder-valued trees), classifiers (extensionless classifier artifacts), and custom_nodes (executable plugin code)
• download creation requires structured provenance metadata (publisher, license, source_url) and a 64-char expected_sha256
• import keeps fail-closed destination/filename validation and re-checks the staged file hash before activation

1.3D LLM Management & Chat

LLM Base Path: /openclaw/llm/

Method	Path	Legacy Path	Auth	Description
POST	/chat	/moltbot/llm/chat	Admin/Local	Unified chat interface for assistant interactions.
POST	/test	/moltbot/llm/test	Admin	Test LLM connectivity and configuration.
GET	/models	/moltbot/llm/models	Admin	List available models from configured provider. Request-time fetch uses the same SSRF contract as saved base_url validation, including scoped private-network allowance and the explicit insecure override for private-IP/HTTP targets.

1.4 Templates & Assets

Base Path: /openclaw/

Method	Path	Legacy Path	Auth	Description
GET	/templates	/moltbot/templates	Observability	List discovered template IDs and metadata.
GET	/presets	/moltbot/presets	Public/Admin*	List local presets (*depends on OPENCLAW_PRESETS_PUBLIC_READ).
POST	/presets	/moltbot/presets	Admin	Create a new preset.
PUT	/presets/{id}	/moltbot/presets/{id}	Admin	Update an existing preset.
DELETE	/presets/{id}	/moltbot/presets/{id}	Admin	Delete a preset.
GET	/checkpoints	/moltbot/checkpoints	Observability	List model checkpoints.
POST	/checkpoints	/moltbot/checkpoints	Admin	Create/copy a checkpoint.
GET	/packs	/moltbot/packs	Admin	List installed asset packs.
POST	/packs/import	/moltbot/packs/import	Admin	Import an asset pack (.zip).
GET	/packs/export/...	/moltbot/packs/export...	Admin	Download an asset pack.

1.5 Schedules & Approvals

Base Path: /openclaw/ Auth: Admin Token Required

Method	Path	Description
GET	/schedules	List all schedules.
POST	/schedules	Create a new schedule.
GET	/schedules/{id}	Get schedule details.
PUT	/schedules/{id}	Update a schedule.
DELETE	/schedules/{id}	Delete a schedule.
POST	/schedules/{id}/run	Manually trigger a schedule.
GET	/schedules/{id}/runs	Get run history for a schedule.
GET	/approvals	List pending approvals (includes pagination/scan diagnostics; bounded serialization scan on malformed records).
POST	/approvals/{id}/approve	Approve a pending request.
POST	/approvals/{id}/reject	Reject a pending request.

Schedule delivery is normalized before persistence. Supported fields are platform, target_id (legacy aliases such as channel_id are accepted), thread_id (aliases such as thread_ts, topic_id, and message_thread_id are accepted), workspace_id, account_id, mode, and failure_alert. Omitting delivery on update preserves the existing target, delivery: null clears it, and {"enabled": false} or {"mode": "none"} records explicit no-delivery. Invalid delivery targets are rejected before persistence with bounded codes: delivery_malformed, delivery_ambiguous, or delivery_unsupported.

1.5A External Tools

OpenClaw path prefix: /openclaw/ Legacy Base Path: /moltbot/ Auth: Admin Token Required Feature flag: OPENCLAW_ENABLE_EXTERNAL_TOOLS=true

Method	Path	Legacy Path	Auth	Description
GET	/tools	/moltbot/tools	Admin Token Required	List allowed external tools and their declared sandbox metadata.
POST	/tools/{name}/run	/moltbot/tools/{name}/run	Admin Token Required	Execute a named allowlisted external tool with validated arguments.

Tool execution contract notes:

• tools are disabled unless OPENCLAW_ENABLE_EXTERNAL_TOOLS is truthy
• tool definitions load from package-owned data/tools_allowlist.json unless OPENCLAW_TOOLS_CONFIG_PATH is set
• in public/split high-risk surfaces, tool execution can be blocked by the surface guard even when the feature flag is enabled
• execution responses preserve the current HTTP payload shape: failed runs return ok=false, tool, error, redacted output, exit_code, and duration_ms
• the service-level tool runner classifies common local failures with stable diagnostics such as sandbox_runtime_unavailable, interpreter_missing, timeout, and workspace_violation; clients should still follow this API document for the current HTTP response shape

1.6 Bridge (Sidecar)

Base Path: /bridge/ Auth: Bridge Auth (Device Check)

Method	Path	Description
GET	/health	Bridge status and connectivity check.
POST	/submit	Submit job from sidecar to core.
POST	/deliver	Outbound delivery from core to sidecar (via callback).

---

2. Status & Error Semantics

API responses MUST adhere to the following status codes and envelope format.

2.1 Standard Envelope

All JSON responses (success or error) share a common structure:

{
  "ok": boolean,
  "error": "string (optional)",
  "detail": "string (optional)",
  "trace_id": "string (optional)",
  "data": { ... } // Success payload
}

2.2 Status Codes

Code	Meaning	Usage
200	OK	Successful synchronous request.
201	Created	Resource created (schedules, presets).
202	Accepted	Async job submitted (pending execution or approval).
400	Bad Request	Schema validation failure, missing required fields.
401	Unauthorized	Missing or invalid authentication token.
403	Forbidden	Authenticated but permission denied (e.g., admin-only).
404	Not Found	Resource or route does not exist.
409	Conflict	Idempotency collision or state conflict.
413	Payload Too Large	Input size exceeds OPENCLAW_MAX_RENDERED_WORKFLOW_BYTES or similar limits.
429	Too Many Requests	Rate limit or Execution Budget exceeded.
500	Internal Error	Unhandled server exception.
501	Not Implemented	Required current-host contract is unavailable (for example jobs_host_contract_unsupported).
503	Unavailable	Feature disabled or service not wired.

Tenant-boundary error notes:

• tenant boundary violations use 403 with explicit codes such as tenant_mismatch and tenant_invalid.

2.3 SSE Endpoint Notes (Contractual Behavior)

• SSE endpoints return Content-Type: text/event-stream.
• Current SSE surfaces include:
  • /openclaw/events/stream (job lifecycle events)
  • optional /openclaw/assist/planner/stream and /openclaw/assist/refiner/stream (assist incremental preview path)
• Assist streaming emits event types from the following set:
  • ready
  • stage
  • delta
  • final
  • error
  • keepalive
• Clients MUST treat final as the source of truth for structured assist results. delta preview text is best-effort and may be truncated or differ from the final parsed payload.
• Event-stream and polling payloads redact provider reasoning / thinking traces and explicitly marked internal maintenance/helper content by default; reasoning reveal is debug-only and gated by the same privileged local-debug contract used by trace/assist surfaces.
• Clients SHOULD gracefully fall back to non-streaming assist endpoints when streaming capability is absent or streaming transport fails.

2.4 Pagination & Scan Diagnostics (Management Query Contract)

• GET /openclaw/events and GET /openclaw/approvals include deterministic pagination normalization.
• Responses may include pagination and scan diagnostic objects so clients/operators can detect:
  • normalized limit/offset/cursor values
  • stale/future cursor resets
  • bounded scan truncation or malformed-record skips
• GET /openclaw/preflight/inventory may return snapshot-state diagnostics so clients/operators can detect:
  • whether the response came from a previous cached snapshot
  • whether a background refresh is currently running
  • whether the current snapshot is stale or the last deep scan failed
• Backend/runtime errors outside pagination normalization are still surfaced explicitly (not silently swallowed).

---

3. Limits & Budgets

These limits are contractual and strictly enforced. Clients MUST handle 413 and 429 responses.

Limit	Metric	Default	Configuration Key
Concurrency (Global)	In-flight jobs	2	OPENCLAW_MAX_INFLIGHT_SUBMITS_TOTAL
Concurrency (Webhook)	In-flight jobs	1	OPENCLAW_MAX_INFLIGHT_SUBMITS_WEBHOOK
Concurrency (Bridge)	In-flight jobs	1	OPENCLAW_MAX_INFLIGHT_SUBMITS_BRIDGE
Concurrency (Per-Tenant)	In-flight jobs per tenant	1	OPENCLAW_MAX_INFLIGHT_SUBMITS_PER_TENANT
Payload Size	Rendered workflow	512KB	OPENCLAW_MAX_RENDERED_WORKFLOW_BYTES
Webhook Body	Raw JSON body	10MB	MAX_BODY_SIZE (internal constant)
Trigger Inputs	Input variables	32KB	Hardcoded in api/triggers.py
Log Tail	Max lines	500	Hardcoded in api/route_handlers.py

---

4. Deprecation Policy

4.1 Legacy Routes (/moltbot/)

• Status: Deprecated.
• Policy: Maintained for backward compatibility in v1.x.
• Removal: Scheduled for removal in v2.0.
• Action: Clients should migrate to /openclaw/ prefixes immediately.

4.2 Legacy Config Keys

• Status: Deprecated.
• Policy: Read-only fallback. OPENCLAW_* keys take precedence.
• Action: Operators should rename MOLTBOT_* keys to OPENCLAW_*.