> ## Documentation Index
> Fetch the complete documentation index at: https://visorai.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Response schema

> Reference the JSON envelope, run result structure, step result structure, and assertion result objects returned by Visor.

Visor returns a structured JSON envelope for normal commands.

If you run `visor --help`, `visor -h`, or invoke the CLI with no command, the CLI prints a plain-text usage summary instead. If you run `visor --version` or `visor -v`, the CLI prints the package version instead.

## Top-level envelope

| Field | Type | Meaning |
| - | - | - |
| `status` | string | `ok` or `fail` |
| `command_id` | string | Unique command invocation id |
| `started_at` | string | UTC timestamp |
| `ended_at` | string | UTC timestamp |
| `artifacts` | array of string | Artifact paths associated with the response |
| `next_action` | string | Hint for the next logical operation |
| `error` | object | Present only on failure |
| `data` | object | Command-specific payload |

## Error payload

| Field | Type | Meaning |
| - | - | - |
| `code` | string | Structured error code |
| `message` | string | Human-readable summary |
| `likely_cause` | string | Best current explanation |
| `next_step` | string | Suggested remediation |

## Run result

When a scenario run succeeds or fails, `data.run` contains a run result.

| Field | Type | Meaning |
| - | - | - |
| `run_id` | string | Unique run id |
| `platform` | string | `android` or `ios` |
| `device` | string | Resolved device name |
| `started_at` | string | Run start timestamp |
| `ended_at` | string | Run end timestamp |
| `status` | string | `ok` or `fail` |
| `steps` | array | Ordered step results |
| `assertions` | array | Assertion results |
| `artifacts` | array of string | Final copied artifact paths |
| `determinism_signature` | string | SHA-256 signature of normalized run data |
| `seed` | number | Present when the scenario provides a seed |
| `map` | object | Present when mapped execution was considered for the run |
| `error` | object | Present when the run failed |

## Step result

| Field | Type | Meaning |
| - | - | - |
| `id` | string | Step id |
| `command` | string | Executed command |
| `status` | string | `ok` or `fail` |
| `duration_ms` | number | Step duration |
| `details` | object | Adapter-returned payload |
| `error` | object | Present when the step failed |

## Map metadata

Mapped execution metadata uses these fields:

| Field | Type | Meaning |
| - | - | - |
| `enabled` | boolean | Whether Visor enabled map reads and writes |
| `used` | boolean | Whether Visor used cached map knowledge for routing |
| `updated` | boolean | Whether the host app map changed during the command |
| `repaired` | boolean | Whether Visor repaired a stale or missing route |
| `repairs` | number | Count of bounded repair passes used |
| `schema_version` | number | App-map schema version |
| `path` | string | Host path to the persisted app map when enabled |
| `agent_path` | string | Host path to compact AI-only semantic memory |
| `identity` | string | App-map identity, scoped by platform and app id |
| `summary` | object | Path-free app-map inventory attached to `visor discover` responses when the persisted map can be read |

Direct action commands return this object in `data.map`. Scenario runs return it in `data.run.map`. A routed or repaired step may also include `details.map.route`, an ordered list of hidden route actions Visor performed before the requested step action.

`visor discover` adds `data.map.summary` when Visor enables mapped execution and can read the persisted map file. You can safely share the summary in reviews because it does not include the host map path.

| Summary field | Type | Meaning |
| - | - | - |
| `schema_version` | number | App-map schema version read from disk |
| `identity` | string | App-map identity, scoped by platform and app id |
| `app_id` | string | App id used for the map |
| `platform` | string | `android` or `ios` |
| `screens` | number | Count of discovered logical screens |
| `variants` | number | Count of discovered screen variants |
| `edges` | number | Count of recorded navigation edges |
| `actions` | number | Count of stored action affordances |
| `auth_required_variants` | number | Count of variants marked as requiring authentication |
| `updated_at` | string | Last persisted map update timestamp |

## Discovery annotation result

When `visor discover --annotate-current <file|->` succeeds, `data.annotation` confirms the semantic update applied to the variant observed by that command.

| Field | Type | Meaning |
| - | - | - |
| `screen_applied` | boolean | Whether Visor applied screen semantics |
| `actions_inserted` | number | Standalone actions newly stored |
| `actions_updated` | number | Existing semantic actions changed |
| `actions_merged` | number | Source-derived actions enriched while retaining execution metadata |

The same response includes `data.screen.variant_id` and `data.screen.screen_id`. Visor applies annotation before `data.crawl` when you use both options.

`data.observation_token` identifies the exact discovery observation. Pass it back with `--observation-token` to annotate without another device source read. `data.memory` contains the compact current-screen slice, relevant routes, and semantic gaps.

## Route result

`visor route` returns these fields in `data`:

| Field | Type | Meaning |
| - | - | - |
| `action` | string | Always `route` |
| `status` | string | `completed`, `failed`, or `needs_discovery` |
| `goal` | string | Semantic plan goal |
| `selected_path` | string | Path that completed, when successful |
| `attempts` | array | Ordered path attempts and typed step outcomes |
| `checkpoint_path` | string | Atomic checkpoint with the plan, attempts, current observation token, and resume position |
| `current_screen` | object | Compact final screen after success |
| `rediscovery` | object | Exact observation token and compact unknown-state context |
| `recovery` | object | Prior attempts when the daemon recreated a dropped Appium session |

Each step reports `success`, `runtime_failure`, or `verification_failure`. A path reports `completed`, `failed`, or `skipped`.

## Assertion result

Assertion results are plain objects with these fields:

| Field | Type | Meaning |
| - | - | - |
| `id` | string | Assertion id |
| `type` | string | Assertion type |
| `target` | string | Selector that was checked |
| `status` | string | `passed` or `failed` |
| `details` | string | Failure or informational detail |

## Benchmark result payload

Benchmark responses store their command-specific payload in `data`.

| Field | Type | Meaning |
| - | - | - |
| `runs` | number | Number of iterations attempted |
| `threshold` | number | Required determinism threshold |
| `determinismScore` | number | Calculated score |
| `pass` | boolean | Whether the benchmark passed |
| `failures` | number | Count of failed iterations |
| `runIds` | array of string | Run ids created during the benchmark |
| `warnings` | array | Validation warnings carried through from scenario parsing |

## Validation payload

Validation responses use this `data` structure:

| Field | Type | Meaning |
| - | - | - |
| `valid` | boolean | Whether the scenario passed validation |
| `issues` | array | Validation errors and warnings |

Important behavior:

* schema-invalid scenarios return `status: "ok"` with `data.valid: false` and a non-zero process exit code
* malformed JSON or unreadable files return a failure envelope with `status: "fail"`

Each issue contains:

* `severity`
* `code`
* `message`
* `path`

## Example envelope

```json theme={null}
{
  "status": "ok",
  "command_id": "cmd_123456789abc",
  "started_at": "2026-03-29T16:00:00Z",
  "ended_at": "2026-03-29T16:00:01Z",
  "artifacts": [
    "artifacts/run_123/screenshots/001-app-opened.png"
  ],
  "next_action": "report",
  "data": {
    "run": {
      "run_id": "run_123456789abc",
      "platform": "android",
      "device": "emulator-5554",
      "started_at": "2026-03-29T16:00:00Z",
      "ended_at": "2026-03-29T16:00:01Z",
      "status": "ok",
      "steps": [],
      "assertions": [],
      "artifacts": [],
      "determinism_signature": "...",
      "seed": 42
    },
    "warnings": []
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.