Skip to content
Mimic Docs

Agents API

Agent endpoints cover lifecycle control, execution dispatch, telemetry, and diagnostics.

Common endpoints

  • GET /api/agents list agents in org scope
  • POST /api/agents/{id}/run execute saved script
  • POST /api/agents/{id}/builder/run execute a builder phase snippet on the worker
  • POST /api/agents/{id}/run-snippet execute an ad-hoc Python snippet on the worker
  • POST /api/agents/{id}/run-function execute a reusable function
  • POST /api/agents/{id}/script push or fetch script payloads
  • POST /api/agents/{id}/step-status callback for step-level progress
  • POST /api/agents/{id}/video-analyze create workflow from recording
  • GET /api/agents/{id}/status fetch lightweight live status for UI polling
  • GET /api/agents/{id}/runs fetch the 20 most recent runs with aggregated AI cost
  • GET /api/agents/{id}/run-snippet/status?commandId=... poll ad-hoc snippet execution status/results
  • POST /api/agents/{id}/dexis-images convert DEXIS .dex images to JPEG assets on the worker and upload to S3
  • GET /api/agents/{id}/dexis-images/status?commandId=... poll DEXIS conversion status/results
  • POST /api/agents/{id}/dexis-composite generate a labeled multi-tooth composite PNG from DEXIS images
  • GET /api/agents/{id}/dexis-composite/status?commandId=... poll DEXIS composite status/results
  • POST /api/agent/{id}/activity mark user workspace activity for idle-stop accounting

Lifecycle and VM state

  • POST /api/agent/{id}/action perform lifecycle and control actions.

Supported action values:

  • start
  • stop
  • reboot
  • terminate
  • repair (requires apiKey in body)
  • stop_job
  • start_job
  • start_recording
  • attach_recording
  • stop_recording
  • deploy_extension

Agent pool UI behavior for /app/agents:

  • start and stop are first-class table actions for operators.
  • rename is handled as a form action on /app/agents (not through POST /api/agent/{id}/action).
  • start restores publicTunnelUrl from the latest known tunnel hostname (publicTunnelUrl fallback to tunnelUrl) so Open View links recover immediately after boot.

start_job now performs JIT wake with unified policy enforcement:

  • If the target agent is stopped and org VM setting vmAutoWakeOnJob is enabled, Mimic starts the agent and waits up to 2 minutes for online.
  • If auto-wake is disabled, the endpoint returns 409 with a start-manually message.
  • The same auto-wake policy is enforced across manual dispatch, scheduled runs, and retry attempts.
  • Each wake attempt emits lifecycle events (wake_requested, wake_ready/wake_timeout/wake_failed, or wake_blocked).

reboot action behavior:

  • API returns after the reboot command is issued.
  • Agent status is set to rebooting immediately.
  • Clients should poll GET /api/agents/{id}/status until the agent returns to a stable state.

Polling endpoints for Agent View

Use these endpoints for high-frequency UI updates without re-running heavy page loaders.

GET /api/agents/{id}/status

Returns current persisted agent state and best-effort VM state (3-second timeout guard).

Response shape:

{
  "status": "online",
  "lastSeen": "2026-03-04T12:01:22.000Z",
  "lastActivityAt": "2026-03-04T12:00:10.000Z",
  "publicTunnelUrl": "https://...",
  "vmState": "running",
  "vmIp": "10.0.4.13"
}

GET /api/agents/{id}/runs

Returns up to 20 recent job-backed runs for one agent.

Response shape:

{
  "runs": [
    {
      "id": "job_uuid",
      "status": "success",
      "startedAt": "2026-03-04T11:40:00.000Z",
      "duration": 242000,
      "totalCost": 0.11,
      "totalSteps": 24,
      "passedSteps": 24,
      "failedSteps": 0,
      "error": null
    }
  ]
}

Idle management

  • PATCH /api/agent/{id}/idle-exempt

Request body:

{
  "exempt": true
}

Response:

{
  "success": true,
  "idleAutoStopExempt": true
}

Use this to pin an agent as always-on when org-level auto-stop is enabled.

Builder run endpoint

POST /api/agents/{id}/builder/run supports builder-phase execution for portal scripts.

Body fields:

  • phase required phase name
  • portal defaults to dentrix
  • mimicBaseUrl optional override for callback routing (for example local tunnel testing)
  • workflowPackId, workflowPackVersionId, workflowPackInstallationId optional release-context IDs
  • runtimeBundleId, runtimeBundleManifestKey optional deployed bundle lineage IDs

Runtime behavior:

  • Resolves the effective Mimic base URL from mimicBaseUrl override or PUBLIC_APP_URL.
  • Loads the target agent organization and injects org API credentials into worker env.
  • Injects MIMIC_BASE_URL, MIMIC_API_KEY, AGENT_ID, ORGANIZATION_ID, and workflow-pack lineage env vars before script execution.
  • Creates an isolated session run root on the VM and snapshots source files for reproducible builder runs.

This keeps dashboard callback and run-summary publish paths bound to the correct org context.

Ad-hoc snippet endpoints

Use these endpoints when Agent View needs deterministic worker-side diagnostics that are not modeled as a dedicated API action.

POST /api/agents/{id}/run-snippet

Request body:

{
  "code": "print('hello from worker')"
}

Behavior:

  • Starts a Python snippet on the target worker through VM command execution.
  • Returns immediately with { "commandId": "..." }.
  • Leaves completion tracking to the paired status endpoint.

GET /api/agents/{id}/run-snippet/status?commandId=...

Behavior:

  • Polls worker command status for the snippet run.
  • Returns { "status": "pending" | "success" | "failed", "output"?, "error"? }.
  • Used by Agent View SQL/DEXIS diagnostics flows that require long-running data collection.

Claim workflow endpoint usage

Agent View Claim Workflow (non-standard attachment readiness) does not introduce new API contracts. It composes existing endpoints:

  • POST /api/agents/{id}/run-snippet plus GET /api/agents/{id}/run-snippet/status for Scope and Gather phases.
  • The same run-snippet pair is used for current MVP execution steps after Review approval (attach_xray, write_narrative, import_perio, populate_prosthesis).
  • POST /api/agents/{id}/dexis-composite plus GET /api/agents/{id}/dexis-composite/status for optional composite generation in Gather/Review.
  • Current Agent View Claim Workflow submits patientLookup as String(selectedPatient.patimageid) when requesting composites.

Output handling requirements:

  • Parse snippet output using explicit markers (for example __CW_SCOPE_START__...__CW_SCOPE_END__) before JSON decode.
  • Parse execution payloads from __CW_EXEC_START__...__CW_EXEC_END__ before evaluating step success/failure.
  • Treat missing markers or invalid JSON as failed deterministic diagnostics and surface operator-visible errors.

DEXIS image conversion endpoints

Use these endpoints from Agent View DEXIS tooling to create browser-viewable previews from DEXIS flat-file images.

POST /api/agents/{id}/dexis-images

Request body:

{
  "dexisPath": "\\\\wmeis01\\DEXIS\\DATA\\1\\0\\0\\1\\0\\7\\4\\8",
  "patimageid": 10010748,
  "images": [
    { "ordinal": 1, "filename": "000001.dex" }
  ]
}

Behavior:

  • Runs a Python snippet on the target worker.
  • Reads .dex files (TIFF), including files with prefixed headers.
  • Generates thumbnail and full-size JPEG variants.
  • Uploads assets under dexis/{PATIMAGEID}/... in the configured bucket.
  • Returns { "commandId": "..." } for polling.

GET /api/agents/{id}/dexis-images/status?commandId=...

Behavior:

  • Polls VMService.getSnippetStatus for the command.
  • Returns snippet status and output payload.
  • Mirrors the same polling model used by run-snippet/status.

DEXIS tooth composite endpoints

Use these endpoints from Agent View DEXIS tooling to build one labeled image across multiple requested teeth.

POST /api/agents/{id}/dexis-composite

Request body:

{
  "patientLookup": "10010748",
  "teeth": [18, 31]
}

patientLookup accepts patient name, chart number, PATIMAGEID, or display labels that include PATIMAGEID.

Behavior:

  • Runs a Python snippet on the target worker.
  • Resolves the patient in Dentrix SQL (DDB_PAT) using the lookup value.
  • Parses DEXIS.dat, decodes tooth data from field [10] (FDI -> ADA), and selects the most recent image per requested tooth.
  • Builds a labeled PNG composite with placeholders for missing teeth.
  • Uploads the composite under dexis/comp/... in the configured bucket.
  • Returns { "commandId": "..." } for polling.

GET /api/agents/{id}/dexis-composite/status?commandId=...

Behavior:

  • Polls VMService.getSnippetStatus for the command.
  • On success, output includes JSON between __DEXIS_COMP_START__ and __DEXIS_COMP_END__.
  • JSON includes composite_key, patient, teeth_found, and teeth_missing.

Agent heartbeats and handshake

  • POST /api/agent/heartbeat (machine endpoint, x-api-key required)
  • POST /api/agents/handshake (machine endpoint, x-api-key required)

Heartbeat behavior:

  • Updates lastSeen and tunnel health.
  • Mirrors tunnel hostname into both publicTunnelUrl and tunnelUrl when present.
  • Applies OpenClaw auto-recovery after repeated unhealthy checks.
  • Transitions status to online on recovery.
  • Marks activity timestamps for idle management accounting.

Handshake behavior:

  • Publishes tunnel hostname into both publicTunnelUrl and tunnelUrl.
  • Sets status online.
  • Updates lastSeen and activity timestamp.

Setup-status behavior:

  • POST /api/agent/setup-status also mirrors tunnelUrl into both tunnel fields when provided.

OpenClaw-specific endpoints

  • POST /api/agents/{id}/chat
  • POST /api/agents/{id}/chat/stream
  • POST /api/agents/{id}/manage

Autopilot orchestration

  • POST /api/agents/{id}/autopilot
  • GET /api/agents/{id}/autopilot

POST actions:

  • generate-task: convert natural-language intent to task JSON
  • analyze-script: derive a task plan from existing script + gap prompt
  • start: start a new orchestration session
  • cancel: cancel a running session
  • resume: resume a paused session (optional step override)

GET modes:

  • ?sessionId=<id>: detailed status, current step, attempts, and metrics
  • no sessionId: list recent sessions for the agent

Autopilot stores step attempts, discovered selectors, and generated stable code. Prefer this for iterative portal hardening while keeping RPA-first execution rules.

Use these for conversational execution and managed tooling flows.

Lifecycle events

Agent lifecycle transitions (idle stop, auto-wake, manual actions) are recorded in the agent_lifecycle_event table and surfaced through two channels:

SSE stream

GET /api/agents/{id}/events now includes lifecycle events alongside existing status, log, and job events:

{
  "type": "lifecycle",
  "eventType": "idle_stop_success",
  "source": "idle_monitor",
  "reason": "Idle for 32 minutes (threshold: 30)",
  "previousStatus": "online",
  "currentStatus": "stopped",
  "timestamp": "2025-01-15T10:30:00Z"
}

Event types: idle_stop_attempt, idle_stop_success, idle_stop_failed, wake_requested, wake_blocked, wake_ready, wake_timeout, wake_failed, manual_start, manual_stop, manual_reboot.

Logs endpoint

GET /api/agents/{id}/logs merges lifecycle events into the unified log timeline alongside provisioning and execution logs.

Lifecycle controls

Agent management endpoints may include deploy, heartbeat, and tunnel operations.

Health probes

  • GET /api/health lightweight liveness probe with no database dependency (used by AppRunner health checks, bypasses global request timeout middleware)
  • GET /api/health/deep deep probe with DB connectivity and latency measurement (503 on DB timeout/failure)

Key practices:

  • Require org ownership on every mutation.
  • Protect machine endpoints with API keys.
  • Emit structured lifecycle events for troubleshooting.
  • All lifecycle actions (start, stop, reboot) are recorded with source, reason, and status transition metadata.

Error handling

Return machine-readable error codes for common categories:

  • agent_not_found
  • agent_not_ready
  • invalid_payload
  • execution_timeout
  • permission_denied

Reliability guidance

  • Treat step-status callbacks as idempotent.
  • Do not assume ordered callback delivery.
  • Persist enough context to reconstruct run state after restarts.
  • Prefer RPA-first selectors and reserve agentic fallback for non-deterministic branches.