{ "openapi": "3.1.0", "info": { "title": "Glasshand agent API", "version": "0.1.0", "description": "Dedicated monthly physical iPhone and Mac rentals. Open registration; check catalog billingMode before checkout. Device authorization setup is a Glasshand convenience endpoint; token exchange uses OAuth device and refresh grants." }, "servers": [ { "url": "https://api.glasshand.com/v1" } ], "security": [ { "bearerAuth": [] } ], "externalDocs": { "description": "Agent setup, retry semantics and device control guide", "url": "https://glasshand.com/agents.md" }, "paths": { "/auth/device/code": { "post": { "operationId": "startDeviceAuthorization", "summary": "Create an agent authorization request", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string", "format": "uri" }, "verification_uri_complete": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer" }, "interval": { "type": "integer" } }, "required": [ "client_id", "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "description": "Show verification_uri_complete to the human. Keep device_code private. Poll no faster than interval. Creates a public OAuth client for this named agent automatically.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientName": { "type": "string", "maxLength": 80 } }, "required": [ "clientName" ] } } } } } }, "/auth/device/token": { "post": { "operationId": "exchangeDeviceToken", "summary": "Exchange device code or rotate refresh token", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "refresh_token", "scope" ] } } } }, "400": { "description": "OAuth polling or token error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "description": "Use device_code for the device grant, refresh_token for refresh. OAuth errors are {error:string,error_description?:string}; handle authorization_pending, slow_down, access_denied, expired_token, invalid_client and invalid_grant. Atomically replace rotated credentials.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:device_code", "refresh_token" ] }, "device_code": { "type": "string" }, "refresh_token": { "type": "string" } }, "required": [ "client_id", "grant_type" ] } } } } } }, "/me": { "get": { "operationId": "getIdentity", "summary": "Read the authenticated account", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" } }, "required": [ "id", "email" ] }, "billingMode": { "enum": [ "test", "live" ] }, "launchOpen": { "type": "boolean" } }, "required": [ "user", "billingMode", "launchOpen" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/catalog": { "get": { "operationId": "getCatalog", "summary": "List device models and monthly prices", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "iphone", "mac" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "monthlyPrice": { "type": "number" }, "currency": { "const": "USD" }, "specs": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "name", "description", "monthlyPrice", "currency", "specs" ] } }, "billingMode": { "enum": [ "test", "live" ] }, "launchOpen": { "type": "boolean" } }, "required": [ "items", "billingMode", "launchOpen" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "description": "A model catalog is not an inventory guarantee. monthlyPrice is USD base-price dollars before applicable tax." } }, "/rentals": { "get": { "operationId": "listRentals", "summary": "List owned rentals and explicitly authorized shared rentals", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Rental" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires rentals:read. Team rentals appear only with current team membership and an explicit team grant on this agent. Joining a team does not broaden existing agents. isOwner and permissions distinguish rental purchasers from shared users; billing/cancellation remain purchaser-only." } }, "/rentals/{id}": { "get": { "operationId": "getRental", "summary": "Read an owned or explicitly authorized shared rental", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rental" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/rentals/checkout": { "post": { "operationId": "createCheckout", "summary": "Prepare a monthly Stripe subscription checkout", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rentalId": { "type": "string", "format": "uuid" }, "checkoutUrl": { "type": "string", "format": "uri" } }, "required": [ "rentalId", "checkoutUrl" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Persist one unique key per logical operation; retry the exact body with the same key after timeouts/503. Never reuse for a different operation." } ], "description": "Send checkoutUrl to the human. Stripe Checkout calculates applicable tax above the monthly base price. On confirmed stockout, refund/cancel and availability notifications are automatic unless waitlistOnFailure is false. No device is ready until the verified payment workflow provisions it. Poll getRental. Never infer payment from redirect alone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "iphone", "mac" ] }, "waitlistOnFailure": { "type": "boolean", "default": true, "description": "Automatically join availability notifications on confirmed stockout; explicit false opts out." } }, "required": [ "kind" ] } } } } } }, "/rentals/{id}/cancel": { "post": { "operationId": "cancelRental", "summary": "Schedule cancellation at the paid period end", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rental" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Persist one unique key per logical operation; retry the exact body with the same key after timeouts/503. Never reuse for a different operation." } ], "description": "Rental purchaser only. Team membership does not permit cancellation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelAtPeriodEnd": { "const": true } }, "required": [ "cancelAtPeriodEnd" ] } } } } } }, "/rentals/{id}/resume": { "post": { "operationId": "resumeRental", "summary": "Remove a pending period-end cancellation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rental" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Persist one unique key per logical operation; retry the exact body with the same key after timeouts/503. Never reuse for a different operation." } ], "description": "Rental purchaser only. Team membership does not permit billing changes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } } } }, "/billing/portal": { "post": { "operationId": "openBillingPortal", "summary": "Create a private hosted Stripe billing link", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires billing:write. Present the link to the human; do not log or publish it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } } } }, "/waitlist": { "get": { "operationId": "getWaitlist", "summary": "List notification interests", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "iphone", "mac" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "createdAt" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "joinWaitlist", "summary": "Join a device notification list", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "joined": { "const": true } }, "required": [ "joined" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "iphone", "mac" ] } }, "required": [ "kind" ] } } } } } }, "/waitlist/{kind}": { "delete": { "operationId": "leaveWaitlist", "summary": "Leave a notification list", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "joined": { "const": false } }, "required": [ "joined" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "iphone", "mac" ] } } ] } }, "/rentals/{id}/connection": { "get": { "operationId": "getConnection", "summary": "Get device geometry and authenticated connection URLs", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rentalId": { "type": "string", "format": "uuid" }, "geometry": { "$ref": "#/components/schemas/Geometry" }, "capture": { "type": "object" }, "control": { "type": [ "object", "null" ] }, "screenshotUrl": { "type": "string", "format": "uri" }, "controlUrl": { "type": "string", "format": "uri" } }, "required": [ "rentalId", "geometry", "capture", "control", "screenshotUrl", "controlUrl" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Requires devices:control and an active/grace deviceReady rental. Never put a bearer token in a URL. The WebSocket protocol is in the agent instructions." } }, "/rentals/{id}/mac-login": { "get": { "operationId": "getMacLogin", "summary": "Get the login supplied with an accessible Mac", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "username", "password" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Sensitive, on-demand response with Cache-Control: no-store. Requires devices:control, ownership or current membership in its sharing team with an explicit team grant for this agent, a ready Mac, and active or unexpired grace access. Session/grant and rental access are checked again after retrieval. Returns the provider-supplied macOS login, which does not track password changes made inside the Mac. Use it only for the user-authorized task; never print it in chat, logs, screenshots of tooling, or URLs. Do not poll or persist this response. Missing/unsupported provider credentials return 503 mac_login_unavailable; retry deliberately or contact support. Non-Mac, unready, ended, expired or unauthorized rentals return 404 device_unavailable. This endpoint does not change the password, control the device, or expose controller/workspace credentials." } }, "/rentals/{id}/screenshot": { "get": { "operationId": "getScreenshot", "summary": "Read a fresh full-HDMI JPEG", "responses": { "200": { "description": "Success", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Crop geometry.viewport for the visible iPhone. Returns 503 if capture is stale. Requires devices:control." } }, "/rentals/{id}/input": { "post": { "operationId": "sendInput", "summary": "Send one device input as the authenticated agent", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "v": { "const": 1 }, "type": { "const": "result" }, "requestId": { "type": "string" }, "ok": { "type": "boolean" }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "v", "type", "requestId", "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Persist one unique key per logical operation; retry the exact body with the same key after timeouts/503. Never reuse for a different operation." } ], "description": "Requires devices:control. Input deduplication is bounded to the current controller process. Do not blindly retry uncertain physical input; inspect the screen. Pause on control_taken while a human has control.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Input" } } } } } }, "/teams": { "get": { "operationId": "listTeams", "summary": "List teams explicitly authorized for this agent", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires rentals:read. Only current memberships explicitly selected by the human on this agent grant are returned. Team creation, membership, invitations, rental sharing and grant changes are managed in the Glasshand browser app." } }, "/teams/{id}": { "get": { "operationId": "getTeam", "summary": "Read an explicitly authorized team and its shared devices", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" }, "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "role": { "enum": [ "owner", "admin", "member" ] }, "joinedAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "name", "role", "joinedAt" ] } }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/Rental" } }, "invitations": { "type": "array", "maxItems": 0 } }, "required": [ "team", "members", "devices", "invitations" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Requires current membership, explicit agent team permission and rentals:read. Pending invitations are not returned to agents. A shared physical device has one state and one active controller." } }, "/rentals/{id}/control/release": { "post": { "operationId": "releaseDeviceControl", "summary": "Release this agent HTTP control session", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry safely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Requires devices:control and current device access. Releases this agent HTTP input lease only; it cannot release another user or agent lease. WebSocket agents use their existing release/disconnect command. Cooperate with other members: release when finished; inspect the screen after handoff.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Rental": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "iphone", "mac" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_payment", "provisioning", "active", "grace", "ending", "refunding", "failed", "ended" ] }, "createdAt": { "type": "string", "format": "date-time" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "graceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "monthlyPrice": { "type": "number", "description": "USD base price before applicable tax, not cents" }, "deviceReady": { "type": "boolean" }, "billingManaged": { "type": "boolean" }, "failureMessage": { "type": [ "string", "null" ] }, "isOwner": { "type": "boolean" }, "team": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "owner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name" ] }, "permissions": { "type": "object", "properties": { "canManageBilling": { "type": "boolean" }, "canShare": { "type": "boolean" } }, "required": [ "canManageBilling", "canShare" ] } }, "required": [ "id", "kind", "name", "status", "deviceReady", "monthlyPrice", "billingManaged" ] }, "Input": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "click" }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "button": { "enum": [ 1, 2, 4 ] }, "count": { "enum": [ 1, 2 ] } }, "required": [ "type", "x", "y" ] }, { "type": "object", "properties": { "type": { "const": "drag" }, "fromX": { "type": "number", "minimum": 0, "maximum": 1 }, "fromY": { "type": "number", "minimum": 0, "maximum": 1 }, "toX": { "type": "number", "minimum": 0, "maximum": 1 }, "toY": { "type": "number", "minimum": 0, "maximum": 1 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 3000 } }, "required": [ "type", "fromX", "fromY", "toX", "toY" ] }, { "type": "object", "properties": { "type": { "const": "scroll" }, "delta": { "type": "integer", "minimum": -127, "maximum": 127 }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "type", "delta" ] }, { "type": "object", "properties": { "type": { "const": "text" }, "text": { "type": "string", "maxLength": 512, "description": "US printable ASCII plus newline/tab only" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "const": "pointer" }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "buttons": { "type": "integer", "minimum": 0, "maximum": 31 } }, "required": [ "type", "x", "y", "buttons" ] }, { "type": "object", "properties": { "type": { "const": "key" }, "keys": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 231 }, "maxItems": 6 }, "modifiers": { "type": "integer", "minimum": 0, "maximum": 255 } }, "required": [ "type", "keys" ] }, { "type": "object", "properties": { "type": { "const": "press" }, "keys": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 231 }, "maxItems": 6, "minItems": 1 }, "modifiers": { "type": "integer", "minimum": 0, "maximum": 255 } }, "required": [ "type", "keys" ] }, { "type": "object", "properties": { "type": { "const": "home" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "const": "release_all" } }, "required": [ "type" ] } ] }, "Geometry": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" }, "viewport": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ] } }, "required": [ "width", "height", "viewport" ] }, "Team": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "admin", "member" ] }, "memberCount": { "type": "integer" }, "deviceCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "role", "memberCount", "deviceCount", "createdAt" ] } } } }