@usestatemachines/sdk 0.11.0 → 0.12.1

package/openapi.json

@@ -70,27 +70,18 @@
             "$ref": "#/components/schemas/AbsentReason"
           },
           "source": {
-            "$ref": "#/components/schemas/AbsentRecordSource"
-          }
-        },
-        "required": ["object", "source", "nativeId", "reason"],
-        "type": "object"
-      },
-      "AbsentRecordSource": {
-        "description": "The file of the record in the import, such as `salesforce/records/Opportunity.jsonl`, and its line, counted from 1.",
-        "properties": {
-          "file": {
-            "type": "string"
+            "$ref": "#/components/schemas/RecordSource"
           },
-          "line": {
-            "exclusiveMinimum": 0,
-            "type": ["integer", "null"]
+          "text": {
+            "description": "The text that the record wrote as its ID, such as `acme`, when the text is no vendor ID.",
+            "type": "string"
           }
         },
-        "required": ["file", "line"],
+        "required": ["object", "source", "nativeId", "reason"],
         "type": "object"
       },
       "Actor": {
+        "description": "A user of the app's seed, for display.",
         "properties": {
           "id": {
             "maxLength": 255,
@@ -158,6 +149,31 @@
           }
         ]
       },
+      "AppUser": {
+        "description": "A user of an app who can sign in, as the app answers it.",
+        "properties": {
+          "default": {
+            "type": "boolean"
+          },
+          "email": {
+            "type": ["string", "null"]
+          },
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "role": {
+            "type": ["string", "null"]
+          },
+          "username": {
+            "type": ["string", "null"]
+          }
+        },
+        "required": ["id", "name", "email", "username", "role", "default"],
+        "type": "object"
+      },
       "AuditEvent": {
         "properties": {
           "data": {
@@ -525,6 +541,9 @@
       },
       "Credentials": {
         "properties": {
+          "actor": {
+            "$ref": "#/components/schemas/AppUser"
+          },
           "actorId": {
             "type": "string"
           },
@@ -584,7 +603,7 @@
                         "type": "string"
                       },
                       "url": {
-                        "description": "The MCP server's URL. On an environment created with `tokenInUrl`, a request with no `Authorization` header acts as the actor that this call picks when you send no `actorId`. To act as `actorId`, send the service's headers.",
+                        "description": "The MCP server's URL. On an environment created with `tokenInUrl`, a request with no `Authorization` header acts as the app's default user. To act as the user of these credentials, send the service's headers.",
                         "type": "string"
                       }
                     },
@@ -803,8 +822,10 @@
                   "workspace_archived",
                   "version_in_use",
                   "ui_disabled",
+                  "actor_cannot_sign_in",
                   "body_too_large",
                   "version_unavailable",
+                  "actor_not_found",
                   "environment_limit_reached",
                   "rate_limited",
                   "internal_error",
@@ -824,6 +845,13 @@
               "message": {
                 "type": "string"
               },
+              "nearest": {
+                "description": "On `actor_not_found`, the users who can act in the app that are nearest to `as`, nearest first.",
+                "items": {
+                  "$ref": "#/components/schemas/AppUser"
+                },
+                "type": "array"
+              },
               "requestId": {
                 "type": "string"
               },
@@ -838,6 +866,22 @@
         "required": ["error"],
         "type": "object"
       },
+      "FilledField": {
+        "properties": {
+          "field": {
+            "type": "string"
+          },
+          "object": {
+            "type": "string"
+          },
+          "records": {
+            "description": "How many loaded records of the object the app filled the field for.",
+            "type": "integer"
+          }
+        },
+        "required": ["object", "field", "records"],
+        "type": "object"
+      },
       "Import": {
         "properties": {
           "apps": {
@@ -918,6 +962,207 @@
         ],
         "type": "object"
       },
+      "ImportActor": {
+        "properties": {
+          "id": {
+            "description": "The ID of the user in the app's database.",
+            "type": "string"
+          },
+          "user": {
+            "description": "The entry of `actors` in the manifest: an email, a username or an ID.",
+            "type": "string"
+          }
+        },
+        "required": ["user", "id"],
+        "type": "object"
+      },
+      "ImportFile": {
+        "oneOf": [
+          {
+            "properties": {
+              "kind": {
+                "enum": ["unavailable"],
+                "type": "string"
+              },
+              "reason": {
+                "enum": [
+                  "uploading",
+                  "invalid",
+                  "deleted",
+                  "missing",
+                  "unreadable",
+                  "too_large"
+                ],
+                "type": "string"
+              }
+            },
+            "required": ["kind", "reason"],
+            "type": "object"
+          },
+          {
+            "properties": {
+              "kind": {
+                "enum": ["binary"],
+                "type": "string"
+              },
+              "path": {
+                "type": "string"
+              },
+              "sizeBytes": {
+                "minimum": 0,
+                "type": "integer"
+              }
+            },
+            "required": ["kind", "path", "sizeBytes"],
+            "type": "object"
+          },
+          {
+            "properties": {
+              "kind": {
+                "enum": ["text"],
+                "type": "string"
+              },
+              "path": {
+                "type": "string"
+              },
+              "sizeBytes": {
+                "minimum": 0,
+                "type": "integer"
+              },
+              "tables": {
+                "items": {
+                  "properties": {
+                    "columns": {
+                      "items": {
+                        "type": "string"
+                      },
+                      "type": "array"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "rows": {
+                      "items": {
+                        "items": {
+                          "type": "string"
+                        },
+                        "type": "array"
+                      },
+                      "type": "array"
+                    },
+                    "truncated": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": ["name", "columns", "rows", "truncated"],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "tablesTruncated": {
+                "type": "boolean"
+              },
+              "text": {
+                "type": "string"
+              },
+              "truncated": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "kind",
+              "path",
+              "sizeBytes",
+              "text",
+              "truncated",
+              "tablesTruncated",
+              "tables"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "ImportFolder": {
+        "oneOf": [
+          {
+            "properties": {
+              "kind": {
+                "enum": ["unavailable"],
+                "type": "string"
+              },
+              "reason": {
+                "enum": [
+                  "uploading",
+                  "invalid",
+                  "deleted",
+                  "missing",
+                  "unreadable",
+                  "too_large"
+                ],
+                "type": "string"
+              }
+            },
+            "required": ["kind", "reason"],
+            "type": "object"
+          },
+          {
+            "properties": {
+              "entries": {
+                "items": {
+                  "oneOf": [
+                    {
+                      "properties": {
+                        "kind": {
+                          "enum": ["folder"],
+                          "type": "string"
+                        },
+                        "path": {
+                          "type": "string"
+                        }
+                      },
+                      "required": ["kind", "path"],
+                      "type": "object"
+                    },
+                    {
+                      "properties": {
+                        "kind": {
+                          "enum": ["file"],
+                          "type": "string"
+                        },
+                        "path": {
+                          "type": "string"
+                        },
+                        "sizeBytes": {
+                          "minimum": 0,
+                          "type": "integer"
+                        }
+                      },
+                      "required": ["kind", "path", "sizeBytes"],
+                      "type": "object"
+                    }
+                  ]
+                },
+                "type": "array"
+              },
+              "kind": {
+                "enum": ["folder"],
+                "type": "string"
+              },
+              "name": {
+                "type": ["string", "null"]
+              },
+              "nextCursor": {
+                "type": ["string", "null"]
+              },
+              "path": {
+                "type": "string"
+              }
+            },
+            "required": ["kind", "path", "name", "entries", "nextCursor"],
+            "type": "object"
+          }
+        ]
+      },
       "ImportProblem": {
         "properties": {
           "code": {
@@ -936,11 +1181,11 @@
             "type": "string"
           },
           "pointer": {
-            "description": "The JSON pointer of the value, such as `/apps/0/name`. In a records file, it points into the record on `line`. Null when the problem names no value.",
+            "description": "The JSON pointer of the value, such as `/apps/salesforce/appId`. In a records file, it points into the record on `line`. Null when the problem names no value.",
             "type": ["string", "null"]
           },
           "severity": {
-            "description": "An error refuses the import: the check of the zip file makes the import `invalid`, and the load of a snapshot from the import fails the snapshot. A warning refuses nothing.",
+            "description": "An error refuses the import, and the check makes the import `invalid`. In `skipRecord` mode, an error in the values, the ID, or the references of a record leaves out only that record. A warning refuses nothing.",
             "enum": ["error", "warning"],
             "type": "string"
           }
@@ -952,12 +1197,39 @@
         "enum": ["uploading", "ready", "invalid", "deleted"],
         "type": "string"
       },
+      "KnownDifference": {
+        "properties": {
+          "field": {
+            "description": "The field, or null for the whole object.",
+            "type": ["string", "null"]
+          },
+          "message": {
+            "type": "string"
+          },
+          "object": {
+            "description": "The object, or null for the whole app.",
+            "type": ["string", "null"]
+          },
+          "values": {
+            "description": "How many values of the import the difference affects, or null when the load did not count them.",
+            "type": ["number", "null"]
+          }
+        },
+        "required": ["object", "field", "message", "values"],
+        "type": "object"
+      },
       "LaunchUiSession": {
         "additionalProperties": false,
         "properties": {
           "actorId": {
-            "maxLength": 255,
-            "minLength": 1,
+            "deprecated": true,
+            "description": "The old name of `as`. It takes the same values.",
+            "maxLength": 320,
+            "type": "string"
+          },
+          "as": {
+            "description": "The user to act as: an email, a username or an ID of a user of the app. Without it, the call acts as the app's default user.",
+            "maxLength": 320,
             "type": "string"
           },
           "entryPath": {
@@ -978,13 +1250,47 @@
             "type": "string"
           }
         },
-        "required": [
-          "serviceId",
-          "actorId",
-          "mode",
-          "launcherOrigin",
-          "entryPath"
-        ],
+        "required": ["serviceId", "mode", "launcherOrigin", "entryPath"],
+        "type": "object"
+      },
+      "MadeId": {
+        "properties": {
+          "id": {
+            "description": "The ID that the app made.",
+            "type": "string"
+          },
+          "object": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/RecordSource"
+          },
+          "text": {
+            "description": "The text that the record wrote as its ID, such as `acme`, or null for a record that wrote no ID, whose ID the app made from its place.",
+            "type": ["string", "null"]
+          }
+        },
+        "required": ["object", "source", "text", "id"],
+        "type": "object"
+      },
+      "MatchedRecord": {
+        "properties": {
+          "id": {
+            "description": "The ID of the seed record that the record took over.",
+            "type": "string"
+          },
+          "object": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/RecordSource"
+          },
+          "text": {
+            "description": "The text that the record wrote as its ID, such as `standard`, when the text is no vendor ID.",
+            "type": "string"
+          }
+        },
+        "required": ["object", "source", "id"],
         "type": "object"
       },
       "McpServer": {
@@ -1127,6 +1433,27 @@
         ],
         "type": "object"
       },
+      "ObjectLoad": {
+        "properties": {
+          "absent": {
+            "description": "How many records of the object did not load.",
+            "type": "integer"
+          },
+          "matched": {
+            "description": "How many records of the object took over a seed record.",
+            "type": "integer"
+          },
+          "native": {
+            "description": "How many records of the object loaded as records of their own, under their vendor IDs or IDs that the app made.",
+            "type": "integer"
+          },
+          "object": {
+            "type": "string"
+          }
+        },
+        "required": ["object", "native", "matched", "absent"],
+        "type": "object"
+      },
       "Organization": {
         "properties": {
           "domain": {
@@ -1173,21 +1500,64 @@
         "required": ["type", "id", "name"],
         "type": "object"
       },
-      "Request": {
+      "ProblemCounts": {
+        "description": "For each severity, how many problems of the load have each code. The errors are those of the records that did not load in `skipRecord` mode.",
         "properties": {
-          "appName": {
-            "type": "string"
-          },
-          "completedAt": {
-            "format": "date-time",
-            "type": "string"
-          },
-          "durationMs": {
-            "minimum": 0,
-            "type": "integer"
+          "error": {
+            "additionalProperties": {
+              "type": "integer"
+            },
+            "type": "object"
           },
-          "environmentId": {
-            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+          "warning": {
+            "additionalProperties": {
+              "type": "integer"
+            },
+            "type": "object"
+          }
+        },
+        "required": ["error", "warning"],
+        "type": "object"
+      },
+      "ReceivedImport": {
+        "properties": {
+          "received": {
+            "enum": [true],
+            "type": "boolean"
+          }
+        },
+        "required": ["received"],
+        "type": "object"
+      },
+      "RecordSource": {
+        "description": "The file that holds the record in the import, such as `salesforce/records/Opportunity.jsonl` or the manifest `acme.yaml`, and the line where the record starts, counted from 1.",
+        "properties": {
+          "file": {
+            "type": "string"
+          },
+          "line": {
+            "exclusiveMinimum": 0,
+            "type": ["integer", "null"]
+          }
+        },
+        "required": ["file", "line"],
+        "type": "object"
+      },
+      "Request": {
+        "properties": {
+          "appName": {
+            "type": "string"
+          },
+          "completedAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "durationMs": {
+            "minimum": 0,
+            "type": "integer"
+          },
+          "environmentId": {
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
             "type": "string"
           },
           "errorCode": {
@@ -1544,8 +1914,8 @@
         ],
         "type": "object"
       },
-      "SnapshotAppLoad": {
-        "description": "What the load of the snapshot's import left out of the app. Null for a snapshot of an environment, and until the app's load ends.",
+      "SnapshotAppFullLoad": {
+        "description": "The report of the load of the snapshot's import into the app. Each list holds its first items, which fit in the report's size, and the count beside it counts all of them. Null for a snapshot of an environment, and until the app's load ends.",
         "properties": {
           "absent": {
             "description": "The first records of the import that did not load, in the order of the import.",
@@ -1555,12 +1925,264 @@
             "type": "array"
           },
           "absentCount": {
-            "description": "How many records of the import did not load. It is larger than the length of `absent` when they did not all fit.",
+            "description": "How many records of the import did not load.",
+            "type": "integer"
+          },
+          "actorCount": {
+            "description": "How many users the import names in `actors` for the app.",
+            "type": "integer"
+          },
+          "actors": {
+            "description": "The first users that the import names in `actors`, in that order. The first is the default user.",
+            "items": {
+              "$ref": "#/components/schemas/ImportActor"
+            },
+            "type": "array"
+          },
+          "deactivated": {
+            "description": "The IDs of the first seed users that the load deactivated.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "deactivatedCount": {
+            "description": "How many seed users the load deactivated, because the import brings users of its own.",
+            "type": "integer"
+          },
+          "details": {
+            "enum": ["full"],
+            "type": "string"
+          },
+          "differenceCount": {
+            "description": "How many differences from the vendor's app the load knows of.",
+            "type": "integer"
+          },
+          "differences": {
+            "description": "The first differences from the vendor's app.",
+            "items": {
+              "$ref": "#/components/schemas/KnownDifference"
+            },
+            "type": "array"
+          },
+          "filled": {
+            "description": "The first fields that the app filled, by object and field.",
+            "items": {
+              "$ref": "#/components/schemas/FilledField"
+            },
+            "type": "array"
+          },
+          "filledCount": {
+            "description": "How many fields the app filled for loaded records that did not write them.",
+            "type": "integer"
+          },
+          "filledValueCount": {
+            "description": "How many values the app filled in those fields.",
+            "type": "integer"
+          },
+          "made": {
+            "description": "The first IDs that the app made, in the order of the import.",
+            "items": {
+              "$ref": "#/components/schemas/MadeId"
+            },
+            "type": "array"
+          },
+          "madeCount": {
+            "description": "How many IDs the app made for records, from the text that a record wrote as its ID or from the record's place.",
+            "type": "integer"
+          },
+          "matched": {
+            "description": "The first records that took over a seed record, in the order of the import.",
+            "items": {
+              "$ref": "#/components/schemas/MatchedRecord"
+            },
+            "type": "array"
+          },
+          "matchedCount": {
+            "description": "How many records took over a seed record.",
+            "type": "integer"
+          },
+          "objectCount": {
+            "description": "How many objects of the app the import holds records of.",
+            "type": "integer"
+          },
+          "objects": {
+            "description": "For the first objects of the app that the import holds records of, by name, how many of its records loaded, took over a seed record, or did not load.",
+            "items": {
+              "$ref": "#/components/schemas/ObjectLoad"
+            },
+            "type": "array"
+          },
+          "problemCounts": {
+            "$ref": "#/components/schemas/ProblemCounts"
+          },
+          "warningCount": {
+            "description": "How many warnings the load found.",
             "type": "integer"
+          },
+          "warnings": {
+            "description": "The first warnings of the load, in the order of file, line and pointer.",
+            "items": {
+              "$ref": "#/components/schemas/ImportProblem"
+            },
+            "type": "array"
           }
         },
-        "required": ["absentCount", "absent"],
-        "type": ["object", "null"]
+        "required": [
+          "details",
+          "objectCount",
+          "madeCount",
+          "matchedCount",
+          "filledCount",
+          "filledValueCount",
+          "actorCount",
+          "deactivatedCount",
+          "absentCount",
+          "differenceCount",
+          "problemCounts",
+          "warningCount",
+          "objects",
+          "made",
+          "matched",
+          "filled",
+          "actors",
+          "deactivated",
+          "absent",
+          "differences",
+          "warnings"
+        ],
+        "type": "object"
+      },
+      "SnapshotAppFullLoadCounts": {
+        "description": "Every count of the report of the load of the snapshot's import into the app, as the list of snapshots answers it. Get the snapshot for the first items of each list. Null for a snapshot of an environment, and until the app's load ends.",
+        "properties": {
+          "absentCount": {
+            "description": "How many records of the import did not load.",
+            "type": "integer"
+          },
+          "actorCount": {
+            "description": "How many users the import names in `actors` for the app.",
+            "type": "integer"
+          },
+          "deactivatedCount": {
+            "description": "How many seed users the load deactivated, because the import brings users of its own.",
+            "type": "integer"
+          },
+          "details": {
+            "enum": ["full"],
+            "type": "string"
+          },
+          "differenceCount": {
+            "description": "How many differences from the vendor's app the load knows of.",
+            "type": "integer"
+          },
+          "filledCount": {
+            "description": "How many fields the app filled for loaded records that did not write them.",
+            "type": "integer"
+          },
+          "filledValueCount": {
+            "description": "How many values the app filled in those fields.",
+            "type": "integer"
+          },
+          "madeCount": {
+            "description": "How many IDs the app made for records, from the text that a record wrote as its ID or from the record's place.",
+            "type": "integer"
+          },
+          "matchedCount": {
+            "description": "How many records took over a seed record.",
+            "type": "integer"
+          },
+          "objectCount": {
+            "description": "How many objects of the app the import holds records of.",
+            "type": "integer"
+          },
+          "problemCounts": {
+            "$ref": "#/components/schemas/ProblemCounts"
+          },
+          "warningCount": {
+            "description": "How many warnings the load found.",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "details",
+          "objectCount",
+          "madeCount",
+          "matchedCount",
+          "filledCount",
+          "filledValueCount",
+          "actorCount",
+          "deactivatedCount",
+          "absentCount",
+          "differenceCount",
+          "problemCounts",
+          "warningCount"
+        ],
+        "type": "object"
+      },
+      "SnapshotAppLimitedLoad": {
+        "description": "The recorded count and first skipped records. Additional import diagnostics were not recorded for this snapshot.",
+        "properties": {
+          "absent": {
+            "items": {
+              "$ref": "#/components/schemas/AbsentRecord"
+            },
+            "type": "array"
+          },
+          "absentCount": {
+            "description": "How many records of the import did not load.",
+            "type": "integer"
+          },
+          "details": {
+            "enum": ["limited"],
+            "type": "string"
+          }
+        },
+        "required": ["details", "absentCount", "absent"],
+        "type": "object"
+      },
+      "SnapshotAppLimitedLoadCounts": {
+        "description": "The recorded count of skipped records. Additional import diagnostics were not recorded for this snapshot.",
+        "properties": {
+          "absentCount": {
+            "description": "How many records of the import did not load.",
+            "type": "integer"
+          },
+          "details": {
+            "enum": ["limited"],
+            "type": "string"
+          }
+        },
+        "required": ["details", "absentCount"],
+        "type": "object"
+      },
+      "SnapshotAppLoad": {
+        "description": "Recorded import diagnostics. Full reports contain every diagnostic category. Limited reports preserve skipped records when additional details were not recorded.",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/SnapshotAppFullLoad"
+          },
+          {
+            "$ref": "#/components/schemas/SnapshotAppLimitedLoad"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "SnapshotAppLoadCounts": {
+        "description": "Recorded import counts. Full reports contain every diagnostic count. Limited reports contain only the skipped-record count.",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/SnapshotAppFullLoadCounts"
+          },
+          {
+            "$ref": "#/components/schemas/SnapshotAppLimitedLoadCounts"
+          },
+          {
+            "type": "null"
+          }
+        ]
       },
       "SnapshotFailure": {
         "anyOf": [
@@ -1605,41 +2227,147 @@
           }
         ]
       },
-      "SnapshotStatus": {
-        "enum": ["saving", "ready", "failed", "deleted"],
-        "type": "string"
-      },
-      "UiSessionLaunch": {
+      "SnapshotListItem": {
+        "description": "A snapshot as the list answers it: each app's load holds its counts only. Get the snapshot for the lists of each load.",
         "properties": {
-          "actorId": {
-            "type": "string"
+          "apps": {
+            "items": {
+              "properties": {
+                "appId": {
+                  "type": "string"
+                },
+                "load": {
+                  "$ref": "#/components/schemas/SnapshotAppLoadCounts"
+                },
+                "name": {
+                  "pattern": "^[a-z][a-z0-9-]{0,39}$",
+                  "type": "string"
+                },
+                "services": {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                "setup": {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                "version": {
+                  "type": "string"
+                },
+                "versionId": {
+                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "name",
+                "appId",
+                "versionId",
+                "version",
+                "setup",
+                "services"
+              ],
+              "type": "object"
+            },
+            "type": "array"
           },
-          "appName": {
-            "pattern": "^[a-z][a-z0-9-]{0,39}$",
+          "createdAt": {
+            "format": "date-time",
             "type": "string"
           },
-          "entryPath": {
-            "type": "string"
+          "createdBy": {
+            "$ref": "#/components/schemas/Principal"
+          },
+          "deletedAt": {
+            "format": "date-time",
+            "type": ["string", "null"]
           },
           "environmentId": {
+            "description": "The environment that the snapshot copies, or null for a snapshot built from an import.",
             "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
-            "type": "string"
-          },
-          "exchangeUrl": {
-            "type": "string"
+            "type": ["string", "null"]
           },
-          "expiresAt": {
-            "format": "date-time",
-            "type": "string"
+          "environmentName": {
+            "type": ["string", "null"]
           },
-          "grant": {
-            "type": "string"
+          "failure": {
+            "$ref": "#/components/schemas/SnapshotFailure"
           },
-          "grantExpiresAt": {
-            "format": "date-time",
+          "id": {
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
             "type": "string"
           },
-          "mode": {
+          "importId": {
+            "description": "The import that the snapshot was built from, or null for a snapshot of an environment.",
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+            "type": ["string", "null"]
+          },
+          "name": {
+            "type": ["string", "null"]
+          },
+          "readyAt": {
+            "format": "date-time",
+            "type": ["string", "null"]
+          },
+          "status": {
+            "$ref": "#/components/schemas/SnapshotStatus"
+          },
+          "workspaceId": {
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "workspaceId",
+          "environmentId",
+          "environmentName",
+          "name",
+          "status",
+          "failure",
+          "apps",
+          "createdBy",
+          "createdAt",
+          "readyAt",
+          "deletedAt"
+        ],
+        "type": "object"
+      },
+      "SnapshotStatus": {
+        "enum": ["saving", "ready", "failed", "deleted"],
+        "type": "string"
+      },
+      "UiSessionLaunch": {
+        "properties": {
+          "actorId": {
+            "type": "string"
+          },
+          "appName": {
+            "pattern": "^[a-z][a-z0-9-]{0,39}$",
+            "type": "string"
+          },
+          "entryPath": {
+            "type": "string"
+          },
+          "environmentId": {
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+            "type": "string"
+          },
+          "exchangeUrl": {
+            "type": "string"
+          },
+          "expiresAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "grant": {
+            "type": "string"
+          },
+          "grantExpiresAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "mode": {
             "$ref": "#/components/schemas/UiSessionMode"
           },
           "origin": {
@@ -1699,6 +2427,7 @@
       "Version": {
         "properties": {
           "actors": {
+            "description": "The seed's users, for display. Credentials can act as any user who can sign in to the running app. `GET /v1/environments/{environmentId}/apps/{appName}/actors` lists them.",
             "items": {
               "$ref": "#/components/schemas/Actor"
             },
@@ -1971,10 +2700,716 @@
           },
           {
             "in": "query",
-            "name": "cursor",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "maxLength": 2048,
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "$ref": "#/components/schemas/Version"
+                      },
+                      "type": "array"
+                    },
+                    "nextCursor": {
+                      "type": ["string", "null"]
+                    }
+                  },
+                  "required": ["data", "nextCursor"],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "The app's published versions, newest first"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Invalid request"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Permission denied"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Resource not found"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Conflicting request"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Request body too large"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Version unavailable"
+          },
+          "429": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Limit reached"
+          },
+          "500": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Unexpected failure"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Dependency unavailable"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/v1/audit-events": {
+      "get": {
+        "operationId": "listAuditEvents",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 50,
+              "maximum": 100,
+              "minimum": 1,
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "maxLength": 2048,
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "workspaceId",
+            "required": false,
+            "schema": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "environmentId",
+            "required": false,
+            "schema": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "$ref": "#/components/schemas/AuditEvent"
+                      },
+                      "type": "array"
+                    },
+                    "nextCursor": {
+                      "type": ["string", "null"]
+                    }
+                  },
+                  "required": ["data", "nextCursor"],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "A workspace's or an environment's audit events, newest first"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Invalid request"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Permission denied"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Resource not found"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Conflicting request"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Request body too large"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Version unavailable"
+          },
+          "429": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Limit reached"
+          },
+          "500": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Unexpected failure"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Dependency unavailable"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/v1/environments": {
+      "get": {
+        "operationId": "listEnvironments",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 50,
+              "maximum": 100,
+              "minimum": 1,
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "maxLength": 2048,
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "workspaceId",
+            "required": false,
+            "schema": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "status",
+            "required": false,
+            "schema": {
+              "items": {
+                "$ref": "#/components/schemas/EnvironmentStatus"
+              },
+              "maxItems": 5,
+              "type": "array"
+            }
+          },
+          {
+            "in": "query",
+            "name": "appId",
+            "required": false,
+            "schema": {
+              "items": {
+                "pattern": "^[a-z][a-z0-9-]{1,39}$",
+                "type": "string"
+              },
+              "maxItems": 20,
+              "type": "array"
+            }
+          },
+          {
+            "in": "query",
+            "name": "createdBy",
+            "required": false,
+            "schema": {
+              "items": {
+                "pattern": "^(user_[0-9A-Za-z]+|key_[0-9a-z]{16})$",
+                "type": "string"
+              },
+              "maxItems": 50,
+              "type": "array"
+            }
+          },
+          {
+            "in": "query",
+            "name": "snapshotId",
+            "required": false,
+            "schema": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "search",
+            "required": false,
+            "schema": {
+              "maxLength": 120,
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "label",
+            "required": false,
+            "schema": {
+              "items": {
+                "pattern": "^[^=]+=.*$",
+                "type": "string"
+              },
+              "maxItems": 32,
+              "type": "array"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "$ref": "#/components/schemas/Environment"
+                      },
+                      "type": "array"
+                    },
+                    "nextCursor": {
+                      "type": ["string", "null"]
+                    }
+                  },
+                  "required": ["data", "nextCursor"],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "The workspace's environments, newest created first"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Invalid request"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Permission denied"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Resource not found"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Conflicting request"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Request body too large"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Version unavailable"
+          },
+          "429": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Limit reached"
+          },
+          "500": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Unexpected failure"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Dependency unavailable"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "createEnvironment",
+        "parameters": [
+          {
+            "in": "header",
+            "name": "idempotency-key",
+            "required": false,
+            "schema": {
+              "maxLength": 128,
+              "minLength": 8,
+              "pattern": "^[A-Za-z0-9._:-]+$",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateEnvironment"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Environment"
+                }
+              }
+            },
+            "description": "The environment an earlier request with this Idempotency-Key created, as it is now"
+          },
+          "202": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Environment"
+                }
+              }
+            },
+            "description": "Environment starting"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Invalid request"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Permission denied"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Resource not found"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Conflicting request"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Request body too large"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Version unavailable"
+          },
+          "429": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Limit reached"
+          },
+          "500": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Unexpected failure"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Dependency unavailable"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/v1/environments/creators": {
+      "get": {
+        "operationId": "listEnvironmentCreators",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "workspaceId",
             "required": false,
             "schema": {
-              "maxLength": 2048,
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
           }
@@ -1987,20 +3422,17 @@
                   "properties": {
                     "data": {
                       "items": {
-                        "$ref": "#/components/schemas/Version"
+                        "$ref": "#/components/schemas/Principal"
                       },
                       "type": "array"
-                    },
-                    "nextCursor": {
-                      "type": ["string", "null"]
                     }
                   },
-                  "required": ["data", "nextCursor"],
+                  "required": ["data"],
                   "type": "object"
                 }
               }
             },
-            "description": "The app's published versions, newest first"
+            "description": "Each principal that created an environment in the workspace, by name"
           },
           "400": {
             "content": {
@@ -2110,45 +3542,27 @@
         ]
       }
     },
-    "/v1/audit-events": {
-      "get": {
-        "operationId": "listAuditEvents",
+    "/v1/environments/{environmentId}": {
+      "delete": {
+        "operationId": "deleteEnvironment",
         "parameters": [
           {
-            "in": "query",
-            "name": "limit",
-            "required": false,
-            "schema": {
-              "default": 50,
-              "maximum": 100,
-              "minimum": 1,
-              "type": "integer"
-            }
-          },
-          {
-            "in": "query",
-            "name": "cursor",
-            "required": false,
-            "schema": {
-              "maxLength": 2048,
-              "type": "string"
-            }
-          },
-          {
-            "in": "query",
-            "name": "workspaceId",
-            "required": false,
+            "in": "path",
+            "name": "environmentId",
+            "required": true,
             "schema": {
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
           },
           {
-            "in": "query",
-            "name": "environmentId",
+            "in": "header",
+            "name": "idempotency-key",
             "required": false,
             "schema": {
-              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "maxLength": 128,
+              "minLength": 8,
+              "pattern": "^[A-Za-z0-9._:-]+$",
               "type": "string"
             }
           }
@@ -2158,23 +3572,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "properties": {
-                    "data": {
-                      "items": {
-                        "$ref": "#/components/schemas/AuditEvent"
-                      },
-                      "type": "array"
-                    },
-                    "nextCursor": {
-                      "type": ["string", "null"]
-                    }
-                  },
-                  "required": ["data", "nextCursor"],
-                  "type": "object"
+                  "$ref": "#/components/schemas/Environment"
                 }
               }
             },
-            "description": "A workspace's or an environment's audit events, newest first"
+            "description": "Environment deleted; compute and data are released after the response"
           },
           "400": {
             "content": {
@@ -2282,109 +3684,18 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/v1/environments": {
+      },
       "get": {
-        "operationId": "listEnvironments",
+        "operationId": "getEnvironment",
         "parameters": [
           {
-            "in": "query",
-            "name": "limit",
-            "required": false,
-            "schema": {
-              "default": 50,
-              "maximum": 100,
-              "minimum": 1,
-              "type": "integer"
-            }
-          },
-          {
-            "in": "query",
-            "name": "cursor",
-            "required": false,
-            "schema": {
-              "maxLength": 2048,
-              "type": "string"
-            }
-          },
-          {
-            "in": "query",
-            "name": "workspaceId",
-            "required": false,
-            "schema": {
-              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
-              "type": "string"
-            }
-          },
-          {
-            "in": "query",
-            "name": "status",
-            "required": false,
-            "schema": {
-              "items": {
-                "$ref": "#/components/schemas/EnvironmentStatus"
-              },
-              "maxItems": 5,
-              "type": "array"
-            }
-          },
-          {
-            "in": "query",
-            "name": "appId",
-            "required": false,
-            "schema": {
-              "items": {
-                "pattern": "^[a-z][a-z0-9-]{1,39}$",
-                "type": "string"
-              },
-              "maxItems": 20,
-              "type": "array"
-            }
-          },
-          {
-            "in": "query",
-            "name": "createdBy",
-            "required": false,
-            "schema": {
-              "items": {
-                "pattern": "^(user_[0-9A-Za-z]+|key_[0-9a-z]{16})$",
-                "type": "string"
-              },
-              "maxItems": 50,
-              "type": "array"
-            }
-          },
-          {
-            "in": "query",
-            "name": "snapshotId",
-            "required": false,
+            "in": "path",
+            "name": "environmentId",
+            "required": true,
             "schema": {
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
-          },
-          {
-            "in": "query",
-            "name": "search",
-            "required": false,
-            "schema": {
-              "maxLength": 120,
-              "type": "string"
-            }
-          },
-          {
-            "in": "query",
-            "name": "label",
-            "required": false,
-            "schema": {
-              "items": {
-                "pattern": "^[^=]+=.*$",
-                "type": "string"
-              },
-              "maxItems": 32,
-              "type": "array"
-            }
           }
         ],
         "responses": {
@@ -2392,23 +3703,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "properties": {
-                    "data": {
-                      "items": {
-                        "$ref": "#/components/schemas/Environment"
-                      },
-                      "type": "array"
-                    },
-                    "nextCursor": {
-                      "type": ["string", "null"]
-                    }
-                  },
-                  "required": ["data", "nextCursor"],
-                  "type": "object"
+                  "$ref": "#/components/schemas/Environment"
                 }
               }
             },
-            "description": "The workspace's environments, newest created first"
+            "description": "Environment"
           },
           "400": {
             "content": {
@@ -2517,17 +3816,15 @@
           }
         ]
       },
-      "post": {
-        "operationId": "createEnvironment",
+      "patch": {
+        "operationId": "updateEnvironment",
         "parameters": [
           {
-            "in": "header",
-            "name": "idempotency-key",
-            "required": false,
+            "in": "path",
+            "name": "environmentId",
+            "required": true,
             "schema": {
-              "maxLength": 128,
-              "minLength": 8,
-              "pattern": "^[A-Za-z0-9._:-]+$",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
           }
@@ -2536,7 +3833,21 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateEnvironment"
+                "properties": {
+                  "labels": {
+                    "additionalProperties": {
+                      "maxLength": 256,
+                      "type": "string"
+                    },
+                    "type": "object"
+                  },
+                  "name": {
+                    "maxLength": 120,
+                    "minLength": 1,
+                    "type": ["string", "null"]
+                  }
+                },
+                "type": "object"
               }
             }
           },
@@ -2551,17 +3862,7 @@
                 }
               }
             },
-            "description": "The environment an earlier request with this Idempotency-Key created, as it is now"
-          },
-          "202": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Environment"
-                }
-              }
-            },
-            "description": "Environment starting"
+            "description": "Environment updated"
           },
           "400": {
             "content": {
@@ -2666,21 +3967,60 @@
         },
         "security": [
           {
-            "bearerAuth": []
-          }
-        ]
-      }
-    },
-    "/v1/environments/creators": {
-      "get": {
-        "operationId": "listEnvironmentCreators",
-        "parameters": [
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/v1/environments/{environmentId}/apps/{appName}/actors": {
+      "get": {
+        "operationId": "listActors",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "environmentId",
+            "required": true,
+            "schema": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "path",
+            "name": "appName",
+            "required": true,
+            "schema": {
+              "pattern": "^[a-z][a-z0-9-]{0,39}$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "default": 50,
+              "maximum": 100,
+              "minimum": 1,
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "maxLength": 2048,
+              "minLength": 1,
+              "type": "string"
+            }
+          },
           {
             "in": "query",
-            "name": "workspaceId",
+            "name": "search",
             "required": false,
             "schema": {
-              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "maxLength": 320,
               "type": "string"
             }
           }
@@ -2693,17 +4033,20 @@
                   "properties": {
                     "data": {
                       "items": {
-                        "$ref": "#/components/schemas/Principal"
+                        "$ref": "#/components/schemas/AppUser"
                       },
                       "type": "array"
+                    },
+                    "nextCursor": {
+                      "type": ["string", "null"]
                     }
                   },
-                  "required": ["data"],
+                  "required": ["data", "nextCursor"],
                   "type": "object"
                 }
               }
             },
-            "description": "Each principal that created an environment in the workspace, by name"
+            "description": "The users who can act in one app of a running environment, the default user first, as the app answers them"
           },
           "400": {
             "content": {
@@ -2813,9 +4156,9 @@
         ]
       }
     },
-    "/v1/environments/{environmentId}": {
-      "delete": {
-        "operationId": "deleteEnvironment",
+    "/v1/environments/{environmentId}/apps/{appName}/credentials": {
+      "post": {
+        "operationId": "createCredentials",
         "parameters": [
           {
             "in": "path",
@@ -2827,27 +4170,56 @@
             }
           },
           {
-            "in": "header",
-            "name": "idempotency-key",
-            "required": false,
+            "in": "path",
+            "name": "appName",
+            "required": true,
             "schema": {
-              "maxLength": 128,
-              "minLength": 8,
-              "pattern": "^[A-Za-z0-9._:-]+$",
+              "pattern": "^[a-z][a-z0-9-]{0,39}$",
               "type": "string"
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "actorId": {
+                    "deprecated": true,
+                    "description": "The old name of `as`. It takes the same values.",
+                    "maxLength": 320,
+                    "type": "string"
+                  },
+                  "as": {
+                    "description": "The user to act as: an email, a username or an ID of a user of the app. Without it, the call acts as the app's default user.",
+                    "maxLength": 320,
+                    "type": "string"
+                  },
+                  "services": {
+                    "items": {
+                      "pattern": "^[a-z][a-z0-9-]{0,39}$",
+                      "type": "string"
+                    },
+                    "maxItems": 20,
+                    "type": "array"
+                  }
+                },
+                "type": "object"
+              }
+            }
+          },
+          "required": false
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Environment"
+                  "$ref": "#/components/schemas/Credentials"
                 }
               }
             },
-            "description": "Environment deleted; compute and data are released after the response"
+            "description": "How to call one app as one actor; the same tokens each time"
           },
           "400": {
             "content": {
@@ -2955,9 +4327,12 @@
             "bearerAuth": []
           }
         ]
-      },
-      "get": {
-        "operationId": "getEnvironment",
+      }
+    },
+    "/v1/environments/{environmentId}/apps/{appName}/ui-sessions": {
+      "post": {
+        "description": "Launches a browser session of one actor in an app's UI. The answer holds a one-use grant and no reusable credential. Return it only to the browser of the user it is for, which posts the grant to `exchangeUrl` from `launcherOrigin`.",
+        "operationId": "launchUiSession",
         "parameters": [
           {
             "in": "path",
@@ -2967,18 +4342,37 @@
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
+          },
+          {
+            "in": "path",
+            "name": "appName",
+            "required": true,
+            "schema": {
+              "pattern": "^[a-z][a-z0-9-]{0,39}$",
+              "type": "string"
+            }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/LaunchUiSession"
+              }
+            }
+          },
+          "required": true
+        },
         "responses": {
-          "200": {
+          "201": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Environment"
+                  "$ref": "#/components/schemas/UiSessionLaunch"
                 }
               }
             },
-            "description": "Environment"
+            "description": "A pending session and its one-use grant"
           },
           "400": {
             "content": {
@@ -3086,9 +4480,12 @@
             "bearerAuth": []
           }
         ]
-      },
-      "patch": {
-        "operationId": "updateEnvironment",
+      }
+    },
+    "/v1/environments/{environmentId}/apps/{appName}/ui-sessions/{sessionId}": {
+      "delete": {
+        "description": "Revokes a browser session that the caller's own credential launched. Revoking again answers the same result. Another credential's session is not found.",
+        "operationId": "revokeUiSession",
         "parameters": [
           {
             "in": "path",
@@ -3098,42 +4495,36 @@
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "properties": {
-                  "labels": {
-                    "additionalProperties": {
-                      "maxLength": 256,
-                      "type": "string"
-                    },
-                    "type": "object"
-                  },
-                  "name": {
-                    "maxLength": 120,
-                    "minLength": 1,
-                    "type": ["string", "null"]
-                  }
-                },
-                "type": "object"
-              }
+          },
+          {
+            "in": "path",
+            "name": "appName",
+            "required": true,
+            "schema": {
+              "pattern": "^[a-z][a-z0-9-]{0,39}$",
+              "type": "string"
             }
           },
-          "required": true
-        },
+          {
+            "in": "path",
+            "name": "sessionId",
+            "required": true,
+            "schema": {
+              "pattern": "^uis_[0-9a-z]{26}$",
+              "type": "string"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Environment"
+                  "$ref": "#/components/schemas/UiSessionRevocation"
                 }
               }
             },
-            "description": "Environment updated"
+            "description": "The session is revoked"
           },
           "400": {
             "content": {
@@ -3243,64 +4634,74 @@
         ]
       }
     },
-    "/v1/environments/{environmentId}/apps/{appName}/credentials": {
-      "post": {
-        "operationId": "createCredentials",
+    "/v1/imports": {
+      "get": {
+        "operationId": "listImports",
         "parameters": [
           {
-            "in": "path",
-            "name": "environmentId",
-            "required": true,
+            "in": "query",
+            "name": "limit",
+            "required": false,
             "schema": {
-              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "default": 50,
+              "maximum": 100,
+              "minimum": 1,
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "maxLength": 2048,
               "type": "string"
             }
           },
           {
-            "in": "path",
-            "name": "appName",
-            "required": true,
+            "in": "query",
+            "name": "workspaceId",
+            "required": false,
             "schema": {
-              "pattern": "^[a-z][a-z0-9-]{0,39}$",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
+          },
+          {
+            "in": "query",
+            "name": "status",
+            "required": false,
+            "schema": {
+              "items": {
+                "$ref": "#/components/schemas/ImportStatus"
+              },
+              "maxItems": 4,
+              "type": "array"
+            }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "properties": {
-                  "actorId": {
-                    "maxLength": 255,
-                    "minLength": 1,
-                    "type": "string"
-                  },
-                  "services": {
-                    "items": {
-                      "pattern": "^[a-z][a-z0-9-]{0,39}$",
-                      "type": "string"
-                    },
-                    "maxItems": 20,
-                    "type": "array"
-                  }
-                },
-                "type": "object"
-              }
-            }
-          },
-          "required": false
-        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Credentials"
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "$ref": "#/components/schemas/Import"
+                      },
+                      "type": "array"
+                    },
+                    "nextCursor": {
+                      "type": ["string", "null"]
+                    }
+                  },
+                  "required": ["data", "nextCursor"],
+                  "type": "object"
                 }
               }
             },
-            "description": "How to call one app as one actor; the same tokens each time"
+            "description": "The workspace's imports, newest first"
           },
           "400": {
             "content": {
@@ -3408,28 +4809,18 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/v1/environments/{environmentId}/apps/{appName}/ui-sessions": {
+      },
       "post": {
-        "description": "Launches a browser session of one actor in an app's UI. The answer holds a one-use grant and no reusable credential. Return it only to the browser of the user it is for, which posts the grant to `exchangeUrl` from `launcherOrigin`.",
-        "operationId": "launchUiSession",
+        "operationId": "createImport",
         "parameters": [
           {
-            "in": "path",
-            "name": "environmentId",
-            "required": true,
-            "schema": {
-              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
-              "type": "string"
-            }
-          },
-          {
-            "in": "path",
-            "name": "appName",
-            "required": true,
+            "in": "header",
+            "name": "idempotency-key",
+            "required": false,
             "schema": {
-              "pattern": "^[a-z][a-z0-9-]{0,39}$",
+              "maxLength": 128,
+              "minLength": 8,
+              "pattern": "^[A-Za-z0-9._:-]+$",
               "type": "string"
             }
           }
@@ -3438,22 +4829,51 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/LaunchUiSession"
+                "properties": {
+                  "digest": {
+                    "description": "`sha256:` and the lowercase hex SHA-256 of the zip file. The check refuses a zip file with another digest.",
+                    "pattern": "^sha256:[0-9a-f]{64}$",
+                    "type": "string"
+                  },
+                  "sizeBytes": {
+                    "description": "The size of the zip file in bytes. The upload URL takes exactly this many bytes.",
+                    "maximum": 67108864,
+                    "minimum": 1,
+                    "type": "integer"
+                  },
+                  "workspaceId": {
+                    "description": "The import's workspace. A member must send it. An API key's own workspace is the default.",
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+                    "type": "string"
+                  }
+                },
+                "required": ["sizeBytes", "digest"],
+                "type": "object"
               }
             }
           },
           "required": true
         },
         "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreatedImport"
+                }
+              }
+            },
+            "description": "The import an earlier request with this Idempotency-Key created, as it is now, with a new upload URL while it is `uploading`"
+          },
           "201": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/UiSessionLaunch"
+                  "$ref": "#/components/schemas/CreatedImport"
                 }
               }
             },
-            "description": "A pending session and its one-use grant"
+            "description": "Import created; send its zip file to the upload URL, then complete it"
           },
           "400": {
             "content": {
@@ -3563,37 +4983,18 @@
         ]
       }
     },
-    "/v1/environments/{environmentId}/apps/{appName}/ui-sessions/{sessionId}": {
+    "/v1/imports/{importId}": {
       "delete": {
-        "description": "Revokes a browser session that the caller's own credential launched. Revoking again answers the same result. Another credential's session is not found.",
-        "operationId": "revokeUiSession",
+        "operationId": "deleteImport",
         "parameters": [
           {
             "in": "path",
-            "name": "environmentId",
+            "name": "importId",
             "required": true,
             "schema": {
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
-          },
-          {
-            "in": "path",
-            "name": "appName",
-            "required": true,
-            "schema": {
-              "pattern": "^[a-z][a-z0-9-]{0,39}$",
-              "type": "string"
-            }
-          },
-          {
-            "in": "path",
-            "name": "sessionId",
-            "required": true,
-            "schema": {
-              "pattern": "^uis_[0-9a-z]{26}$",
-              "type": "string"
-            }
           }
         ],
         "responses": {
@@ -3601,11 +5002,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/UiSessionRevocation"
+                  "$ref": "#/components/schemas/Import"
                 }
               }
             },
-            "description": "The session is revoked"
+            "description": "Import deleted, with its problems cleared and its zip file removed"
           },
           "400": {
             "content": {
@@ -3713,52 +5114,18 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/v1/imports": {
+      },
       "get": {
-        "operationId": "listImports",
+        "operationId": "getImport",
         "parameters": [
           {
-            "in": "query",
-            "name": "limit",
-            "required": false,
-            "schema": {
-              "default": 50,
-              "maximum": 100,
-              "minimum": 1,
-              "type": "integer"
-            }
-          },
-          {
-            "in": "query",
-            "name": "cursor",
-            "required": false,
-            "schema": {
-              "maxLength": 2048,
-              "type": "string"
-            }
-          },
-          {
-            "in": "query",
-            "name": "workspaceId",
-            "required": false,
+            "in": "path",
+            "name": "importId",
+            "required": true,
             "schema": {
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
-          },
-          {
-            "in": "query",
-            "name": "status",
-            "required": false,
-            "schema": {
-              "items": {
-                "$ref": "#/components/schemas/ImportStatus"
-              },
-              "maxItems": 4,
-              "type": "array"
-            }
           }
         ],
         "responses": {
@@ -3766,23 +5133,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "properties": {
-                    "data": {
-                      "items": {
-                        "$ref": "#/components/schemas/Import"
-                      },
-                      "type": "array"
-                    },
-                    "nextCursor": {
-                      "type": ["string", "null"]
-                    }
-                  },
-                  "required": ["data", "nextCursor"],
-                  "type": "object"
+                  "$ref": "#/components/schemas/Import"
                 }
               }
             },
-            "description": "The workspace's imports, newest first"
+            "description": "Import"
           },
           "400": {
             "content": {
@@ -3890,71 +5245,32 @@
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/v1/imports/{importId}/complete": {
       "post": {
-        "operationId": "createImport",
+        "operationId": "completeImport",
         "parameters": [
           {
-            "in": "header",
-            "name": "idempotency-key",
-            "required": false,
+            "in": "path",
+            "name": "importId",
+            "required": true,
             "schema": {
-              "maxLength": 128,
-              "minLength": 8,
-              "pattern": "^[A-Za-z0-9._:-]+$",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "properties": {
-                  "digest": {
-                    "description": "`sha256:` and the lowercase hex SHA-256 of the zip file. The check refuses a zip file with another digest.",
-                    "pattern": "^sha256:[0-9a-f]{64}$",
-                    "type": "string"
-                  },
-                  "sizeBytes": {
-                    "description": "The size of the zip file in bytes. The upload URL takes exactly this many bytes.",
-                    "maximum": 67108864,
-                    "minimum": 1,
-                    "type": "integer"
-                  },
-                  "workspaceId": {
-                    "description": "The import's workspace. A member must send it. An API key's own workspace is the default.",
-                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
-                    "type": "string"
-                  }
-                },
-                "required": ["sizeBytes", "digest"],
-                "type": "object"
-              }
-            }
-          },
-          "required": true
-        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/CreatedImport"
-                }
-              }
-            },
-            "description": "The import an earlier request with this Idempotency-Key created, as it is now, with a new upload URL while it is `uploading`"
-          },
-          "201": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CreatedImport"
+                  "$ref": "#/components/schemas/Import"
                 }
               }
             },
-            "description": "Import created; send its zip file to the upload URL, then complete it"
+            "description": "The import after its check, which runs each app's own check on the app's part, as a build of a snapshot does: `ready`, or `invalid` with its problems"
           },
           "400": {
             "content": {
@@ -4064,9 +5380,9 @@
         ]
       }
     },
-    "/v1/imports/{importId}": {
-      "delete": {
-        "operationId": "deleteImport",
+    "/v1/imports/{importId}/file": {
+      "get": {
+        "operationId": "getImportFile",
         "parameters": [
           {
             "in": "path",
@@ -4076,6 +5392,16 @@
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
+          },
+          {
+            "in": "query",
+            "name": "path",
+            "required": true,
+            "schema": {
+              "maxLength": 65535,
+              "minLength": 1,
+              "type": "string"
+            }
           }
         ],
         "responses": {
@@ -4083,11 +5409,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Import"
+                  "$ref": "#/components/schemas/ImportFile"
                 }
               }
             },
-            "description": "Import deleted, with its problems cleared and its zip file removed"
+            "description": "A bounded preview of an original file; a truncated prefix does not verify the full file CRC"
           },
           "400": {
             "content": {
@@ -4195,9 +5521,11 @@
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/v1/imports/{importId}/files": {
       "get": {
-        "operationId": "getImport",
+        "operationId": "listImportFiles",
         "parameters": [
           {
             "in": "path",
@@ -4207,6 +5535,25 @@
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
+          },
+          {
+            "in": "query",
+            "name": "path",
+            "required": false,
+            "schema": {
+              "default": "",
+              "maxLength": 65535,
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "maxLength": 2048,
+              "type": "string"
+            }
           }
         ],
         "responses": {
@@ -4214,11 +5561,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Import"
+                  "$ref": "#/components/schemas/ImportFolder"
                 }
               }
             },
-            "description": "Import"
+            "description": "Immediate folder entries in the original upload, or an unavailable source"
           },
           "400": {
             "content": {
@@ -4328,9 +5675,9 @@
         ]
       }
     },
-    "/v1/imports/{importId}/complete": {
-      "post": {
-        "operationId": "completeImport",
+    "/v1/imports/{importId}/upload": {
+      "put": {
+        "operationId": "uploadImport",
         "parameters": [
           {
             "in": "path",
@@ -4342,16 +5689,27 @@
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/zip": {
+              "schema": {
+                "format": "binary",
+                "type": "string"
+              }
+            }
+          },
+          "required": true
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Import"
+                  "$ref": "#/components/schemas/ReceivedImport"
                 }
               }
             },
-            "description": "The import after the check of its zip file: `ready`, or `invalid` with its problems"
+            "description": "ZIP received; complete the import to check it"
           },
           "400": {
             "content": {
@@ -5493,7 +6851,7 @@
                   "properties": {
                     "data": {
                       "items": {
-                        "$ref": "#/components/schemas/Snapshot"
+                        "$ref": "#/components/schemas/SnapshotListItem"
                       },
                       "type": "array"
                     },
@@ -5506,7 +6864,7 @@
                 }
               }
             },
-            "description": "The workspace's snapshots, newest first"
+            "description": "The workspace's snapshots, newest first, each app's load with its counts only"
           },
           "400": {
             "content": {