{
  "openapi": "3.0.3",
  "info": {
    "title": "FleetDeck Agent API",
    "version": "0.1.1",
    "description": "Device-scoped REST access for assigned owned and rental phones. All successful requests return HTTP 200; action status/result must be checked separately. JSON request bodies use Content-Type: application/json and are limited to 3,000,000 bytes (/api/agent-keys create: 16,384). Unknown fields in request objects are rejected. All account-data responses use Cache-Control: no-store. The API has no automatic physical-action replay. Driver capabilities and hardware permissions vary. Native tools require an operator bridge; scheduled tasks require an external always-on agent worker. See /docs and /downloads/fleetdeck-agent-guide.md."
  },
  "servers": [
    {
      "url": "https://fleetdeck.co"
    }
  ],
  "security": [
    {
      "agentKey": []
    }
  ],
  "tags": [
    {
      "name": "Devices"
    },
    {
      "name": "Sessions and actions"
    },
    {
      "name": "Account"
    },
    {
      "name": "Touch automations"
    },
    {
      "name": "Jobs"
    },
    {
      "name": "Workers and bridges"
    },
    {
      "name": "Dashboard keys"
    }
  ],
  "paths": {
    "/api/v1/devices": {
      "get": {
        "operationId": "list-devices",
        "tags": [
          "Devices"
        ],
        "summary": "List assigned devices",
        "description": "Returns accessible phones assigned to this key and account, including assigned rentals. An empty devices array is valid. Inventory status is not a readiness check; inspect capabilities and verify capture before acting.\n\nRequired permission: devices:read",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "devices:read",
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceList"
                },
                "example": {
                  "devices": [
                    {
                      "id": "device_123",
                      "name": "Test phone",
                      "platform": "android",
                      "model": null,
                      "os": null,
                      "status": "online",
                      "lastSeenAt": "2030-01-01T10:00:00.000Z",
                      "relayRegion": "eu",
                      "agentWebrtc": false,
                      "wdaStatus": "idle"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{deviceId}/capabilities": {
      "get": {
        "operationId": "capabilities",
        "tags": [
          "Devices"
        ],
        "summary": "Discover device capabilities",
        "description": "Returns relay tools plus tools advertised by a currently authorized bridge seen within 15 seconds. Native tool descriptors retain their inputSchema. Discovery indicates available routes, not guaranteed support for every parameter, device state or app.\n\nRequired permission: devices:read",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "devices:read",
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "description": "Exact device ID from List devices. The current key must grant access to this phone.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "device_123"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                },
                "example": {
                  "deviceId": "device_123",
                  "platform": "android",
                  "coordinateSpace": "normalized",
                  "coordinates": "x and y are 0..1 of the current screenshot; inspect again after rotation",
                  "backend": "relay",
                  "capabilities": {
                    "tools": [
                      "screenshot",
                      "tap",
                      "double_tap",
                      "long_press",
                      "swipe",
                      "text",
                      "key",
                      "button",
                      "launch_app",
                      "kill_app",
                      "set_clipboard",
                      "apps",
                      "open_url",
                      "push_media",
                      "media_chunk"
                    ],
                    "acknowledgement": "Relay input is submitted only; use a fresh screenshot to verify the intended change",
                    "limitations": [
                      "UI hierarchy, clipboard reads and privileged tools require a native bridge"
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sessions": {
      "post": {
        "operationId": "acquire-session",
        "tags": [
          "Sessions and actions"
        ],
        "summary": "Acquire a phone session",
        "description": "Acquire exclusive automation access. ttlSeconds defaults to 120, range 30..900, capped at key expiry when the key has one. Always use the returned expiresAt: temporary job keys can give a session less than 15 seconds even with the default TTL. Sessions exclude other automation sessions and active touch schedules, but do not lock out human input or external ADB/WDA clients. Save the returned id. This POST is not idempotent.\n\nRequired permission: devices:read",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "devices:read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionInput"
              },
              "example": {
                "deviceId": "device_123",
                "ttlSeconds": 120
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                },
                "example": {
                  "id": "session_123",
                  "deviceId": "device_123",
                  "expiresAt": "2030-01-01T10:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "DEVICE_BUSY: Another automation session, touch run or in-flight action owns the phone. Fix: Wait for its release/expiry and any running lease. Coordinate operators; do not create parallel controls.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "DEVICE_BUSY": {
                    "summary": "Another automation session, touch run or in-flight action owns the phone.",
                    "value": {
                      "error": "Another automation session, touch run or in-flight action owns the phone.",
                      "code": "DEVICE_BUSY"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sessions/{sessionId}": {
      "delete": {
        "operationId": "release-session",
        "tags": [
          "Sessions and actions"
        ],
        "summary": "Release a session",
        "description": "Closes this key’s session and cancels its queued work. Returns released:true even when there is no matching open session. A running action may finish; its lease can keep the device busy. No request body.\n\nRequired permission: Same key that acquired the session",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "Same key that acquired the session",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "description": "Session ID returned by Acquire a session. Use the key that owns that session.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "session_123"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Released"
                },
                "example": {
                  "released": true
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sessions/{sessionId}/heartbeat": {
      "post": {
        "operationId": "heartbeat-session",
        "tags": [
          "Sessions and actions"
        ],
        "summary": "Renew a session",
        "description": "Sets expiration to now + 120 seconds, capped at key expiry when set, regardless of the initial TTL. Follow the returned expiresAt; job children need frequent session renewal as their worker renews the child token. Renew before expiry; an expired session cannot be revived. No request body.\n\nRequired permission: Same key that acquired the session",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "Same key that acquired the session",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "description": "Session ID returned by Acquire a session. Use the key that owns that session.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "session_123"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionHeartbeat"
                },
                "example": {
                  "id": "session_123",
                  "expiresAt": "2030-01-01T10:00:00.000Z"
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "SESSION_EXPIRED: Session expired, was closed or belongs to another key. Fix: Read the original action if needed, acquire a new session and inspect before new input. Heartbeat before the returned expiresAt; temporary child keys can have much shorter sessions than 120 seconds.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "SESSION_EXPIRED": {
                    "summary": "Session expired, was closed or belongs to another key.",
                    "value": {
                      "error": "Session expired, was closed or belongs to another key.",
                      "code": "SESSION_EXPIRED"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sessions/{sessionId}/actions": {
      "post": {
        "operationId": "submit-action",
        "tags": [
          "Sessions and actions"
        ],
        "summary": "Submit one command",
        "description": "Send {requestId,command}. requestId identifies one intended action within this session. Identical retries return the existing action; changed input with the same ID conflicts. At most one queued/running action per session. Relay work generally finishes during the request; native bridge work returns queued and must be polled. HTTP 200 can contain failed or unknown status. See command payloads and recovery below.\n\nRequired permission: Command-specific device scope; same session key",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "Command-specific device scope; same session key",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "description": "Session ID returned by Acquire a session. Use the key that owns that session.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "session_123"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionInput"
              },
              "example": {
                "requestId": "tap-001",
                "command": {
                  "type": "tap",
                  "x": 0.5,
                  "y": 0.6
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action record. Inspect status and result, not only HTTP status. completed is not proof of application outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionRecord"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "action_123",
                      "requestId": "tap-001",
                      "status": "completed",
                      "kind": "tap",
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": "2030-01-01T10:00:00.000Z",
                      "result": {
                        "status": "submitted",
                        "verified": false,
                        "instruction": "Take a fresh screenshot to verify the intended effect before the next decision"
                      }
                    }
                  },
                  "queued": {
                    "value": {
                      "id": "action_123",
                      "requestId": "tap-001",
                      "status": "queued",
                      "kind": "tap",
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": null,
                      "result": null
                    }
                  },
                  "unknown": {
                    "value": {
                      "id": "action_123",
                      "requestId": "tap-001",
                      "status": "unknown",
                      "kind": "tap",
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": "2030-01-01T10:00:00.000Z",
                      "result": {
                        "code": "DELIVERY_UNKNOWN",
                        "error": "No device response; inspect before retrying"
                      }
                    }
                  },
                  "failed": {
                    "value": {
                      "id": "action_123",
                      "requestId": "tap-001",
                      "status": "failed",
                      "kind": "inspect",
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": "2030-01-01T10:00:00.000Z",
                      "result": {
                        "code": "UNSUPPORTED",
                        "error": "This operation requires a native bridge; inspect device capabilities"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "SESSION_EXPIRED: Session expired, was closed or belongs to another key. Fix: Read the original action if needed, acquire a new session and inspect before new input. Heartbeat before the returned expiresAt; temporary child keys can have much shorter sessions than 120 seconds.\nIDEMPOTENCY_CONFLICT: requestId already identifies a different command. Fix: Retrieve that original action. Reuse its exact command only for lookup/retry; use a new ID only for a newly intended action.\nACTION_BUSY: This session has queued or running work. Fix: Poll the existing action to a terminal state before issuing another.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "SESSION_EXPIRED": {
                    "summary": "Session expired, was closed or belongs to another key.",
                    "value": {
                      "error": "Session expired, was closed or belongs to another key.",
                      "code": "SESSION_EXPIRED"
                    }
                  },
                  "IDEMPOTENCY_CONFLICT": {
                    "summary": "requestId already identifies a different command.",
                    "value": {
                      "error": "requestId already identifies a different command.",
                      "code": "IDEMPOTENCY_CONFLICT"
                    }
                  },
                  "ACTION_BUSY": {
                    "summary": "This session has queued or running work.",
                    "value": {
                      "error": "This session has queued or running work.",
                      "code": "ACTION_BUSY"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "RATE_LIMIT: At most 120 new actions per session in a rolling minute. Fix: Pause until the window clears. Poll existing actions instead of resubmitting new work. No Retry-After header is currently supplied.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "RATE_LIMIT": {
                    "summary": "At most 120 new actions per session in a rolling minute.",
                    "value": {
                      "error": "At most 120 new actions per session in a rolling minute.",
                      "code": "RATE_LIMIT"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sessions/{sessionId}/actions/{requestId}": {
      "get": {
        "operationId": "get-action",
        "tags": [
          "Sessions and actions"
        ],
        "summary": "Read action status without replay",
        "description": "Reads the existing record, including after session expiry/release while the key and device access remain valid. Does not execute the command. Result payloads are cleared opportunistically after one hour; result:null can mean pending work, expiry or retention cleanup. Inspect status and finishedAt.\n\nRequired permission: Same key that acquired the session; continued device access",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "Same key that acquired the session; continued device access",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "description": "Session ID returned by Acquire a session. Use the key that owns that session.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "session_123"
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "description": "Your stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "tap-001"
          }
        ],
        "responses": {
          "200": {
            "description": "Action record. Inspect status and result, not only HTTP status. completed is not proof of application outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionRecord"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "action_123",
                      "requestId": "tap-001",
                      "status": "completed",
                      "kind": "tap",
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": "2030-01-01T10:00:00.000Z",
                      "result": {
                        "status": "submitted",
                        "verified": false,
                        "instruction": "Take a fresh screenshot to verify the intended effect before the next decision"
                      }
                    }
                  },
                  "queued": {
                    "value": {
                      "id": "action_123",
                      "requestId": "tap-001",
                      "status": "queued",
                      "kind": "tap",
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": null,
                      "result": null
                    }
                  },
                  "unknown": {
                    "value": {
                      "id": "action_123",
                      "requestId": "tap-001",
                      "status": "unknown",
                      "kind": "tap",
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": "2030-01-01T10:00:00.000Z",
                      "result": {
                        "code": "DELIVERY_UNKNOWN",
                        "error": "No device response; inspect before retrying"
                      }
                    }
                  },
                  "failed": {
                    "value": {
                      "id": "action_123",
                      "requestId": "tap-001",
                      "status": "failed",
                      "kind": "inspect",
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": "2030-01-01T10:00:00.000Z",
                      "result": {
                        "code": "UNSUPPORTED",
                        "error": "This operation requires a native bridge; inspect device capabilities"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "operationId": "me",
        "tags": [
          "Account"
        ],
        "summary": "Check this key",
        "description": "Connection test for Zapier, Make, n8n and scripts. Returns the account name, key owner, key scopes, expiry and the device IDs assigned to the key. Assigned IDs are not a promise of current access; per-device grants and entitlement are checked on each device call. The token itself is never returned.\n\nRequired permission: Any valid key (no scope required)",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "Any valid key (no scope required)",
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                },
                "example": {
                  "account": {
                    "id": "account_123",
                    "name": "Acme Studio"
                  },
                  "user": {
                    "id": "user_123",
                    "email": "owner@example.com",
                    "role": "owner"
                  },
                  "key": {
                    "id": "key_123",
                    "name": "My agent",
                    "prefix": "fd_example",
                    "scopes": [
                      "devices:read"
                    ],
                    "expiresAt": null,
                    "createdAt": "2030-01-01T10:00:00.000Z"
                  },
                  "deviceIds": [
                    "device_123"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{deviceId}/sequences": {
      "get": {
        "operationId": "list-sequences",
        "tags": [
          "Touch automations"
        ],
        "summary": "List saved touch sequences",
        "description": "Returns sequences saved on this phone in the dashboard sequence editor (summaries, not raw coordinates) and library sequences the key owner owns or bought. compatible:false means the sequence was recorded on a different phone model and cannot run here. Use a sequence id with Run a saved sequence or Create a touch schedule (library:true for library ids).\n\nRequired permission: devices:read",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "devices:read",
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "description": "Exact device ID from List devices. The current key must grant access to this phone.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "device_123"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SequenceList"
                },
                "example": {
                  "deviceId": "device_123",
                  "deviceModelKey": "ios:iphone15,2",
                  "sequences": [
                    {
                      "id": "seq_123",
                      "name": "Open inbox",
                      "steps": 4,
                      "repeat": 1,
                      "durationMs": 5400,
                      "platform": "ios",
                      "modelKey": "ios:iphone15,2",
                      "compatible": true
                    }
                  ],
                  "library": [
                    {
                      "id": "lib_123",
                      "name": "Daily check-in",
                      "platform": "ios",
                      "modelKey": "ios:iphone15,2",
                      "modelLabel": "iPhone 14 Pro",
                      "compatible": true
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{deviceId}/sequence-runs": {
      "post": {
        "operationId": "run-sequence",
        "tags": [
          "Touch automations"
        ],
        "summary": "Run a saved sequence now",
        "description": "Queues the saved sequence on FleetDeck’s touch scheduler, which plays it within a few seconds with the same safety checks as scheduled runs (device access, entitlement, phone model, busy device). requestId is required: repeating the same requestId returns the same run and its current status instead of starting another; a different sequenceId with that requestId is IDEMPOTENCY_CONFLICT. The phone must be online, the scheduler online, and the phone free: release your own automation session first. Poll this endpoint with the same body, or List touch runs filtered by scheduleId, for the outcome. completed means the steps were sent, not that the app reached a given state.\n\nRequired permission: devices:control",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "devices:control",
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "description": "Exact device ID from List devices. The current key must grant access to this phone.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "device_123"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SequenceRunInput"
              },
              "example": {
                "requestId": "run-inbox-001",
                "sequenceId": "seq_123",
                "library": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SequenceRun"
                },
                "example": {
                  "requestId": "run-inbox-001",
                  "scheduleId": "schedule_456",
                  "sequenceId": "seq_123",
                  "existing": false,
                  "status": "queued",
                  "queuedAt": "2030-01-01T10:00:00.000Z",
                  "run": null
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "DEVICE_BUSY: Another automation session, touch run or in-flight action owns the phone. Fix: Wait for its release/expiry and any running lease. Coordinate operators; do not create parallel controls.\nDEVICE_OFFLINE: The phone is not connected, so a sequence cannot start. Fix: Bring the phone online (agent app running, network up), then retry with the same requestId.\nMODEL_MISMATCH: The saved sequence was recorded on a different phone model. Fix: Use a sequence recorded on this phone model; coordinates do not transfer between models.\nIDEMPOTENCY_CONFLICT: requestId already identifies a different command. Fix: Retrieve that original action. Reuse its exact command only for lookup/retry; use a new ID only for a newly intended action.\nLIMIT: Maximum 50 active keys per user or 100 queued jobs per key. Fix: Revoke unused keys or cancel unnecessary queued jobs before creating more.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "DEVICE_BUSY": {
                    "summary": "Another automation session, touch run or in-flight action owns the phone.",
                    "value": {
                      "error": "Another automation session, touch run or in-flight action owns the phone.",
                      "code": "DEVICE_BUSY"
                    }
                  },
                  "DEVICE_OFFLINE": {
                    "summary": "The phone is not connected, so a sequence cannot start.",
                    "value": {
                      "error": "The phone is not connected, so a sequence cannot start.",
                      "code": "DEVICE_OFFLINE"
                    }
                  },
                  "MODEL_MISMATCH": {
                    "summary": "The saved sequence was recorded on a different phone model.",
                    "value": {
                      "error": "The saved sequence was recorded on a different phone model.",
                      "code": "MODEL_MISMATCH"
                    }
                  },
                  "IDEMPOTENCY_CONFLICT": {
                    "summary": "requestId already identifies a different command.",
                    "value": {
                      "error": "requestId already identifies a different command.",
                      "code": "IDEMPOTENCY_CONFLICT"
                    }
                  },
                  "LIMIT": {
                    "summary": "Maximum 50 active keys per user or 100 queued jobs per key.",
                    "value": {
                      "error": "Maximum 50 active keys per user or 100 queued jobs per key.",
                      "code": "LIMIT"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "SCHEDULER_OFFLINE: FleetDeck’s touch scheduler has not checked in recently, so a sequence run would not start. Fix: Retry later with the same requestId.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "SCHEDULER_OFFLINE": {
                    "summary": "FleetDeck’s touch scheduler has not checked in recently, so a sequence run would not start.",
                    "value": {
                      "error": "FleetDeck’s touch scheduler has not checked in recently, so a sequence run would not start.",
                      "code": "SCHEDULER_OFFLINE"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{deviceId}/touch-schedules": {
      "get": {
        "operationId": "list-touch-schedules",
        "tags": [
          "Touch automations"
        ],
        "summary": "List touch schedules",
        "description": "Returns up to 100 active (not deleted) touch schedules for the phone, newest first, plus whether the touch scheduler is online. These are the same schedules shown in the dashboard; they belong to the user, not the key.\n\nRequired permission: devices:read",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "devices:read",
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "description": "Exact device ID from List devices. The current key must grant access to this phone.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "device_123"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TouchScheduleList"
                },
                "example": {
                  "deviceId": "device_123",
                  "schedules": [
                    {
                      "id": "schedule_123",
                      "name": "Morning check-in",
                      "sequenceId": "seq_123",
                      "cron": "0 9 * * 1-5",
                      "timezone": "Europe/Bratislava",
                      "runAt": null,
                      "failureEmail": null,
                      "enabled": true,
                      "nextRunAt": "2030-01-01T10:00:00.000Z",
                      "createdAt": "2030-01-01T10:00:00.000Z"
                    }
                  ],
                  "worker": {
                    "online": true,
                    "lastSeenAt": "2030-01-01T10:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-touch-schedule",
        "tags": [
          "Touch automations"
        ],
        "summary": "Create a touch schedule",
        "description": "Schedules a saved sequence. Supply exactly one of cron (five numeric fields: minute hour day month weekday, evaluated in timezone) or runAt (one ISO instant with offset, 30 seconds to one year ahead). timezone is an IANA zone; never guess it. confirmed must be true, asserting the phone’s layout matches the recorded sequence. failureEmail, if set, must belong to a workspace member. Maximum 100 schedules per device. The schedule is user-owned and keeps running after this key is revoked or expires; delete it explicitly. warning describes overlap with another schedule, if any.\n\nRequired permission: jobs:write + devices:control",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "jobs:write + devices:control",
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "description": "Exact device ID from List devices. The current key must grant access to this phone.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "device_123"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TouchScheduleInput"
              },
              "example": {
                "name": "Morning check-in",
                "sequenceId": "seq_123",
                "cron": "0 9 * * 1-5",
                "timezone": "Europe/Bratislava",
                "confirmed": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TouchScheduleRecord"
                },
                "example": {
                  "id": "schedule_123",
                  "name": "Morning check-in",
                  "sequenceId": "seq_123",
                  "cron": "0 9 * * 1-5",
                  "timezone": "Europe/Bratislava",
                  "runAt": null,
                  "failureEmail": null,
                  "enabled": true,
                  "nextRunAt": "2030-01-01T10:00:00.000Z",
                  "createdAt": "2030-01-01T10:00:00.000Z",
                  "warning": null
                }
              }
            }
          },
          "400": {
            "description": "INVALID_SCHEDULE: The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code). Fix: Use five numeric cron fields or a runAt 30 seconds to one year ahead, a valid IANA timezone, a workspace member email and a sequence saved on this phone.\nINVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_SCHEDULE": {
                    "summary": "The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code).",
                    "value": {
                      "error": "The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code).",
                      "code": "INVALID_SCHEDULE"
                    }
                  },
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "SCHEDULE_CONFLICT: The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran). Fix: Read the message, list the schedules again and apply the change that matches the current state.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "SCHEDULE_CONFLICT": {
                    "summary": "The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran).",
                    "value": {
                      "error": "The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran).",
                      "code": "SCHEDULE_CONFLICT"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "UNAVAILABLE: Touch schedules are not configured on this server. Fix: Use the hosted FleetDeck API or configure the touch scheduler service.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAVAILABLE": {
                    "summary": "Touch schedules are not configured on this server.",
                    "value": {
                      "error": "Touch schedules are not configured on this server.",
                      "code": "UNAVAILABLE"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{deviceId}/touch-schedules/{scheduleId}": {
      "post": {
        "operationId": "update-touch-schedule",
        "tags": [
          "Touch automations"
        ],
        "summary": "Pause, resume or move a touch schedule",
        "description": "enabled:false pauses and asks a running occurrence to stop; enabled:true resumes. runAt (with confirmed:true) moves a one-time run that has not run yet. failureEmail may be changed or set to null. All fields are optional.\n\nRequired permission: jobs:write (+ devices:control to resume or move)",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "jobs:write (+ devices:control to resume or move)",
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "description": "Exact device ID from List devices. The current key must grant access to this phone.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "device_123"
          },
          {
            "name": "scheduleId",
            "in": "path",
            "required": true,
            "description": "Exact identifier returned by this API, owned by the applicable key/account.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "schedule_123"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TouchScheduleUpdate"
              },
              "example": {
                "enabled": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TouchScheduleRecord"
                },
                "example": {
                  "id": "schedule_123",
                  "name": "Morning check-in",
                  "sequenceId": "seq_123",
                  "cron": "0 9 * * 1-5",
                  "timezone": "Europe/Bratislava",
                  "runAt": null,
                  "failureEmail": null,
                  "enabled": false,
                  "nextRunAt": "2030-01-01T10:00:00.000Z",
                  "createdAt": "2030-01-01T10:00:00.000Z",
                  "warning": null
                }
              }
            }
          },
          "400": {
            "description": "INVALID_SCHEDULE: The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code). Fix: Use five numeric cron fields or a runAt 30 seconds to one year ahead, a valid IANA timezone, a workspace member email and a sequence saved on this phone.\nINVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_SCHEDULE": {
                    "summary": "The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code).",
                    "value": {
                      "error": "The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code).",
                      "code": "INVALID_SCHEDULE"
                    }
                  },
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "SCHEDULE_CONFLICT: The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran). Fix: Read the message, list the schedules again and apply the change that matches the current state.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "SCHEDULE_CONFLICT": {
                    "summary": "The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran).",
                    "value": {
                      "error": "The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran).",
                      "code": "SCHEDULE_CONFLICT"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "UNAVAILABLE: Touch schedules are not configured on this server. Fix: Use the hosted FleetDeck API or configure the touch scheduler service.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAVAILABLE": {
                    "summary": "Touch schedules are not configured on this server.",
                    "value": {
                      "error": "Touch schedules are not configured on this server.",
                      "code": "UNAVAILABLE"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "delete-touch-schedule",
        "tags": [
          "Touch automations"
        ],
        "summary": "Delete a touch schedule",
        "description": "Removes the schedule from the list and asks a running occurrence to stop. Its run history is kept. No request body.\n\nRequired permission: jobs:write",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "jobs:write",
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "description": "Exact device ID from List devices. The current key must grant access to this phone.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "device_123"
          },
          {
            "name": "scheduleId",
            "in": "path",
            "required": true,
            "description": "Exact identifier returned by this API, owned by the applicable key/account.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "schedule_123"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ok"
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "description": "INVALID_SCHEDULE: The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code). Fix: Use five numeric cron fields or a runAt 30 seconds to one year ahead, a valid IANA timezone, a workspace member email and a sequence saved on this phone.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_SCHEDULE": {
                    "summary": "The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code).",
                    "value": {
                      "error": "The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code).",
                      "code": "INVALID_SCHEDULE"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "SCHEDULE_CONFLICT: The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran). Fix: Read the message, list the schedules again and apply the change that matches the current state.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "SCHEDULE_CONFLICT": {
                    "summary": "The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran).",
                    "value": {
                      "error": "The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran).",
                      "code": "SCHEDULE_CONFLICT"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "UNAVAILABLE: Touch schedules are not configured on this server. Fix: Use the hosted FleetDeck API or configure the touch scheduler service.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAVAILABLE": {
                    "summary": "Touch schedules are not configured on this server.",
                    "value": {
                      "error": "Touch schedules are not configured on this server.",
                      "code": "UNAVAILABLE"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{deviceId}/touch-runs": {
      "get": {
        "operationId": "list-touch-runs",
        "tags": [
          "Touch automations"
        ],
        "summary": "List touch runs",
        "description": "Run history for touch schedules and sequence runs on this phone, newest first. Query: scheduleId, status (running, completed, failed, cancelled, skipped, interrupted), limit 1..100 (default 20) and cursor (the previous nextCursor). Add format=csv for a spreadsheet download of up to 5,000 rows across pages, starting at cursor if given; X-FleetDeck-Truncated tells whether more rows exist. CSV cells starting with =, +, -, @, tab or carriage return are prefixed with an apostrophe so spreadsheets do not run them as formulas.\n\nRequired permission: devices:read",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "devices:read",
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "description": "Exact device ID from List devices. The current key must grant access to this phone.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "device_123"
          },
          {
            "name": "scheduleId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only runs of this schedule (a sequence run’s scheduleId works too)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "running",
                "completed",
                "failed",
                "cancelled",
                "skipped",
                "interrupted"
              ]
            },
            "description": "Only runs in this state. Expired running leases are reported as interrupted."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Page size for JSON. Ignored for CSV, which pages internally."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "nextCursor from the previous page."
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            },
            "description": "csv returns text/csv with up to 5,000 rows and an X-FleetDeck-Truncated header."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TouchRunList"
                },
                "example": {
                  "runs": [
                    {
                      "id": "run_123",
                      "scheduleId": "schedule_123",
                      "status": "completed",
                      "scheduledAt": "2030-01-01T10:00:00.000Z",
                      "startedAt": "2030-01-01T10:00:00.000Z",
                      "finishedAt": "2030-01-01T10:00:00.000Z",
                      "error": null,
                      "notificationSentAt": null,
                      "notificationAttempts": 0,
                      "durationMs": 41250
                    }
                  ],
                  "nextCursor": null
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "example": "id,scheduleId,scheduleName,status,scheduledAt,startedAt,finishedAt,durationMs,error\r\n"
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs": {
      "get": {
        "operationId": "list-jobs",
        "tags": [
          "Jobs"
        ],
        "summary": "List this key’s jobs",
        "description": "Returns up to 100 jobs, newest scheduledAt first. Jobs are key-owned; another key for the same account cannot list them. There is no pagination cursor or individual job GET endpoint. Prompts and child tokens are not returned.\n\nRequired permission: devices:read",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "devices:read",
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobList"
                },
                "example": {
                  "jobs": [
                    {
                      "id": "job_123",
                      "deviceId": "device_123",
                      "name": "Inspect phone",
                      "scheduledAt": "2030-01-01T10:00:00.000Z",
                      "timezone": "Europe/Bratislava",
                      "status": "queued",
                      "startedAt": null,
                      "finishedAt": null,
                      "cancelRequested": false,
                      "summary": null
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-job",
        "tags": [
          "Jobs"
        ],
        "summary": "Schedule one agent task",
        "description": "scheduledAt must be a future ISO 8601 instant with a timezone offset, before key expiry when the key has one. timezone is a valid IANA zone retained as intent; it does not recalculate that instant. Choose an actual future time instead of copying the illustrative date; expiring keys must remain valid at that time. A no-expiry key has no key-expiry scheduling cutoff, but each job still has a finite deadline and renewable lease. name 1..120 and prompt 1..16000 trimmed characters; deadlineSeconds 60..3600, default 900. This POST has no idempotency key. Keep an external worker running with this same key; FleetDeck does not host the model or wake a laptop.\n\nRequired permission: jobs:write + devices:control",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "jobs:write + devices:control",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobInput"
              },
              "example": {
                "deviceId": "device_123",
                "name": "Inspect phone",
                "prompt": "Take a screenshot and describe the current screen. Do not change app state.",
                "scheduledAt": "2030-01-01T11:00:00+01:00",
                "timezone": "Europe/Bratislava",
                "deadlineSeconds": 900
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobRecord"
                },
                "example": {
                  "id": "job_123",
                  "deviceId": "device_123",
                  "name": "Inspect phone",
                  "scheduledAt": "2030-01-01T10:00:00.000Z",
                  "timezone": "Europe/Bratislava",
                  "status": "queued",
                  "startedAt": null,
                  "finishedAt": null,
                  "cancelRequested": false,
                  "summary": null
                }
              }
            }
          },
          "400": {
            "description": "INVALID_TIME: Schedule is in the past or at/after a configured key expiry. Fix: Choose a future instant with the correct UTC offset, before key expiry if set. A no-expiry key has no key-expiry cutoff; job deadlines and leases still apply.\nINVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_TIME": {
                    "summary": "Schedule is in the past or at/after a configured key expiry.",
                    "value": {
                      "error": "Schedule is in the past or at/after a configured key expiry.",
                      "code": "INVALID_TIME"
                    }
                  },
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "LIMIT: Maximum 50 active keys per user or 100 queued jobs per key. Fix: Revoke unused keys or cancel unnecessary queued jobs before creating more.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "LIMIT": {
                    "summary": "Maximum 50 active keys per user or 100 queued jobs per key.",
                    "value": {
                      "error": "Maximum 50 active keys per user or 100 queued jobs per key.",
                      "code": "LIMIT"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{jobId}": {
      "delete": {
        "operationId": "cancel-job",
        "tags": [
          "Jobs"
        ],
        "summary": "Request job cancellation",
        "description": "Queued jobs become cancelled immediately. Running jobs set cancelRequested, revoke their child token and close child sessions; the worker must stop the process on its next heartbeat. Returns cancelled:true as acknowledgement, not proof that all physical effects stopped or were reversed. No request body.\n\nRequired permission: jobs:write; same key that created the job",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "jobs:write; same key that created the job",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "Job ID returned by Schedule a job or List jobs, owned by the current key.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "job_123"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cancelled"
                },
                "example": {
                  "cancelled": true
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/worker/jobs/claim": {
      "post": {
        "operationId": "claim-job",
        "tags": [
          "Workers and bridges"
        ],
        "summary": "Claim a due task",
        "description": "Returns job:null when no eligible task exists or the worker/device is busy. A job more than 30 seconds late becomes missed when the worker next polls and is not replayed. A claimed job receives a 15-second lease and device-bound child token with only the parent’s device scopes. Treat token as a secret. Start the agent once and heartbeat using the parent key.\n\nRequired permission: worker:run; same key that created the job",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "worker:run; same key that created the job",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkerInput"
              },
              "example": {
                "workerId": "worker-01"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobClaim"
                },
                "examples": {
                  "success": {
                    "value": {
                      "job": {
                        "id": "job_123",
                        "deviceId": "device_123",
                        "prompt": "Take a screenshot and describe the current screen.",
                        "deadlineSeconds": 900,
                        "scheduledAt": "2030-01-01T10:00:00.000Z",
                        "token": "<ephemeral child token; never log>"
                      }
                    }
                  },
                  "idle": {
                    "value": {
                      "job": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/worker/jobs/{jobId}/heartbeat": {
      "post": {
        "operationId": "heartbeat-job",
        "tags": [
          "Workers and bridges"
        ],
        "summary": "Renew job authorization",
        "description": "Use the parent key and original workerId. Returns cancel:true for absent/expired leases, cancellation or a passed deadline. Stop the process when true or when renewal fails. Otherwise extends the lease and child-token expiry by 15 seconds, capped at the job deadline and parent expiry when set. It also extends still-active, unclosed sessions owned by that child key to the same finite expiry. It never revives an expired or released session. No-expiry parent keys still produce short-lived child credentials and finite job leases. The supplied CLI heartbeats every 4 seconds with each HTTP call bounded to 5 seconds.\n\nRequired permission: worker:run; owning key and workerId",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "worker:run; owning key and workerId",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "Job ID returned by Schedule a job or List jobs, owned by the current key.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "job_123"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkerInput"
              },
              "example": {
                "workerId": "worker-01"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobHeartbeat"
                },
                "examples": {
                  "success": {
                    "value": {
                      "cancel": false
                    }
                  },
                  "stop": {
                    "value": {
                      "cancel": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/worker/jobs/{jobId}/complete": {
      "post": {
        "operationId": "complete-job",
        "tags": [
          "Workers and bridges"
        ],
        "summary": "Record the agent process outcome",
        "description": "Requires an unexpired running lease. status is completed, failed or cancelled; summary defaults to empty and is at most 2,000 characters. A requested cancellation overrides status to cancelled. Revokes the child token and closes child sessions. completed describes process exit, not verified publication or app outcome. Do not rerun the job if completion reporting fails.\n\nRequired permission: worker:run; owning key and workerId",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "worker:run; owning key and workerId",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "Job ID returned by Schedule a job or List jobs, owned by the current key.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "job_123"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobCompleteInput"
              },
              "example": {
                "workerId": "worker-01",
                "status": "completed",
                "summary": "Agent finished; consult its retained screenshot evidence."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recorded"
                },
                "example": {
                  "recorded": true
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "LEASE_EXPIRED: Completion report no longer owns a live action/job lease. Fix: Do not rerun the work. Inspect action/job status and the device; record the uncertainty in agent evidence.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "LEASE_EXPIRED": {
                    "summary": "Completion report no longer owns a live action/job lease.",
                    "value": {
                      "error": "Completion report no longer owns a live action/job lease.",
                      "code": "LEASE_EXPIRED"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/worker/bridge/claim": {
      "post": {
        "operationId": "claim-bridge",
        "tags": [
          "Workers and bridges"
        ],
        "summary": "Register a bridge and claim one action",
        "description": "Poll with a stable workerId and truthful capabilities. backend is at most 40 characters, tools contains up to 128 strings (128 characters each); nativeTools contains up to 128 discovered descriptors. Registration stays fresh for 15 seconds. Another fresh bridge gets BRIDGE_BUSY. Returns action:null when idle or an action with a 25-second execution deadline and 30-second lease. Execute it at most once; there is no action-lease heartbeat.\n\nRequired permission: worker:run + device grant",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "worker:run + device grant",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BridgeClaimInput"
              },
              "example": {
                "workerId": "bridge-01",
                "deviceId": "device_123",
                "capabilities": {
                  "backend": "adb",
                  "tools": [
                    "screenshot",
                    "inspect",
                    "apps",
                    "tap",
                    "double_tap",
                    "long_press",
                    "swipe",
                    "text",
                    "key",
                    "button",
                    "open_url",
                    "launch_app",
                    "kill_app"
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BridgeClaim"
                },
                "examples": {
                  "success": {
                    "value": {
                      "action": {
                        "id": "action_123",
                        "command": {
                          "type": "tap",
                          "x": 0.5,
                          "y": 0.6
                        },
                        "deadline": "2030-01-01T10:00:00.000Z"
                      }
                    }
                  },
                  "idle": {
                    "value": {
                      "action": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "BRIDGE_BUSY: Another authorized bridge was seen for this device within 15 seconds. Fix: Stop the duplicate bridge or wait until the previous registration is stale. Keep worker IDs stable.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "BRIDGE_BUSY": {
                    "summary": "Another authorized bridge was seen for this device within 15 seconds.",
                    "value": {
                      "error": "Another authorized bridge was seen for this device within 15 seconds.",
                      "code": "BRIDGE_BUSY"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/worker/bridge/{actionId}/complete": {
      "post": {
        "operationId": "complete-bridge",
        "tags": [
          "Workers and bridges"
        ],
        "summary": "Record a native action outcome",
        "description": "Use the action.id from claim, not the caller’s requestId. status is completed, failed or unknown. result is driver-defined JSON (null is allowed). Requires the original running action lease and bridge identity. Record unknown if delivery or effect is uncertain. Never re-execute an action to recover from a reporting failure.\n\nRequired permission: worker:run; registered key, deviceId and workerId",
        "security": [
          {
            "agentKey": []
          }
        ],
        "x-required-scopes": "worker:run; registered key, deviceId and workerId",
        "parameters": [
          {
            "name": "actionId",
            "in": "path",
            "required": true,
            "description": "Internal action ID returned by the bridge claim. This is distinct from the client requestId.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "action_123"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BridgeCompleteInput"
              },
              "example": {
                "workerId": "bridge-01",
                "deviceId": "device_123",
                "status": "completed",
                "result": {
                  "status": "applied",
                  "verified": false,
                  "instruction": "Inspect the screen to verify application state"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recorded"
                },
                "example": {
                  "recorded": true
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "LEASE_EXPIRED: Completion report no longer owns a live action/job lease. Fix: Do not rerun the work. Inspect action/job status and the device; record the uncertainty in agent evidence.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "LEASE_EXPIRED": {
                    "summary": "Completion report no longer owns a live action/job lease.",
                    "value": {
                      "error": "Completion report no longer owns a live action/job lease.",
                      "code": "LEASE_EXPIRED"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent-keys": {
      "get": {
        "operationId": "list-keys",
        "tags": [
          "Dashboard keys"
        ],
        "summary": "List signed-in user’s keys",
        "description": "Dashboard management endpoint; bearer keys cannot manage keys. Returns at most 100 user-created keys, newest first, with metadata only. Ephemeral job-child credentials are hidden and do not consume the active user-key quota. Tokens and hashes are never returned by this endpoint.\n\nRequired permission: Dashboard session cookie",
        "security": [
          {
            "dashboardSession": []
          }
        ],
        "x-required-scopes": "Dashboard session cookie",
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyList"
                },
                "example": {
                  "keys": [
                    {
                      "id": "key_123",
                      "name": "My agent",
                      "prefix": "fd_example",
                      "scopes": [
                        "devices:read"
                      ],
                      "deviceIds": [
                        "device_123"
                      ],
                      "expiresAt": null,
                      "revokedAt": null,
                      "createdAt": "2030-01-01T10:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-key",
        "tags": [
          "Dashboard keys"
        ],
        "summary": "Create a scoped key",
        "description": "Create a key for selected accessible, entitled phones. name is 1..80 trimmed characters; scopes has 1..6 entries from the scope list; deviceIds 1..100; expiresInDays accepts an integer 1..365 or null for no expiry; omission defaults to 30 days. The response expiresAt is an ISO timestamp or null for no expiry. No-expiry keys remain revocable and subject to device grants, account access and entitlement checks; they do not make sessions, job leases or child credentials permanent. Maximum 50 active keys per user, including nonrevoked no-expiry keys. Request body limit is 16,384 bytes. Token is returned once: save it securely. Prefer the /agents dashboard.\n\nRequired permission: Dashboard session cookie + same Origin",
        "security": [
          {
            "dashboardSession": []
          }
        ],
        "x-required-scopes": "Dashboard session cookie + same Origin",
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "example": "https://fleetdeck.co",
            "description": "Must match this app’s origin or configured public app origin."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyInput"
              },
              "examples": {
                "never": {
                  "summary": "No expiry; revocation and finite work leases still apply",
                  "value": {
                    "name": "My agent",
                    "scopes": [
                      "devices:read"
                    ],
                    "deviceIds": [
                      "device_123"
                    ],
                    "expiresInDays": null
                  }
                },
                "thirtyDays": {
                  "summary": "Expires after 30 days (also the default when omitted)",
                  "value": {
                    "name": "My agent",
                    "scopes": [
                      "devices:read"
                    ],
                    "deviceIds": [
                      "device_123"
                    ],
                    "expiresInDays": 30
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedKey"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "key_123",
                      "name": "My agent",
                      "prefix": "fd_example",
                      "scopes": [
                        "devices:read"
                      ],
                      "deviceIds": [
                        "device_123"
                      ],
                      "expiresAt": null,
                      "revokedAt": null,
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "token": "<shown once; save securely>"
                    }
                  },
                  "expiring": {
                    "value": {
                      "id": "key_123",
                      "name": "My agent",
                      "prefix": "fd_example",
                      "scopes": [
                        "devices:read"
                      ],
                      "deviceIds": [
                        "device_123"
                      ],
                      "expiresAt": "2030-01-31T10:00:00.000Z",
                      "revokedAt": null,
                      "createdAt": "2030-01-01T10:00:00.000Z",
                      "token": "<shown once; save securely>"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "INVALID_JSON: Missing or malformed JSON. Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INVALID_JSON": {
                    "summary": "Missing or malformed JSON.",
                    "value": {
                      "error": "Missing or malformed JSON.",
                      "code": "INVALID_JSON"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "PLAN_REQUIRED: Device account has no active entitlement. Fix: Restore an active device entitlement in the workspace before controlling it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PLAN_REQUIRED": {
                    "summary": "Device account has no active entitlement.",
                    "value": {
                      "error": "Device account has no active entitlement.",
                      "code": "PLAN_REQUIRED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN: Required scope, device grant, account membership or worker identity is missing. Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.\nORIGIN: Dashboard mutation lacks an allowed Origin header. Fix: Use the signed-in same-origin dashboard. Cross-origin key management is not supported.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "FORBIDDEN": {
                    "summary": "Required scope, device grant, account membership or worker identity is missing.",
                    "value": {
                      "error": "Required scope, device grant, account membership or worker identity is missing.",
                      "code": "FORBIDDEN"
                    }
                  },
                  "ORIGIN": {
                    "summary": "Dashboard mutation lacks an allowed Origin header.",
                    "value": {
                      "error": "Dashboard mutation lacks an allowed Origin header.",
                      "code": "ORIGIN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "LIMIT: Maximum 50 active keys per user or 100 queued jobs per key. Fix: Revoke unused keys or cancel unnecessary queued jobs before creating more.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "LIMIT": {
                    "summary": "Maximum 50 active keys per user or 100 queued jobs per key.",
                    "value": {
                      "error": "Maximum 50 active keys per user or 100 queued jobs per key.",
                      "code": "LIMIT"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "TOO_LARGE: Request body exceeds its byte limit. Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "TOO_LARGE": {
                    "summary": "Request body exceeds its byte limit.",
                    "value": {
                      "error": "Request body exceeds its byte limit.",
                      "code": "TOO_LARGE"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "CONTENT_TYPE: A supplied JSON body lacks application/json content type. Fix: Set Content-Type: application/json; charset parameters are accepted.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "CONTENT_TYPE": {
                    "summary": "A supplied JSON body lacks application/json content type.",
                    "value": {
                      "error": "A supplied JSON body lacks application/json content type.",
                      "code": "CONTENT_TYPE"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "VALIDATION: A field, type, bound or unknown property failed validation. Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "examples": {
                  "VALIDATION": {
                    "summary": "A field, type, bound or unknown property failed validation.",
                    "value": {
                      "error": "Invalid request",
                      "code": "VALIDATION",
                      "issues": [
                        {
                          "path": [
                            "deviceId"
                          ],
                          "message": "Required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent-keys/{keyId}": {
      "delete": {
        "operationId": "revoke-key",
        "tags": [
          "Dashboard keys"
        ],
        "summary": "Revoke a key or purge its records",
        "description": "Without query parameters, revokes the key, closes sessions, cancels queued jobs and flags running jobs for cancellation. Audit metadata is retained. After revoking, add ?purge=1 to permanently remove this key, child keys and associated session/action/job records. Purge refuses active action/job leases. Responses are {revoked:true} or {removed:true}. No request body.\n\nRequired permission: Owning dashboard session cookie + same Origin",
        "security": [
          {
            "dashboardSession": []
          }
        ],
        "x-required-scopes": "Owning dashboard session cookie + same Origin",
        "parameters": [
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "description": "Exact identifier returned by this API, owned by the applicable key/account.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "example": "key_123"
          },
          {
            "name": "purge",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Permanently remove a previously revoked key and associated records. Active leases block purge."
          },
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "example": "https://fleetdeck.co",
            "description": "Must match this app’s origin or configured public app origin."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. All API successes, including creates and deletes, use HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyRemoval"
                },
                "examples": {
                  "success": {
                    "value": {
                      "revoked": true
                    }
                  },
                  "purged": {
                    "value": {
                      "removed": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "UNAUTHORIZED: Missing, malformed, expired or revoked credential; user verification/password state can also deny access. Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "UNAUTHORIZED": {
                    "summary": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                    "value": {
                      "error": "Missing, malformed, expired or revoked credential; user verification/password state can also deny access.",
                      "code": "UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "ORIGIN: Dashboard mutation lacks an allowed Origin header. Fix: Use the signed-in same-origin dashboard. Cross-origin key management is not supported.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "ORIGIN": {
                    "summary": "Dashboard mutation lacks an allowed Origin header.",
                    "value": {
                      "error": "Dashboard mutation lacks an allowed Origin header.",
                      "code": "ORIGIN"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: Unknown route or resource unavailable to this caller. Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "NOT_FOUND": {
                    "summary": "Unknown route or resource unavailable to this caller.",
                    "value": {
                      "error": "Unknown route or resource unavailable to this caller.",
                      "code": "NOT_FOUND"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "REVOKE_FIRST: Purge attempted on a key that is not revoked. Fix: Revoke the key first, then purge only if permanent record deletion is intended.\nWORK_ACTIVE: Purge would delete an active action/job lease. Fix: Wait for work and leases to finish, then retry purge. Do not erase active work history.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "REVOKE_FIRST": {
                    "summary": "Purge attempted on a key that is not revoked.",
                    "value": {
                      "error": "Purge attempted on a key that is not revoked.",
                      "code": "REVOKE_FIRST"
                    }
                  },
                  "WORK_ACTIVE": {
                    "summary": "Purge would delete an active action/job lease.",
                    "value": {
                      "error": "Purge would delete an active action/job lease.",
                      "code": "WORK_ACTIVE"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL: Unexpected service error. Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "INTERNAL": {
                    "summary": "Unexpected service error.",
                    "value": {
                      "error": "Unexpected service error.",
                      "code": "INTERNAL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "fd_<43 base64url characters>",
        "description": "Create a device-scoped key in /agents. Supply via secret manager/environment; never put it in a URL or log."
      },
      "dashboardSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "rd_session",
        "description": "Existing FleetDeck browser login. Key-management writes additionally require a matching Origin."
      }
    },
    "schemas": {
      "Command": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "screenshot"
                ],
                "description": "Discriminator that selects the action or content shape."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "inspect"
                ],
                "description": "Discriminator that selects the action or content shape."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "apps"
                ],
                "description": "Discriminator that selects the action or content shape."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "tap"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "x": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
              },
              "y": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
              }
            },
            "required": [
              "type",
              "x",
              "y"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "double_tap"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "x": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
              },
              "y": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
              }
            },
            "required": [
              "type",
              "x",
              "y"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "long_press"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "x": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
              },
              "y": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
              },
              "ms": {
                "type": "integer",
                "minimum": 200,
                "maximum": 1500,
                "default": 600,
                "description": "Gesture duration in milliseconds. The valid range depends on the action type."
              }
            },
            "required": [
              "type",
              "x",
              "y"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "swipe"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "from": {
                "type": "object",
                "properties": {
                  "x": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                  },
                  "y": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                  }
                },
                "required": [
                  "x",
                  "y"
                ],
                "additionalProperties": false,
                "description": "Start point of the gesture, using normalized screen coordinates."
              },
              "to": {
                "type": "object",
                "properties": {
                  "x": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                  },
                  "y": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                  }
                },
                "required": [
                  "x",
                  "y"
                ],
                "additionalProperties": false,
                "description": "End point of the gesture, using normalized screen coordinates."
              },
              "ms": {
                "type": "integer",
                "minimum": 100,
                "maximum": 1200,
                "default": 300,
                "description": "Gesture duration in milliseconds. The valid range depends on the action type."
              }
            },
            "required": [
              "type",
              "from",
              "to"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "text"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "value": {
                "type": "string",
                "maxLength": 16000,
                "description": "Text to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it."
              }
            },
            "required": [
              "type",
              "value"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "key"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "key": {
                "type": "string",
                "enum": [
                  "return",
                  "backspace",
                  "space",
                  "tab",
                  "up",
                  "down",
                  "left",
                  "right"
                ],
                "description": "Keyboard key to send to the currently focused control."
              }
            },
            "required": [
              "type",
              "key"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "button"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "name": {
                "type": "string",
                "enum": [
                  "home",
                  "back",
                  "app_switcher",
                  "wake",
                  "lock",
                  "volume_up",
                  "volume_down"
                ],
                "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
              }
            },
            "required": [
              "type",
              "name"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "open_url"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "url": {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096,
                "description": "Open an absolute scheme URL, maximum 4,096 characters. javascript:, data:, file: and control characters are rejected. Custom app schemes need an installed handler. Stock iPhone relay requires a native bridge for this command."
              }
            },
            "required": [
              "type",
              "url"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "launch_app"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "bundleId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
                "description": "Installed iOS bundle ID or Android package name."
              }
            },
            "required": [
              "type",
              "bundleId"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "kill_app"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "bundleId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
                "description": "Installed iOS bundle ID or Android package name."
              }
            },
            "required": [
              "type",
              "bundleId"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "clipboard_get"
                ],
                "description": "Discriminator that selects the action or content shape."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "set_clipboard"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "value": {
                "type": "string",
                "maxLength": 16000,
                "description": "Text to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it."
              }
            },
            "required": [
              "type",
              "value"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "push_media"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "fileName": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "pattern": "^[A-Za-z0-9][A-Za-z0-9._ -]*$",
                "description": "1..160 characters; starts alphanumeric, then letters, digits, dot, underscore, space or hyphen. No path separators; not . or ..."
              },
              "mime": {
                "type": "string",
                "enum": [
                  "image/jpeg",
                  "image/png",
                  "video/mp4"
                ],
                "description": "Media MIME type. It must match the actual source bytes."
              },
              "dataB64": {
                "type": "string",
                "minLength": 4,
                "maxLength": 2800000,
                "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
                "description": "Complete padded base64 bytes without a data URL prefix. Use the complete file or the current ordered chunk."
              }
            },
            "required": [
              "type",
              "fileName",
              "mime",
              "dataB64"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "media_chunk"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "uploadId": {
                "type": "string",
                "format": "uuid",
                "description": "One UUID shared by all chunks of the same upload."
              },
              "chunkIndex": {
                "type": "integer",
                "minimum": 0,
                "maximum": 199,
                "description": "Zero-based chunk index. Send in order, beginning at 0; it must be smaller than chunkCount."
              },
              "chunkCount": {
                "type": "integer",
                "minimum": 1,
                "maximum": 200,
                "description": "Total chunks in this upload. Must not exceed totalBytes; keep it constant across chunks."
              },
              "totalBytes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 104857600,
                "description": "Decoded byte size of the complete file. A one-chunk upload must decode to exactly this length."
              },
              "fileName": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "pattern": "^[A-Za-z0-9][A-Za-z0-9._ -]*$",
                "description": "1..160 characters; starts alphanumeric, then letters, digits, dot, underscore, space or hyphen. No path separators; not . or ..."
              },
              "mime": {
                "type": "string",
                "enum": [
                  "image/jpeg",
                  "image/png",
                  "video/mp4"
                ],
                "description": "Media MIME type. It must match the actual source bytes."
              },
              "dataB64": {
                "type": "string",
                "minLength": 4,
                "maxLength": 1400000,
                "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
                "description": "Complete padded base64 bytes without a data URL prefix. Use the complete file or the current ordered chunk."
              }
            },
            "required": [
              "type",
              "uploadId",
              "chunkIndex",
              "chunkCount",
              "totalBytes",
              "fileName",
              "mime",
              "dataB64"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "native_tool"
                ],
                "description": "Discriminator that selects the action or content shape."
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$",
                "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
              },
              "arguments": {
                "type": "object",
                "additionalProperties": {},
                "default": {},
                "description": "Arguments for the discovered native tool, validated against its advertised inputSchema."
              }
            },
            "required": [
              "type",
              "name"
            ],
            "additionalProperties": false
          }
        ]
      },
      "ActionInput": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Your stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT."
          },
          "command": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "screenshot"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  }
                },
                "required": [
                  "type"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "inspect"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  }
                },
                "required": [
                  "type"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "apps"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  }
                },
                "required": [
                  "type"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "tap"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "x": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                  },
                  "y": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                  }
                },
                "required": [
                  "type",
                  "x",
                  "y"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "double_tap"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "x": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                  },
                  "y": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                  }
                },
                "required": [
                  "type",
                  "x",
                  "y"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "long_press"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "x": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                  },
                  "y": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                  },
                  "ms": {
                    "type": "integer",
                    "minimum": 200,
                    "maximum": 1500,
                    "default": 600,
                    "description": "Gesture duration in milliseconds. The valid range depends on the action type."
                  }
                },
                "required": [
                  "type",
                  "x",
                  "y"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "swipe"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "from": {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                      },
                      "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                      }
                    },
                    "required": [
                      "x",
                      "y"
                    ],
                    "additionalProperties": false,
                    "description": "Start point of the gesture, using normalized screen coordinates."
                  },
                  "to": {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                      },
                      "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                      }
                    },
                    "required": [
                      "x",
                      "y"
                    ],
                    "additionalProperties": false,
                    "description": "End point of the gesture, using normalized screen coordinates."
                  },
                  "ms": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 1200,
                    "default": 300,
                    "description": "Gesture duration in milliseconds. The valid range depends on the action type."
                  }
                },
                "required": [
                  "type",
                  "from",
                  "to"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "text"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "value": {
                    "type": "string",
                    "maxLength": 16000,
                    "description": "Text to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it."
                  }
                },
                "required": [
                  "type",
                  "value"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "key"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "key": {
                    "type": "string",
                    "enum": [
                      "return",
                      "backspace",
                      "space",
                      "tab",
                      "up",
                      "down",
                      "left",
                      "right"
                    ],
                    "description": "Keyboard key to send to the currently focused control."
                  }
                },
                "required": [
                  "type",
                  "key"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "button"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "name": {
                    "type": "string",
                    "enum": [
                      "home",
                      "back",
                      "app_switcher",
                      "wake",
                      "lock",
                      "volume_up",
                      "volume_down"
                    ],
                    "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                  }
                },
                "required": [
                  "type",
                  "name"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "open_url"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "url": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4096,
                    "description": "Open an absolute scheme URL, maximum 4,096 characters. javascript:, data:, file: and control characters are rejected. Custom app schemes need an installed handler. Stock iPhone relay requires a native bridge for this command."
                  }
                },
                "required": [
                  "type",
                  "url"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "launch_app"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "bundleId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
                    "description": "Installed iOS bundle ID or Android package name."
                  }
                },
                "required": [
                  "type",
                  "bundleId"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "kill_app"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "bundleId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
                    "description": "Installed iOS bundle ID or Android package name."
                  }
                },
                "required": [
                  "type",
                  "bundleId"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "clipboard_get"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  }
                },
                "required": [
                  "type"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "set_clipboard"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "value": {
                    "type": "string",
                    "maxLength": 16000,
                    "description": "Text to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it."
                  }
                },
                "required": [
                  "type",
                  "value"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "push_media"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "fileName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._ -]*$",
                    "description": "1..160 characters; starts alphanumeric, then letters, digits, dot, underscore, space or hyphen. No path separators; not . or ..."
                  },
                  "mime": {
                    "type": "string",
                    "enum": [
                      "image/jpeg",
                      "image/png",
                      "video/mp4"
                    ],
                    "description": "Media MIME type. It must match the actual source bytes."
                  },
                  "dataB64": {
                    "type": "string",
                    "minLength": 4,
                    "maxLength": 2800000,
                    "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
                    "description": "Complete padded base64 bytes without a data URL prefix. Use the complete file or the current ordered chunk."
                  }
                },
                "required": [
                  "type",
                  "fileName",
                  "mime",
                  "dataB64"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "media_chunk"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "uploadId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "One UUID shared by all chunks of the same upload."
                  },
                  "chunkIndex": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 199,
                    "description": "Zero-based chunk index. Send in order, beginning at 0; it must be smaller than chunkCount."
                  },
                  "chunkCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 200,
                    "description": "Total chunks in this upload. Must not exceed totalBytes; keep it constant across chunks."
                  },
                  "totalBytes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 104857600,
                    "description": "Decoded byte size of the complete file. A one-chunk upload must decode to exactly this length."
                  },
                  "fileName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._ -]*$",
                    "description": "1..160 characters; starts alphanumeric, then letters, digits, dot, underscore, space or hyphen. No path separators; not . or ..."
                  },
                  "mime": {
                    "type": "string",
                    "enum": [
                      "image/jpeg",
                      "image/png",
                      "video/mp4"
                    ],
                    "description": "Media MIME type. It must match the actual source bytes."
                  },
                  "dataB64": {
                    "type": "string",
                    "minLength": 4,
                    "maxLength": 1400000,
                    "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
                    "description": "Complete padded base64 bytes without a data URL prefix. Use the complete file or the current ordered chunk."
                  }
                },
                "required": [
                  "type",
                  "uploadId",
                  "chunkIndex",
                  "chunkCount",
                  "totalBytes",
                  "fileName",
                  "mime",
                  "dataB64"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "native_tool"
                    ],
                    "description": "Discriminator that selects the action or content shape."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[A-Za-z0-9._:-]+$",
                    "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                  },
                  "arguments": {
                    "type": "object",
                    "additionalProperties": {},
                    "default": {},
                    "description": "Arguments for the discovered native tool, validated against its advertised inputSchema."
                  }
                },
                "required": [
                  "type",
                  "name"
                ],
                "additionalProperties": false
              }
            ],
            "description": "One strict action payload, selected by its type. Unknown fields are rejected."
          }
        },
        "required": [
          "requestId",
          "command"
        ],
        "additionalProperties": false
      },
      "SessionInput": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "ttlSeconds": {
            "type": "integer",
            "minimum": 30,
            "maximum": 900,
            "default": 120,
            "description": "Requested session lifetime in seconds. Credential expiry can shorten the returned lease. Renew before expiresAt."
          }
        },
        "required": [
          "deviceId"
        ],
        "additionalProperties": false
      },
      "JobInput": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16000,
            "description": "Task instructions passed to the external agent adapter. A worker must be running to execute them."
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "description": "Future instant with UTC offset, strictly before key expiry when set. No-expiry keys have no key-expiry cutoff; jobs still use finite leases and deadlines. Example dates must be replaced with your actual future schedule."
          },
          "timezone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Valid IANA timezone. Metadata only; scheduledAt is the actual execution instant."
          },
          "deadlineSeconds": {
            "type": "integer",
            "minimum": 60,
            "maximum": 3600,
            "default": 900,
            "description": "Maximum job runtime in seconds; the worker stops the child at the finite deadline."
          }
        },
        "required": [
          "deviceId",
          "name",
          "prompt",
          "scheduledAt",
          "timezone"
        ],
        "additionalProperties": false
      },
      "KeyInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "devices:read",
                "devices:control",
                "devices:media",
                "devices:advanced",
                "jobs:write",
                "worker:run"
              ]
            },
            "minItems": 1,
            "maxItems": 6,
            "description": "Permissions granted to the key. Operations can require more than one scope."
          },
          "deviceIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "minItems": 1,
            "maxItems": 100,
            "description": "Exact IDs of the devices this key may access."
          },
          "expiresInDays": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365,
            "nullable": true,
            "default": 30,
            "description": "Integer 1..365 for a finite lifetime; null for no expiry. Omission defaults to 30 days. Does not change session, job or child-token expiration."
          }
        },
        "required": [
          "name",
          "scopes",
          "deviceIds"
        ],
        "additionalProperties": false
      },
      "WorkerInput": {
        "type": "object",
        "properties": {
          "workerId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Stable identifier for this worker process. Reuse it for claim, heartbeat and completion calls."
          }
        },
        "required": [
          "workerId"
        ],
        "additionalProperties": false
      },
      "BridgeClaimInput": {
        "type": "object",
        "properties": {
          "workerId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Stable identifier for this worker process. Reuse it for claim, heartbeat and completion calls."
          },
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "backend": {
                "type": "string",
                "maxLength": 40,
                "description": "Active driver route, or the native backend reported by a registering bridge."
              },
              "tools": {
                "type": "array",
                "items": {
                  "type": "string",
                  "maxLength": 128
                },
                "maxItems": 128,
                "description": "Command names supported by this device or advertised by this bridge."
              },
              "nativeTools": {
                "type": "array",
                "items": {},
                "maxItems": 128,
                "description": "Discovered native tool descriptors. Follow each inputSchema; native coordinates may use different units."
              }
            },
            "required": [
              "backend",
              "tools"
            ],
            "additionalProperties": false,
            "description": "Currently advertised commands, native extensions and limitations."
          }
        },
        "required": [
          "workerId",
          "deviceId",
          "capabilities"
        ],
        "additionalProperties": false
      },
      "BridgeCompleteInput": {
        "type": "object",
        "properties": {
          "workerId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Stable identifier for this worker process. Reuse it for claim, heartbeat and completion calls."
          },
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "failed",
              "unknown"
            ],
            "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
          },
          "result": {
            "description": "Driver output or null. Inspect the action status first; result formats vary by driver and command."
          }
        },
        "required": [
          "workerId",
          "deviceId",
          "status"
        ],
        "additionalProperties": false
      },
      "JobCompleteInput": {
        "type": "object",
        "properties": {
          "workerId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Stable identifier for this worker process. Reuse it for claim, heartbeat and completion calls."
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "failed",
              "cancelled"
            ],
            "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
          },
          "summary": {
            "type": "string",
            "maxLength": 2000,
            "default": "",
            "description": "Worker's completion summary. It describes the process outcome, not independently verified app success."
          }
        },
        "required": [
          "workerId",
          "status"
        ],
        "additionalProperties": false
      },
      "Device": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
          },
          "name": {
            "type": "string",
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "platform": {
            "type": "string",
            "description": "Phone platform reported by the device, such as ios or android."
          },
          "model": {
            "type": "string",
            "nullable": true,
            "description": "Device model reported by the phone, or null when unavailable."
          },
          "os": {
            "type": "string",
            "nullable": true,
            "description": "Operating system version reported by the phone, or null when unavailable."
          },
          "status": {
            "type": "string",
            "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Most recent recorded device contact, or null when no contact is recorded."
          },
          "relayRegion": {
            "type": "string",
            "description": "Relay region used for the phone connection."
          },
          "agentWebrtc": {
            "type": "boolean",
            "description": "Whether the phone advertises agent WebRTC support. This does not guarantee a usable JPEG screenshot stream."
          },
          "wdaStatus": {
            "type": "string",
            "description": "Reported WebDriverAgent availability. Check current capabilities before choosing a command."
          }
        },
        "required": [
          "id",
          "name",
          "platform",
          "model",
          "os",
          "status",
          "lastSeenAt",
          "relayRegion",
          "agentWebrtc",
          "wdaStatus"
        ],
        "additionalProperties": false
      },
      "DeviceList": {
        "type": "object",
        "properties": {
          "devices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9._:-]+$",
                  "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
                },
                "name": {
                  "type": "string",
                  "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                },
                "platform": {
                  "type": "string",
                  "description": "Phone platform reported by the device, such as ios or android."
                },
                "model": {
                  "type": "string",
                  "nullable": true,
                  "description": "Device model reported by the phone, or null when unavailable."
                },
                "os": {
                  "type": "string",
                  "nullable": true,
                  "description": "Operating system version reported by the phone, or null when unavailable."
                },
                "status": {
                  "type": "string",
                  "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
                },
                "lastSeenAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "Most recent recorded device contact, or null when no contact is recorded."
                },
                "relayRegion": {
                  "type": "string",
                  "description": "Relay region used for the phone connection."
                },
                "agentWebrtc": {
                  "type": "boolean",
                  "description": "Whether the phone advertises agent WebRTC support. This does not guarantee a usable JPEG screenshot stream."
                },
                "wdaStatus": {
                  "type": "string",
                  "description": "Reported WebDriverAgent availability. Check current capabilities before choosing a command."
                }
              },
              "required": [
                "id",
                "name",
                "platform",
                "model",
                "os",
                "status",
                "lastSeenAt",
                "relayRegion",
                "agentWebrtc",
                "wdaStatus"
              ],
              "additionalProperties": false
            },
            "description": "Devices granted to the current key. An empty array is a valid result."
          }
        },
        "required": [
          "devices"
        ],
        "additionalProperties": false
      },
      "Capabilities": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "platform": {
            "type": "string",
            "description": "Phone platform reported by the device, such as ios or android."
          },
          "coordinateSpace": {
            "type": "string",
            "enum": [
              "normalized"
            ],
            "description": "Coordinate convention for common FleetDeck actions. Normalized x/y values are relative to the current screen."
          },
          "coordinates": {
            "type": "string",
            "description": "Human-readable guidance for translating screen coordinates into action coordinates."
          },
          "backend": {
            "type": "string",
            "enum": [
              "relay",
              "bridge+relay"
            ],
            "description": "Active driver route, or the native backend reported by a registering bridge."
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "tools": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Command names supported by this device or advertised by this bridge."
              },
              "nativeTools": {
                "type": "array",
                "items": {},
                "description": "Discovered upstream descriptors, normally name, description and inputSchema. Validate arguments against each tool’s inputSchema."
              },
              "nativeBackend": {
                "type": "string",
                "description": "Native bridge backend, present when a fresh bridge is registered."
              },
              "acknowledgement": {
                "type": "string",
                "description": "What driver acknowledgement guarantees. Submission alone does not verify a physical effect."
              },
              "limitations": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Platform and driver constraints to account for before executing work."
              }
            },
            "required": [
              "tools",
              "acknowledgement",
              "limitations"
            ],
            "additionalProperties": false,
            "description": "Currently advertised commands, native extensions and limitations."
          }
        },
        "required": [
          "deviceId",
          "platform",
          "coordinateSpace",
          "coordinates",
          "backend",
          "capabilities"
        ],
        "additionalProperties": false
      },
      "Session": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
          },
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC instant when this lease or credential expires. Read each renewal response for the current deadline."
          }
        },
        "required": [
          "id",
          "deviceId",
          "expiresAt"
        ],
        "additionalProperties": false
      },
      "SessionHeartbeat": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC instant when this lease or credential expires. Read each renewal response for the current deadline."
          }
        },
        "required": [
          "id",
          "expiresAt"
        ],
        "additionalProperties": false
      },
      "Released": {
        "type": "object",
        "properties": {
          "released": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "True when the release request is acknowledged. It does not reverse input already delivered."
          }
        },
        "required": [
          "released"
        ],
        "additionalProperties": false
      },
      "ActionRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
          },
          "requestId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Your stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "unknown",
              "cancelled"
            ],
            "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
          },
          "kind": {
            "type": "string",
            "enum": [
              "screenshot",
              "inspect",
              "apps",
              "tap",
              "double_tap",
              "long_press",
              "swipe",
              "text",
              "key",
              "button",
              "open_url",
              "launch_app",
              "kill_app",
              "clipboard_get",
              "set_clipboard",
              "push_media",
              "media_chunk",
              "native_tool"
            ],
            "description": "Action type that produced this record."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC instant when the record was created."
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC instant execution ended, or null while no terminal outcome is recorded."
          },
          "result": {
            "description": "Driver-defined JSON or null. Known shapes are documented in ActionResult; native tool output may differ.",
            "nullable": true,
            "x-known-shape": {
              "$ref": "#/components/schemas/ActionResult"
            }
          }
        },
        "required": [
          "id",
          "requestId",
          "status",
          "kind",
          "createdAt",
          "finishedAt",
          "result"
        ],
        "additionalProperties": false
      },
      "JobRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
          },
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "name": {
            "type": "string",
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "description": "Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule."
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone metadata. scheduledAt remains the authoritative execution instant."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled",
              "missed",
              "interrupted"
            ],
            "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC instant execution began, or null if it has not begun."
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC instant execution ended, or null while no terminal outcome is recorded."
          },
          "cancelRequested": {
            "type": "boolean",
            "description": "Whether cancellation has been requested. Physical effects already delivered are not undone."
          },
          "summary": {
            "type": "string",
            "nullable": true,
            "description": "Worker's completion summary. It describes the process outcome, not independently verified app success."
          }
        },
        "required": [
          "id",
          "deviceId",
          "name",
          "scheduledAt",
          "timezone",
          "status",
          "startedAt",
          "finishedAt",
          "cancelRequested",
          "summary"
        ],
        "additionalProperties": false
      },
      "JobList": {
        "type": "object",
        "properties": {
          "jobs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9._:-]+$",
                  "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
                },
                "deviceId": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9._:-]+$",
                  "description": "Exact device ID from List devices. The current key must grant access to this phone."
                },
                "name": {
                  "type": "string",
                  "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                },
                "scheduledAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule."
                },
                "timezone": {
                  "type": "string",
                  "description": "IANA timezone metadata. scheduledAt remains the authoritative execution instant."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "queued",
                    "running",
                    "completed",
                    "failed",
                    "cancelled",
                    "missed",
                    "interrupted"
                  ],
                  "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
                },
                "startedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "UTC instant execution began, or null if it has not begun."
                },
                "finishedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "UTC instant execution ended, or null while no terminal outcome is recorded."
                },
                "cancelRequested": {
                  "type": "boolean",
                  "description": "Whether cancellation has been requested. Physical effects already delivered are not undone."
                },
                "summary": {
                  "type": "string",
                  "nullable": true,
                  "description": "Worker's completion summary. It describes the process outcome, not independently verified app success."
                }
              },
              "required": [
                "id",
                "deviceId",
                "name",
                "scheduledAt",
                "timezone",
                "status",
                "startedAt",
                "finishedAt",
                "cancelRequested",
                "summary"
              ],
              "additionalProperties": false
            },
            "description": "Up to 100 jobs belonging to the current key."
          }
        },
        "required": [
          "jobs"
        ],
        "additionalProperties": false
      },
      "Cancelled": {
        "type": "object",
        "properties": {
          "cancelled": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "True when the cancellation request has been acknowledged."
          }
        },
        "required": [
          "cancelled"
        ],
        "additionalProperties": false
      },
      "JobClaim": {
        "type": "object",
        "properties": {
          "job": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$",
                "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
              },
              "deviceId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$",
                "description": "Exact device ID from List devices. The current key must grant access to this phone."
              },
              "prompt": {
                "type": "string",
                "description": "Task instructions passed to the external agent adapter. A worker must be running to execute them."
              },
              "deadlineSeconds": {
                "type": "integer",
                "description": "Maximum job runtime in seconds; the worker stops the child at the finite deadline."
              },
              "scheduledAt": {
                "type": "string",
                "format": "date-time",
                "description": "Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule."
              },
              "token": {
                "type": "string",
                "description": "Secret ephemeral device-bound token. Pass privately to the child agent. Never log or persist in public evidence."
              }
            },
            "required": [
              "id",
              "deviceId",
              "prompt",
              "deadlineSeconds",
              "scheduledAt",
              "token"
            ],
            "additionalProperties": false,
            "nullable": true,
            "description": "Claimed job with a private child credential, or null when no job can be claimed."
          }
        },
        "required": [
          "job"
        ],
        "additionalProperties": false
      },
      "JobHeartbeat": {
        "type": "object",
        "properties": {
          "cancel": {
            "type": "boolean",
            "description": "When true, stop the child agent and report cancellation; do not continue under an expired lease."
          }
        },
        "required": [
          "cancel"
        ],
        "additionalProperties": false
      },
      "Recorded": {
        "type": "object",
        "properties": {
          "recorded": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "True when the completion report has been recorded."
          }
        },
        "required": [
          "recorded"
        ],
        "additionalProperties": false
      },
      "BridgeClaim": {
        "type": "object",
        "properties": {
          "action": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$",
                "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
              },
              "command": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "screenshot"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "inspect"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "apps"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "tap"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                      },
                      "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                      }
                    },
                    "required": [
                      "type",
                      "x",
                      "y"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "double_tap"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                      },
                      "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                      }
                    },
                    "required": [
                      "type",
                      "x",
                      "y"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "long_press"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                      },
                      "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                      },
                      "ms": {
                        "type": "integer",
                        "minimum": 200,
                        "maximum": 1500,
                        "default": 600,
                        "description": "Gesture duration in milliseconds. The valid range depends on the action type."
                      }
                    },
                    "required": [
                      "type",
                      "x",
                      "y"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "swipe"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "from": {
                        "type": "object",
                        "properties": {
                          "x": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                          },
                          "y": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                          }
                        },
                        "required": [
                          "x",
                          "y"
                        ],
                        "additionalProperties": false,
                        "description": "Start point of the gesture, using normalized screen coordinates."
                      },
                      "to": {
                        "type": "object",
                        "properties": {
                          "x": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
                          },
                          "y": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
                          }
                        },
                        "required": [
                          "x",
                          "y"
                        ],
                        "additionalProperties": false,
                        "description": "End point of the gesture, using normalized screen coordinates."
                      },
                      "ms": {
                        "type": "integer",
                        "minimum": 100,
                        "maximum": 1200,
                        "default": 300,
                        "description": "Gesture duration in milliseconds. The valid range depends on the action type."
                      }
                    },
                    "required": [
                      "type",
                      "from",
                      "to"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "text"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "value": {
                        "type": "string",
                        "maxLength": 16000,
                        "description": "Text to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it."
                      }
                    },
                    "required": [
                      "type",
                      "value"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "key"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "key": {
                        "type": "string",
                        "enum": [
                          "return",
                          "backspace",
                          "space",
                          "tab",
                          "up",
                          "down",
                          "left",
                          "right"
                        ],
                        "description": "Keyboard key to send to the currently focused control."
                      }
                    },
                    "required": [
                      "type",
                      "key"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "button"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "name": {
                        "type": "string",
                        "enum": [
                          "home",
                          "back",
                          "app_switcher",
                          "wake",
                          "lock",
                          "volume_up",
                          "volume_down"
                        ],
                        "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                      }
                    },
                    "required": [
                      "type",
                      "name"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "open_url"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "url": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 4096,
                        "description": "Open an absolute scheme URL, maximum 4,096 characters. javascript:, data:, file: and control characters are rejected. Custom app schemes need an installed handler. Stock iPhone relay requires a native bridge for this command."
                      }
                    },
                    "required": [
                      "type",
                      "url"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "launch_app"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "bundleId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
                        "description": "Installed iOS bundle ID or Android package name."
                      }
                    },
                    "required": [
                      "type",
                      "bundleId"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "kill_app"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "bundleId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 255,
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
                        "description": "Installed iOS bundle ID or Android package name."
                      }
                    },
                    "required": [
                      "type",
                      "bundleId"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "clipboard_get"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "set_clipboard"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "value": {
                        "type": "string",
                        "maxLength": 16000,
                        "description": "Text to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it."
                      }
                    },
                    "required": [
                      "type",
                      "value"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "push_media"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "fileName": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 160,
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._ -]*$",
                        "description": "1..160 characters; starts alphanumeric, then letters, digits, dot, underscore, space or hyphen. No path separators; not . or ..."
                      },
                      "mime": {
                        "type": "string",
                        "enum": [
                          "image/jpeg",
                          "image/png",
                          "video/mp4"
                        ],
                        "description": "Media MIME type. It must match the actual source bytes."
                      },
                      "dataB64": {
                        "type": "string",
                        "minLength": 4,
                        "maxLength": 2800000,
                        "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
                        "description": "Complete padded base64 bytes without a data URL prefix. Use the complete file or the current ordered chunk."
                      }
                    },
                    "required": [
                      "type",
                      "fileName",
                      "mime",
                      "dataB64"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "media_chunk"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "uploadId": {
                        "type": "string",
                        "format": "uuid",
                        "description": "One UUID shared by all chunks of the same upload."
                      },
                      "chunkIndex": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 199,
                        "description": "Zero-based chunk index. Send in order, beginning at 0; it must be smaller than chunkCount."
                      },
                      "chunkCount": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 200,
                        "description": "Total chunks in this upload. Must not exceed totalBytes; keep it constant across chunks."
                      },
                      "totalBytes": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 104857600,
                        "description": "Decoded byte size of the complete file. A one-chunk upload must decode to exactly this length."
                      },
                      "fileName": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 160,
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._ -]*$",
                        "description": "1..160 characters; starts alphanumeric, then letters, digits, dot, underscore, space or hyphen. No path separators; not . or ..."
                      },
                      "mime": {
                        "type": "string",
                        "enum": [
                          "image/jpeg",
                          "image/png",
                          "video/mp4"
                        ],
                        "description": "Media MIME type. It must match the actual source bytes."
                      },
                      "dataB64": {
                        "type": "string",
                        "minLength": 4,
                        "maxLength": 1400000,
                        "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
                        "description": "Complete padded base64 bytes without a data URL prefix. Use the complete file or the current ordered chunk."
                      }
                    },
                    "required": [
                      "type",
                      "uploadId",
                      "chunkIndex",
                      "chunkCount",
                      "totalBytes",
                      "fileName",
                      "mime",
                      "dataB64"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "native_tool"
                        ],
                        "description": "Discriminator that selects the action or content shape."
                      },
                      "name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128,
                        "pattern": "^[A-Za-z0-9._:-]+$",
                        "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                      },
                      "arguments": {
                        "type": "object",
                        "additionalProperties": {},
                        "default": {},
                        "description": "Arguments for the discovered native tool, validated against its advertised inputSchema."
                      }
                    },
                    "required": [
                      "type",
                      "name"
                    ],
                    "additionalProperties": false
                  }
                ],
                "description": "One strict action payload, selected by its type. Unknown fields are rejected."
              },
              "deadline": {
                "type": "string",
                "format": "date-time",
                "description": "Execution deadline for this claimed bridge action. No action heartbeat is available."
              }
            },
            "required": [
              "id",
              "command",
              "deadline"
            ],
            "additionalProperties": false,
            "nullable": true,
            "description": "Claimed action, or null when no eligible action is queued."
          }
        },
        "required": [
          "action"
        ],
        "additionalProperties": false
      },
      "Key": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
          },
          "name": {
            "type": "string",
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "prefix": {
            "type": "string",
            "description": "Nonsecret token prefix for identifying a key in the dashboard."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "devices:read",
                "devices:control",
                "devices:media",
                "devices:advanced",
                "jobs:write",
                "worker:run"
              ]
            },
            "description": "Permissions granted to the key. Operations can require more than one scope."
          },
          "deviceIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "description": "Exact IDs of the devices this key may access."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Null means no expiry for this user-created key. The key remains revocable. Session and job-child expirations remain finite."
          },
          "revokedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC instant the key was revoked, or null while it has not been revoked."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC instant when the record was created."
          }
        },
        "required": [
          "id",
          "name",
          "prefix",
          "scopes",
          "deviceIds",
          "expiresAt",
          "revokedAt",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "KeyList": {
        "type": "object",
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9._:-]+$",
                  "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
                },
                "name": {
                  "type": "string",
                  "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                },
                "prefix": {
                  "type": "string",
                  "description": "Nonsecret token prefix for identifying a key in the dashboard."
                },
                "scopes": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "devices:read",
                      "devices:control",
                      "devices:media",
                      "devices:advanced",
                      "jobs:write",
                      "worker:run"
                    ]
                  },
                  "description": "Permissions granted to the key. Operations can require more than one scope."
                },
                "deviceIds": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[A-Za-z0-9._:-]+$"
                  },
                  "description": "Exact IDs of the devices this key may access."
                },
                "expiresAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "Null means no expiry for this user-created key. The key remains revocable. Session and job-child expirations remain finite."
                },
                "revokedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "UTC instant the key was revoked, or null while it has not been revoked."
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "UTC instant when the record was created."
                }
              },
              "required": [
                "id",
                "name",
                "prefix",
                "scopes",
                "deviceIds",
                "expiresAt",
                "revokedAt",
                "createdAt"
              ],
              "additionalProperties": false
            },
            "description": "User-created key metadata. Previously issued secret tokens are never returned."
          }
        },
        "required": [
          "keys"
        ],
        "additionalProperties": false
      },
      "CreatedKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
          },
          "name": {
            "type": "string",
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "prefix": {
            "type": "string",
            "description": "Nonsecret token prefix for identifying a key in the dashboard."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "devices:read",
                "devices:control",
                "devices:media",
                "devices:advanced",
                "jobs:write",
                "worker:run"
              ]
            },
            "description": "Permissions granted to the key. Operations can require more than one scope."
          },
          "deviceIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "description": "Exact IDs of the devices this key may access."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Null means no expiry for this user-created key. The key remains revocable. Session and job-child expirations remain finite."
          },
          "revokedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC instant the key was revoked, or null while it has not been revoked."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC instant when the record was created."
          },
          "token": {
            "type": "string",
            "description": "Secret shown once. Save securely; cannot be retrieved later."
          }
        },
        "required": [
          "id",
          "name",
          "prefix",
          "scopes",
          "deviceIds",
          "expiresAt",
          "revokedAt",
          "createdAt",
          "token"
        ],
        "additionalProperties": false
      },
      "KeyRemoval": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "revoked": {
                "type": "boolean",
                "enum": [
                  true
                ],
                "description": "True when the key is revoked and can no longer authenticate."
              }
            },
            "required": [
              "revoked"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "removed": {
                "type": "boolean",
                "enum": [
                  true
                ],
                "description": "True when a previously revoked key and its associated records have been permanently purged."
              }
            },
            "required": [
              "removed"
            ],
            "additionalProperties": false
          }
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable failure explanation. Use code for programmatic handling."
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error identifier. Follow its documented recovery steps before retrying."
          }
        },
        "required": [
          "error",
          "code"
        ],
        "additionalProperties": false
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "Invalid request"
            ],
            "description": "Human-readable failure explanation. Use code for programmatic handling."
          },
          "code": {
            "type": "string",
            "enum": [
              "VALIDATION"
            ],
            "description": "Machine-readable error identifier. Follow its documented recovery steps before retrying."
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "array",
                  "items": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ]
                  },
                  "description": "Path to an invalid field. Array indices are numbers; property names are strings."
                },
                "message": {
                  "type": "string",
                  "description": "Explanation of this validation failure."
                }
              },
              "required": [
                "path",
                "message"
              ],
              "additionalProperties": false
            },
            "description": "Validation failures with the location of each invalid input."
          }
        },
        "required": [
          "error",
          "code",
          "issues"
        ],
        "additionalProperties": false
      },
      "Me": {
        "type": "object",
        "properties": {
          "account": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$",
                "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
              },
              "name": {
                "type": "string",
                "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
              }
            },
            "required": [
              "id",
              "name"
            ],
            "additionalProperties": false,
            "nullable": true
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$",
                "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
              },
              "email": {
                "type": "string"
              },
              "role": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "email",
              "role"
            ],
            "additionalProperties": false
          },
          "key": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$",
                "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
              },
              "name": {
                "type": "string",
                "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
              },
              "prefix": {
                "type": "string",
                "description": "Nonsecret token prefix for identifying a key in the dashboard."
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "devices:read",
                    "devices:control",
                    "devices:media",
                    "devices:advanced",
                    "jobs:write",
                    "worker:run"
                  ]
                },
                "description": "Permissions granted to the key. Operations can require more than one scope."
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "UTC instant when this lease or credential expires. Read each renewal response for the current deadline."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "UTC instant when the record was created."
              }
            },
            "required": [
              "id",
              "name",
              "prefix",
              "scopes",
              "expiresAt",
              "createdAt"
            ],
            "additionalProperties": false,
            "description": "Keyboard key to send to the currently focused control."
          },
          "deviceIds": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "description": "Exact IDs of the devices this key may access."
          }
        },
        "required": [
          "account",
          "user",
          "key",
          "deviceIds"
        ],
        "additionalProperties": false
      },
      "SequenceList": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "deviceModelKey": {
            "type": "string",
            "nullable": true
          },
          "sequences": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
                },
                "name": {
                  "type": "string",
                  "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                },
                "steps": {
                  "type": "integer"
                },
                "repeat": {
                  "type": "integer"
                },
                "durationMs": {
                  "type": "integer"
                },
                "platform": {
                  "type": "string",
                  "nullable": true,
                  "description": "Phone platform reported by the device, such as ios or android."
                },
                "modelKey": {
                  "type": "string",
                  "nullable": true
                },
                "compatible": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "name",
                "steps",
                "repeat",
                "durationMs",
                "platform",
                "modelKey",
                "compatible"
              ],
              "additionalProperties": false
            }
          },
          "library": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9._:-]+$",
                  "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
                },
                "name": {
                  "type": "string",
                  "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                },
                "platform": {
                  "type": "string",
                  "description": "Phone platform reported by the device, such as ios or android."
                },
                "modelKey": {
                  "type": "string"
                },
                "modelLabel": {
                  "type": "string"
                },
                "compatible": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "name",
                "platform",
                "modelKey",
                "modelLabel",
                "compatible"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "deviceId",
          "deviceModelKey",
          "sequences",
          "library"
        ],
        "additionalProperties": false
      },
      "SequenceRunInput": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Your stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT."
          },
          "sequenceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "library": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "requestId",
          "sequenceId"
        ],
        "additionalProperties": false
      },
      "SequenceRun": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Your stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT."
          },
          "scheduleId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "sequenceId": {
            "type": "string"
          },
          "existing": {
            "type": "boolean",
            "description": "true when this requestId was already used and the original run is returned"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled",
              "skipped",
              "interrupted"
            ],
            "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
          },
          "queuedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "run": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$",
                "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
              },
              "scheduleId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "status": {
                "type": "string",
                "enum": [
                  "running",
                  "completed",
                  "failed",
                  "cancelled",
                  "skipped",
                  "interrupted"
                ],
                "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
              },
              "scheduledAt": {
                "type": "string",
                "format": "date-time",
                "description": "Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule."
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "UTC instant execution began, or null if it has not begun."
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "UTC instant execution ended, or null while no terminal outcome is recorded."
              },
              "error": {
                "type": "string",
                "nullable": true,
                "description": "Human-readable failure explanation. Use code for programmatic handling."
              },
              "notificationSentAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "notificationAttempts": {
                "type": "integer"
              },
              "durationMs": {
                "type": "integer",
                "nullable": true
              }
            },
            "required": [
              "id",
              "scheduleId",
              "status",
              "scheduledAt",
              "startedAt",
              "finishedAt",
              "error",
              "notificationSentAt",
              "notificationAttempts",
              "durationMs"
            ],
            "additionalProperties": false,
            "nullable": true
          }
        },
        "required": [
          "requestId",
          "scheduleId",
          "sequenceId",
          "existing",
          "status",
          "queuedAt",
          "run"
        ],
        "additionalProperties": false
      },
      "TouchScheduleInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "sequenceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "library": {
            "type": "boolean"
          },
          "cron": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "runAt": {
            "type": "string",
            "format": "date-time"
          },
          "timezone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "IANA timezone metadata. scheduledAt remains the authoritative execution instant."
          },
          "confirmed": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "failureEmail": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "nullable": true
          }
        },
        "required": [
          "name",
          "sequenceId",
          "timezone",
          "confirmed"
        ],
        "additionalProperties": false
      },
      "TouchScheduleUpdate": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "runAt": {
            "type": "string",
            "format": "date-time"
          },
          "confirmed": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "failureEmail": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "TouchScheduleRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
          },
          "name": {
            "type": "string",
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "sequenceId": {
            "type": "string"
          },
          "cron": {
            "type": "string",
            "description": "Five-field cron, or empty for a one-time run"
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone metadata. scheduledAt remains the authoritative execution instant."
          },
          "runAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "failureEmail": {
            "type": "string",
            "nullable": true
          },
          "enabled": {
            "type": "boolean"
          },
          "nextRunAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC instant when the record was created."
          },
          "warning": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "name",
          "sequenceId",
          "cron",
          "timezone",
          "runAt",
          "failureEmail",
          "enabled",
          "nextRunAt",
          "createdAt",
          "warning"
        ],
        "additionalProperties": false
      },
      "TouchScheduleList": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Exact device ID from List devices. The current key must grant access to this phone."
          },
          "schedules": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9._:-]+$",
                  "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
                },
                "name": {
                  "type": "string",
                  "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
                },
                "sequenceId": {
                  "type": "string"
                },
                "cron": {
                  "type": "string",
                  "description": "Five-field cron, or empty for a one-time run"
                },
                "timezone": {
                  "type": "string",
                  "description": "IANA timezone metadata. scheduledAt remains the authoritative execution instant."
                },
                "runAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                },
                "failureEmail": {
                  "type": "string",
                  "nullable": true
                },
                "enabled": {
                  "type": "boolean"
                },
                "nextRunAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "UTC instant when the record was created."
                }
              },
              "required": [
                "id",
                "name",
                "sequenceId",
                "cron",
                "timezone",
                "runAt",
                "failureEmail",
                "enabled",
                "nextRunAt",
                "createdAt"
              ],
              "additionalProperties": false
            }
          },
          "worker": {
            "type": "object",
            "properties": {
              "online": {
                "type": "boolean"
              },
              "lastSeenAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Most recent recorded device contact, or null when no contact is recorded."
              }
            },
            "required": [
              "online",
              "lastSeenAt"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "deviceId",
          "schedules",
          "worker"
        ],
        "additionalProperties": false
      },
      "TouchRunList": {
        "type": "object",
        "properties": {
          "runs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9._:-]+$",
                  "description": "Unique identifier of this resource. Use the returned value in subsequent requests."
                },
                "scheduleId": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[A-Za-z0-9._:-]+$"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "running",
                    "completed",
                    "failed",
                    "cancelled",
                    "skipped",
                    "interrupted"
                  ],
                  "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
                },
                "scheduledAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule."
                },
                "startedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "UTC instant execution began, or null if it has not begun."
                },
                "finishedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "UTC instant execution ended, or null while no terminal outcome is recorded."
                },
                "error": {
                  "type": "string",
                  "nullable": true,
                  "description": "Human-readable failure explanation. Use code for programmatic handling."
                },
                "notificationSentAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                },
                "notificationAttempts": {
                  "type": "integer"
                },
                "durationMs": {
                  "type": "integer",
                  "nullable": true
                }
              },
              "required": [
                "id",
                "scheduleId",
                "status",
                "scheduledAt",
                "startedAt",
                "finishedAt",
                "error",
                "notificationSentAt",
                "notificationAttempts",
                "durationMs"
              ],
              "additionalProperties": false
            }
          },
          "nextCursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "nullable": true
          }
        },
        "required": [
          "runs",
          "nextCursor"
        ],
        "additionalProperties": false
      },
      "Ok": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "ok"
        ],
        "additionalProperties": false
      },
      "ActionResult": {
        "description": "Driver-defined result or null. These fields describe known relay/ADB/WDA shapes; native MCP results can add fields. Inspect action.status first.",
        "nullable": true,
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "submitted",
              "applied",
              "staged",
              "imported"
            ],
            "description": "Current state. A completed action means the driver finished; verify the intended screen or app effect separately."
          },
          "verified": {
            "type": "boolean",
            "description": "Media import acknowledgement is not publication verification. Other input normally returns false."
          },
          "instruction": {
            "type": "string",
            "description": "Driver guidance for the next observation or recovery step."
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "type",
                "mimeType",
                "data"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "image"
                  ],
                  "description": "Discriminator that selects the action or content shape."
                },
                "mimeType": {
                  "type": "string",
                  "enum": [
                    "image/jpeg",
                    "image/png"
                  ],
                  "description": "MIME type of the returned image."
                },
                "data": {
                  "type": "string",
                  "description": "Base64 image bytes, without a data URL prefix."
                }
              }
            },
            "description": "Content blocks returned by the driver. Screenshot image blocks contain base64 image bytes."
          },
          "width": {
            "type": "integer",
            "description": "Captured image width in pixels."
          },
          "height": {
            "type": "integer",
            "description": "Captured image height in pixels."
          },
          "capturedAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC capture timestamp supplied by the relay."
          },
          "coordinateSpace": {
            "type": "string",
            "description": "Coordinate convention for common FleetDeck actions. Normalized x/y values are relative to the current screen."
          },
          "xml": {
            "type": "string",
            "description": "ADB UI hierarchy XML; bounds use screen pixels."
          },
          "tree": {
            "description": "WDA accessibility tree; shape varies by version."
          },
          "screen": {
            "type": "object",
            "description": "ADB {w,h} pixels; WDA {width,height} logical points.",
            "additionalProperties": {
              "type": "number"
            }
          },
          "packages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Android package-name strings returned by ADB app inventory."
          },
          "apps": {
            "type": "array",
            "items": {
              "description": "Phone-agent defined app entry."
            },
            "description": "Phone-agent-defined app entries. Entry fields depend on the agent version."
          },
          "value": {
            "type": "string",
            "description": "Plaintext clipboard value."
          },
          "code": {
            "type": "string",
            "description": "Execution error code, distinct from an HTTP error."
          },
          "error": {
            "type": "string",
            "description": "Human-readable failure explanation. Use code for programmatic handling."
          }
        }
      },
      "Command_screenshot": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "screenshot"
            ],
            "description": "Discriminator that selects the action or content shape."
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "Capture an image. Result.content contains image data in base64 and mimeType (image/jpeg on relay, image/png on ADB/WDA). Relay also returns width, height and capturedAt. Relay requires an active JPEG-capable stream; a black image is not proof that capture works.",
        "example": {
          "type": "screenshot"
        }
      },
      "Command_inspect": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "inspect"
            ],
            "description": "Discriminator that selects the action or content shape."
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "Read UI hierarchy through a native bridge. ADB returns xml and screen {w,h}; WDA returns tree and screen {width,height}. Their hierarchy coordinates are pixels or logical points, not normalized action coordinates. Accessibility coverage varies by app.",
        "example": {
          "type": "inspect"
        }
      },
      "Command_apps": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "apps"
            ],
            "description": "Discriminator that selects the action or content shape."
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "List installed apps. Relay returns apps (phone-agent defined entries); ADB returns packages (package-name strings). The built-in WDA bridge does not provide app inventory. Older agents may return UNSUPPORTED.",
        "example": {
          "type": "apps"
        }
      },
      "Command_tap": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "tap"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "x": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
          },
          "y": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
          }
        },
        "required": [
          "type",
          "x",
          "y"
        ],
        "additionalProperties": false,
        "description": "Tap the current screen at normalized x/y, inclusive 0..1. Capture again after navigation or rotation.",
        "example": {
          "type": "tap",
          "x": 0.5,
          "y": 0.6
        }
      },
      "Command_double_tap": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "double_tap"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "x": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
          },
          "y": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
          }
        },
        "required": [
          "type",
          "x",
          "y"
        ],
        "additionalProperties": false,
        "description": "Double tap at normalized x/y. Timing and recognition depend on the driver and app.",
        "example": {
          "type": "double_tap",
          "x": 0.5,
          "y": 0.6
        }
      },
      "Command_long_press": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "long_press"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "x": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
          },
          "y": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
          },
          "ms": {
            "type": "integer",
            "minimum": 200,
            "maximum": 1500,
            "default": 600,
            "description": "Gesture duration in milliseconds. The valid range depends on the action type."
          }
        },
        "required": [
          "type",
          "x",
          "y"
        ],
        "additionalProperties": false,
        "description": "Hold a normalized point. ms is an integer from 200 to 1500; default 600.",
        "example": {
          "type": "long_press",
          "x": 0.5,
          "y": 0.6,
          "ms": 600
        }
      },
      "Command_swipe": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "swipe"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "from": {
            "type": "object",
            "properties": {
              "x": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
              },
              "y": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
              }
            },
            "required": [
              "x",
              "y"
            ],
            "additionalProperties": false,
            "description": "Start point of the gesture, using normalized screen coordinates."
          },
          "to": {
            "type": "object",
            "properties": {
              "x": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Horizontal position: 0 is the left edge and 1 is the right edge of the current screen."
              },
              "y": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "description": "Vertical position: 0 is the top edge and 1 is the bottom edge of the current screen."
              }
            },
            "required": [
              "x",
              "y"
            ],
            "additionalProperties": false,
            "description": "End point of the gesture, using normalized screen coordinates."
          },
          "ms": {
            "type": "integer",
            "minimum": 100,
            "maximum": 1200,
            "default": 300,
            "description": "Gesture duration in milliseconds. The valid range depends on the action type."
          }
        },
        "required": [
          "type",
          "from",
          "to"
        ],
        "additionalProperties": false,
        "description": "Swipe between normalized points. ms is an integer from 100 to 1200; default 300.",
        "example": {
          "type": "swipe",
          "from": {
            "x": 0.5,
            "y": 0.8
          },
          "to": {
            "x": 0.5,
            "y": 0.2
          },
          "ms": 300
        }
      },
      "Command_text": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "value": {
            "type": "string",
            "maxLength": 16000,
            "description": "Text to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it."
          }
        },
        "required": [
          "type",
          "value"
        ],
        "additionalProperties": false,
        "description": "Type into the focused control. value allows up to 16,000 characters, including empty text. ADB input supports ASCII only and rejects literal %s; use a compatible relay/IME or native tool for other text.",
        "example": {
          "type": "text",
          "value": "Hello from FleetDeck"
        }
      },
      "Command_key": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "key"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "key": {
            "type": "string",
            "enum": [
              "return",
              "backspace",
              "space",
              "tab",
              "up",
              "down",
              "left",
              "right"
            ],
            "description": "Keyboard key to send to the currently focused control."
          }
        },
        "required": [
          "type",
          "key"
        ],
        "additionalProperties": false,
        "description": "Send one key: return, backspace, space, tab, up, down, left or right. Focus and OS behavior determine its effect.",
        "example": {
          "type": "key",
          "key": "return"
        }
      },
      "Command_button": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "button"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "name": {
            "type": "string",
            "enum": [
              "home",
              "back",
              "app_switcher",
              "wake",
              "lock",
              "volume_up",
              "volume_down"
            ],
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          }
        },
        "required": [
          "type",
          "name"
        ],
        "additionalProperties": false,
        "description": "System button: home, back, app_switcher, wake, lock, volume_up or volume_down. iOS has no system Back; built-in WDA also does not support app_switcher. Wake does not bypass the lockscreen.",
        "example": {
          "type": "button",
          "name": "home"
        }
      },
      "Command_open_url": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "open_url"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "url": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "description": "Absolute URL or installed app scheme. javascript:, data:, file: and control characters are rejected."
          }
        },
        "required": [
          "type",
          "url"
        ],
        "additionalProperties": false,
        "description": "Open an absolute scheme URL, maximum 4,096 characters. javascript:, data:, file: and control characters are rejected. Custom app schemes need an installed handler. Stock iPhone relay requires a native bridge for this command.",
        "example": {
          "type": "open_url",
          "url": "https://example.com"
        }
      },
      "Command_launch_app": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "launch_app"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "bundleId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
            "description": "Installed iOS bundle ID or Android package name."
          }
        },
        "required": [
          "type",
          "bundleId"
        ],
        "additionalProperties": false,
        "description": "Launch an installed iOS bundle ID or Android package. Identifier length 1..255, starts alphanumeric and then uses letters, digits, dot, underscore or hyphen. Verify the foreground app afterward; relay submission is not proof of launch.",
        "example": {
          "type": "launch_app",
          "bundleId": "com.example.app"
        }
      },
      "Command_kill_app": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "kill_app"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "bundleId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
            "description": "Installed iOS bundle ID or Android package name."
          }
        },
        "required": [
          "type",
          "bundleId"
        ],
        "additionalProperties": false,
        "description": "Terminate the identified app (Android force-stop). Same identifier rules as launch_app. Unsaved app work may be lost.",
        "example": {
          "type": "kill_app",
          "bundleId": "com.example.app"
        }
      },
      "Command_clipboard_get": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "clipboard_get"
            ],
            "description": "Discriminator that selects the action or content shape."
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "Read plaintext pasteboard using a supported native bridge; built-in WDA returns {value:string}. Clipboard contents can be sensitive. Relay and built-in ADB do not implement this command.",
        "example": {
          "type": "clipboard_get"
        }
      },
      "Command_set_clipboard": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "set_clipboard"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "value": {
            "type": "string",
            "maxLength": 16000,
            "description": "Text to type or write; for a clipboard read, the returned plaintext value. Writing the clipboard does not paste it."
          }
        },
        "required": [
          "type",
          "value"
        ],
        "additionalProperties": false,
        "description": "Write up to 16,000 characters to a supported pasteboard. This does not itself paste into the focused field. Built-in ADB does not implement this command.",
        "example": {
          "type": "set_clipboard",
          "value": "Text to paste"
        }
      },
      "Command_push_media": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "push_media"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "fileName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._ -]*$",
            "description": "Destination filename with a matching media extension. Path separators are not allowed."
          },
          "mime": {
            "type": "string",
            "enum": [
              "image/jpeg",
              "image/png",
              "video/mp4"
            ],
            "description": "Media MIME type. It must match the actual source bytes."
          },
          "dataB64": {
            "type": "string",
            "minLength": 4,
            "maxLength": 2800000,
            "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
            "description": "Complete padded base64 bytes without a data URL prefix. Use the complete file or the current ordered chunk."
          }
        },
        "required": [
          "type",
          "fileName",
          "mime",
          "dataB64"
        ],
        "additionalProperties": false,
        "description": "Import a small file. dataB64 is complete padded base64 (no data URL), at most 2,800,000 characters; malformed or unpadded input returns VALIDATION. MIME is image/jpeg, image/png or video/mp4. Example bytes are a PNG header only: replace with the complete file. Requires an acknowledged-import phone agent and gallery permission; result.status imported acknowledges import, not publication.",
        "example": {
          "type": "push_media",
          "fileName": "image.png",
          "mime": "image/png",
          "dataB64": "iVBORw0KGgo="
        }
      },
      "Command_media_chunk": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "media_chunk"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "uploadId": {
            "type": "string",
            "format": "uuid",
            "description": "One UUID shared by all chunks of the same upload."
          },
          "chunkIndex": {
            "type": "integer",
            "minimum": 0,
            "maximum": 199,
            "description": "Zero-based chunk index. Send in order, beginning at 0; it must be smaller than chunkCount."
          },
          "chunkCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "Total chunks in this upload. Must not exceed totalBytes; keep it constant across chunks."
          },
          "totalBytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 104857600,
            "description": "Decoded byte size of the complete file. A one-chunk upload must decode to exactly this length."
          },
          "fileName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._ -]*$",
            "description": "Destination filename with a matching media extension. Path separators are not allowed."
          },
          "mime": {
            "type": "string",
            "enum": [
              "image/jpeg",
              "image/png",
              "video/mp4"
            ],
            "description": "Media MIME type. It must match the actual source bytes."
          },
          "dataB64": {
            "type": "string",
            "minLength": 4,
            "maxLength": 1400000,
            "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
            "description": "Complete padded base64 bytes without a data URL prefix. Use the complete file or the current ordered chunk."
          }
        },
        "required": [
          "type",
          "uploadId",
          "chunkIndex",
          "chunkCount",
          "totalBytes",
          "fileName",
          "mime",
          "dataB64"
        ],
        "additionalProperties": false,
        "description": "Send ordered chunks for one upload UUID, starting at index 0. chunkIndex 0..199 and must be below chunkCount; chunkCount 1..200 and cannot exceed totalBytes; totalBytes 1..104,857,600 (100 MiB); each complete padded base64 string is at most 1,400,000 characters and its decoded bytes cannot exceed totalBytes. A single chunk must decode to exactly totalBytes. These cross-field checks return VALIDATION and are not fully represented by OpenAPI. Keep metadata consistent and use a separate requestId for each chunk. Use complete real file bytes: this example is only a PNG header. Intermediate acknowledgements are staged; final success is imported. The CLI uses 1 MiB byte chunks and renews the session.",
        "example": {
          "type": "media_chunk",
          "uploadId": "d7be57c2-1912-433f-a540-4606b073e81c",
          "chunkIndex": 0,
          "chunkCount": 1,
          "totalBytes": 8,
          "fileName": "image.png",
          "mime": "image/png",
          "dataB64": "iVBORw0KGgo="
        }
      },
      "Command_native_tool": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "native_tool"
            ],
            "description": "Discriminator that selects the action or content shape."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Name of the resource or operation. For commands with an enum, choose one of the listed values."
          },
          "arguments": {
            "type": "object",
            "additionalProperties": {},
            "default": {},
            "description": "Arguments for the discovered native tool, validated against its advertised inputSchema."
          }
        },
        "required": [
          "type",
          "name"
        ],
        "additionalProperties": false,
        "description": "Call a tool actually listed in capabilities.nativeTools. name follows the shared ID rules; arguments defaults to {}. This example applies only when get_screen_info is discovered. Follow that tool’s inputSchema and coordinate units; common normalized coordinates do not apply automatically. Native availability depends on the bridge preset, upstream version, device and permissions.",
        "example": {
          "type": "native_tool",
          "name": "get_screen_info",
          "arguments": {}
        }
      }
    }
  }
}
