SymDocs
Passes MCP
All productsSym Workspace APISym Passes MCP
Supportjoinsym.com ↗
Sym Passes MCP

Results and recovery

Distinguish returned output, explicit failures and uncertain execution.

API 2.3.3 · Published service contract ↗

Response contract

Versioned response envelope
{
  "contract": "sym-response-v1",
  "compatibility": "Existing structuredContent and REST success bodies are unchanged. Additive MCP _meta[\"so.sym/response\"] identifies contract, API version, tool, returned/error status and caller requestId when supplied. Returned is not proof of business success or absence of effects.",
  "mcp": {
    "success": "Read structuredContent. Text content mirrors the JSON metadata. Screenshots also include image content blocks; pixel bytes are excluded from structured/text metadata.",
    "error": "Tool execution errors use isError:true and structuredContent.error/status/recovery. HTTP200 can contain an MCP tool error. Protocol, schema and HTTP-admission errors can occur before the handler and need not have tool metadata."
  },
  "rest": {
    "success": "Raw service result, not the MCP content/structuredContent/_meta envelope. Image content GET returns image bytes with private,no-store.",
    "error": "HTTP error status plus JSON error; the service error handler includes ok:false and recovery where available. Early host/origin and OAuth-provider errors may use their own envelopes."
  },
  "payloads": {
    "objects": "{result:{kind,...typed action result}}. MCP structuredContent and REST share this same closed envelope. See /docs/objects.md.",
    "browser": "Ordinary operation: {result:<native value>}; docs: {documentation:...}; screenshots: MCP flattens safe capture metadata into structuredContent and carries pixels separately. REST retains its original result shape.",
    "computer": "Native result under result, except screenshot MCP metadata flattening. Exact operation/session schema comes from the selected Computer Pass.",
    "skill": "{skill:{catalogueId,skillId,version,sourceHash,bundleHash},result:{result:{value:<skill output>}}}. Undefined output may omit value. The immutable version manifest.outputSchema describes the skill value, not the surrounding transport.",
    "catalogue": "Action-dependent objects. Lists return items and nextCursor; get returns exact version metadata/manifest and source unless includeSource:false. Mutation returns are action-specific, not a universal success boolean.",
    "recordings": "Action-dependent list/count/get/asset.get results; recordings are separate from screenshot asset IDs.",
    "account": "Current effective account status, not proof of permission to execute any particular Pass."
  },
  "dynamicBoundaries": [
    "Native operation payloads may vary by installed device/version. Open object schemas intentionally preserve that compatibility.",
    "Catalogue/recording action results are open objects in MCP outputSchema; their prose contract is not a closed per-action field schema.",
    "All browser input schemas are generated; per-verb native output field schemas are not yet universally specified.",
    "OAuth-provider, internal administration and playground APIs are outside the public execution OpenAPI document."
  ],
  "recovery": [
    "A missing dispatchState does not imply not_started.",
    "executionSettled means evaluation returned; effects before an error may have occurred.",
    "Never automatically replay an uncertain action or release its window lock.",
    "A recovery/reload requires explicit approval and verified reset; it preserves the original unknown receipt."
  ]
}

Error schema

Error fields
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "ok": {
      "const": false
    },
    "requestId": {
      "type": "string"
    },
    "accountUrl": {
      "type": "string"
    },
    "recovery": {
      "type": "string"
    },
    "dispatchState": {
      "enum": [
        "not_started",
        "started",
        "acknowledged",
        "unknown"
      ]
    },
    "executionSettled": {
      "type": "boolean"
    },
    "validation": {},
    "javascriptError": {
      "type": "object"
    },
    "diagnosticId": {
      "type": "string"
    },
    "lockState": {
      "type": "string"
    },
    "retryAfterMs": {
      "type": "number"
    },
    "retry_after_ms": {
      "type": "number"
    },
    "tabId": {
      "type": "integer"
    },
    "stepIndex": {
      "type": "integer"
    },
    "completedSteps": {
      "type": "integer"
    }
  },
  "additionalProperties": true
}

Recovery

Recovery guidance
{
  "401": "Reconnect Sign in with Sym.",
  "402": "Open Sym /home to activate or subscribe; no OAuth retry.",
  "403": "Review account plan, selected Pass and native permission; do not widen automatically.",
  "409": "Refresh same-Pass capabilities; if already claimed, inspect state before deciding on a new request.",
  "429": "Back off; do not fan out retries.",
  "503": "Inspect same-Pass connection and operation outcome: a 503 alone does not establish offline state. Do not replay uncertain writes or switch devices."
}

Limits

Service limits
{
  "resultJsonCharacters": 8388608,
  "skillInputBytes": 32000,
  "passPageSize": 50,
  "recordingListMax": 50,
  "recordingEventTranscriptPageMax": 200,
  "recordingAssetMaxBytes": 2097152
}

A successful HTTP response is not proof a browser action succeeded. Check isError and structuredContent. Preserve request, Pass and work-session identities; do not replay an uncertain write.

API versions

The API version is 2.3.3. MCP protocol versions, native capability revisions and immutable skill versions are separate. A published operation catalogue is a reference; retrieve sym_pass_docs for the selected device before use.