@usestatemachines/sdk 0.9.0 → 0.10.0

package/openapi.json

@@ -1,6 +1,95 @@
 {
   "components": {
     "schemas": {
+      "AbsentReason": {
+        "anyOf": [
+          {
+            "properties": {
+              "message": {
+                "type": "string"
+              },
+              "type": {
+                "enum": ["identity"],
+                "type": "string"
+              }
+            },
+            "required": ["type", "message"],
+            "type": "object"
+          },
+          {
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "pointer": {
+                "type": ["string", "null"]
+              },
+              "type": {
+                "enum": ["problem"],
+                "type": "string"
+              }
+            },
+            "required": ["type", "code", "pointer", "message"],
+            "type": "object"
+          },
+          {
+            "properties": {
+              "nativeId": {
+                "type": "string"
+              },
+              "object": {
+                "type": "string"
+              },
+              "pointer": {
+                "type": "string"
+              },
+              "type": {
+                "enum": ["reference"],
+                "type": "string"
+              }
+            },
+            "required": ["type", "pointer", "object", "nativeId"],
+            "type": "object"
+          }
+        ],
+        "description": "Why the record did not load."
+      },
+      "AbsentRecord": {
+        "properties": {
+          "nativeId": {
+            "description": "The vendor's ID of the record, or null for a record that holds none.",
+            "type": ["string", "null"]
+          },
+          "object": {
+            "type": "string"
+          },
+          "reason": {
+            "$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"
+          },
+          "line": {
+            "exclusiveMinimum": 0,
+            "type": ["integer", "null"]
+          }
+        },
+        "required": ["file", "line"],
+        "type": "object"
+      },
       "Actor": {
         "properties": {
           "id": {
@@ -252,6 +341,83 @@
         "required": ["appId"],
         "type": "object"
       },
+      "CreateSnapshot": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/CreateSnapshotFromEnvironment"
+          },
+          {
+            "$ref": "#/components/schemas/CreateSnapshotFromImport"
+          }
+        ]
+      },
+      "CreateSnapshotFromEnvironment": {
+        "additionalProperties": false,
+        "properties": {
+          "environmentId": {
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+            "type": "string"
+          },
+          "name": {
+            "maxLength": 120,
+            "minLength": 1,
+            "type": ["string", "null"]
+          }
+        },
+        "required": ["environmentId"],
+        "type": "object"
+      },
+      "CreateSnapshotFromImport": {
+        "additionalProperties": false,
+        "properties": {
+          "importId": {
+            "description": "A `ready` import that the caller reaches. The snapshot gets every app of the import, each on the app's default version, with empty setup and services.",
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+            "type": "string"
+          },
+          "name": {
+            "maxLength": 120,
+            "minLength": 1,
+            "type": ["string", "null"]
+          }
+        },
+        "required": ["importId"],
+        "type": "object"
+      },
+      "CreatedImport": {
+        "properties": {
+          "import": {
+            "$ref": "#/components/schemas/Import"
+          },
+          "upload": {
+            "description": "Where to send the zip file while the import is `uploading`, and null after. Complete the import once the upload succeeds.",
+            "properties": {
+              "expiresAt": {
+                "format": "date-time",
+                "type": "string"
+              },
+              "headers": {
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "description": "Send the zip file as the body of a PUT to `url`, with each of these headers as given. The URL refuses another value of each.",
+                "type": "object"
+              },
+              "method": {
+                "enum": ["PUT"],
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": ["method", "url", "headers", "expiresAt"],
+            "type": ["object", "null"]
+          }
+        },
+        "required": ["import", "upload"],
+        "type": "object"
+      },
       "Credential": {
         "oneOf": [
           {
@@ -672,6 +838,120 @@
         "required": ["error"],
         "type": "object"
       },
+      "Import": {
+        "properties": {
+          "apps": {
+            "description": "Each app of the import's manifest, by its name and its app ID. Empty until the check reads the manifest, and when the check cannot read it.",
+            "items": {
+              "properties": {
+                "appId": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              },
+              "required": ["name", "appId"],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "checkedAt": {
+            "format": "date-time",
+            "type": ["string", "null"]
+          },
+          "createdAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "createdBy": {
+            "$ref": "#/components/schemas/Principal"
+          },
+          "deletedAt": {
+            "format": "date-time",
+            "type": ["string", "null"]
+          },
+          "digest": {
+            "description": "`sha256:` and the lowercase hex SHA-256 of the zip file, as the create declared it.",
+            "type": "string"
+          },
+          "id": {
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+            "type": "string"
+          },
+          "problemCount": {
+            "description": "How many problems the check found. It is larger than the length of `problems` when they did not all fit.",
+            "type": "integer"
+          },
+          "problems": {
+            "description": "The first problems that the check found, errors before warnings. A delete clears them.",
+            "items": {
+              "$ref": "#/components/schemas/ImportProblem"
+            },
+            "type": "array"
+          },
+          "sizeBytes": {
+            "description": "The size of the zip file in bytes, as the create declared it.",
+            "type": "integer"
+          },
+          "status": {
+            "$ref": "#/components/schemas/ImportStatus"
+          },
+          "workspaceId": {
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "workspaceId",
+          "status",
+          "sizeBytes",
+          "digest",
+          "apps",
+          "problems",
+          "problemCount",
+          "createdBy",
+          "createdAt",
+          "checkedAt",
+          "deletedAt"
+        ],
+        "type": "object"
+      },
+      "ImportProblem": {
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "file": {
+            "description": "The path in the import, such as `salesforce/records/Account.jsonl`. An empty path names the zip file as a whole.",
+            "type": "string"
+          },
+          "line": {
+            "description": "The line in the file, counted from 1, or null when the problem is about the whole file.",
+            "exclusiveMinimum": 0,
+            "type": ["integer", "null"]
+          },
+          "message": {
+            "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.",
+            "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.",
+            "enum": ["error", "warning"],
+            "type": "string"
+          }
+        },
+        "required": ["file", "line", "pointer", "code", "severity", "message"],
+        "type": "object"
+      },
+      "ImportStatus": {
+        "enum": ["uploading", "ready", "invalid", "deleted"],
+        "type": "string"
+      },
       "LaunchUiSession": {
         "additionalProperties": false,
         "properties": {
@@ -1167,6 +1447,9 @@
                 "appId": {
                   "type": "string"
                 },
+                "load": {
+                  "$ref": "#/components/schemas/SnapshotAppLoad"
+                },
                 "name": {
                   "pattern": "^[a-z][a-z0-9-]{0,39}$",
                   "type": "string"
@@ -1215,29 +1498,25 @@
             "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"
+            "type": ["string", "null"]
           },
           "environmentName": {
             "type": ["string", "null"]
           },
           "failure": {
-            "properties": {
-              "code": {
-                "enum": ["interrupted", "internal_error"],
-                "type": "string"
-              },
-              "message": {
-                "type": "string"
-              }
-            },
-            "required": ["code", "message"],
-            "type": ["object", "null"]
+            "$ref": "#/components/schemas/SnapshotFailure"
           },
           "id": {
             "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
             "type": "string"
           },
+          "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"]
           },
@@ -1273,27 +1552,88 @@
         ],
         "type": "object"
       },
-      "SnapshotStatus": {
-        "enum": ["saving", "ready", "failed", "deleted"],
-        "type": "string"
-      },
-      "UiSessionLaunch": {
+      "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.",
         "properties": {
-          "actorId": {
-            "type": "string"
-          },
-          "appName": {
-            "pattern": "^[a-z][a-z0-9-]{0,39}$",
-            "type": "string"
-          },
-          "entryPath": {
-            "type": "string"
+          "absent": {
+            "description": "The first records of the import that did not load, in the order of the import.",
+            "items": {
+              "$ref": "#/components/schemas/AbsentRecord"
+            },
+            "type": "array"
           },
-          "environmentId": {
-            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
-            "type": "string"
+          "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.",
+            "type": "integer"
+          }
+        },
+        "required": ["absentCount", "absent"],
+        "type": ["object", "null"]
+      },
+      "SnapshotFailure": {
+        "anyOf": [
+          {
+            "properties": {
+              "code": {
+                "enum": ["interrupted", "internal_error"],
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              }
+            },
+            "required": ["code", "message"],
+            "type": "object"
           },
-          "exchangeUrl": {
+          {
+            "properties": {
+              "appName": {
+                "type": "string"
+              },
+              "code": {
+                "enum": ["invalid_import"],
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "problems": {
+                "description": "The first problems that the load of the refusing app found, errors before warnings. It can be empty, such as when the load passed its time limit.",
+                "items": {
+                  "$ref": "#/components/schemas/ImportProblem"
+                },
+                "type": "array"
+              }
+            },
+            "required": ["code", "message"],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "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": {
@@ -2354,24 +2694,774 @@
           }
         ],
         "responses": {
-          "200": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "$ref": "#/components/schemas/Principal"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": ["data"],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Each principal that created an environment in the workspace, by name"
+          },
+          "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/{environmentId}": {
+      "delete": {
+        "operationId": "deleteEnvironment",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "environmentId",
+            "required": true,
+            "schema": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "header",
+            "name": "idempotency-key",
+            "required": false,
+            "schema": {
+              "maxLength": 128,
+              "minLength": 8,
+              "pattern": "^[A-Za-z0-9._:-]+$",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Environment"
+                }
+              }
+            },
+            "description": "Environment deleted; compute and data are released after the response"
+          },
+          "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": []
+          }
+        ]
+      },
+      "get": {
+        "operationId": "getEnvironment",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "environmentId",
+            "required": true,
+            "schema": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Environment"
+                }
+              }
+            },
+            "description": "Environment"
+          },
+          "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": []
+          }
+        ]
+      },
+      "patch": {
+        "operationId": "updateEnvironment",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "environmentId",
+            "required": true,
+            "schema": {
+              "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"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Environment"
+                }
+              }
+            },
+            "description": "Environment updated"
+          },
+          "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/{environmentId}/apps/{appName}/credentials": {
+      "post": {
+        "operationId": "createCredentials",
+        "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"
+            }
+          }
+        ],
+        "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"
+                }
+              }
+            },
+            "description": "How to call one app as one actor; the same tokens each time"
+          },
+          "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/{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",
+            "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"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/LaunchUiSession"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
             "content": {
               "application/json": {
                 "schema": {
-                  "properties": {
-                    "data": {
-                      "items": {
-                        "$ref": "#/components/schemas/Principal"
-                      },
-                      "type": "array"
-                    }
-                  },
-                  "required": ["data"],
-                  "type": "object"
+                  "$ref": "#/components/schemas/UiSessionLaunch"
                 }
               }
             },
-            "description": "Each principal that created an environment in the workspace, by name"
+            "description": "A pending session and its one-use grant"
           },
           "400": {
             "content": {
@@ -2481,9 +3571,10 @@
         ]
       }
     },
-    "/v1/environments/{environmentId}": {
+    "/v1/environments/{environmentId}/apps/{appName}/ui-sessions/{sessionId}": {
       "delete": {
-        "operationId": "deleteEnvironment",
+        "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",
@@ -2495,13 +3586,20 @@
             }
           },
           {
-            "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"
+            }
+          },
+          {
+            "in": "path",
+            "name": "sessionId",
+            "required": true,
+            "schema": {
+              "pattern": "^uis_[0-9a-z]{26}$",
               "type": "string"
             }
           }
@@ -2511,11 +3609,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Environment"
+                  "$ref": "#/components/schemas/UiSessionRevocation"
                 }
               }
             },
-            "description": "Environment deleted; compute and data are released after the response"
+            "description": "The session is revoked"
           },
           "400": {
             "content": {
@@ -2623,18 +3721,52 @@
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/v1/imports": {
       "get": {
-        "operationId": "getEnvironment",
+        "operationId": "listImports",
         "parameters": [
           {
-            "in": "path",
-            "name": "environmentId",
-            "required": true,
+            "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/ImportStatus"
+              },
+              "maxItems": 4,
+              "type": "array"
+            }
           }
         ],
         "responses": {
@@ -2642,11 +3774,23 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Environment"
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "$ref": "#/components/schemas/Import"
+                      },
+                      "type": "array"
+                    },
+                    "nextCursor": {
+                      "type": ["string", "null"]
+                    }
+                  },
+                  "required": ["data", "nextCursor"],
+                  "type": "object"
                 }
               }
             },
-            "description": "Environment"
+            "description": "The workspace's imports, newest first"
           },
           "400": {
             "content": {
@@ -2755,15 +3899,17 @@
           }
         ]
       },
-      "patch": {
-        "operationId": "updateEnvironment",
+      "post": {
+        "operationId": "createImport",
         "parameters": [
           {
-            "in": "path",
-            "name": "environmentId",
-            "required": true,
+            "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"
             }
           }
@@ -2773,19 +3919,24 @@
             "application/json": {
               "schema": {
                 "properties": {
-                  "labels": {
-                    "additionalProperties": {
-                      "maxLength": 256,
-                      "type": "string"
-                    },
-                    "type": "object"
+                  "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"
                   },
-                  "name": {
-                    "maxLength": 120,
-                    "minLength": 1,
-                    "type": ["string", "null"]
+                  "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"
               }
             }
@@ -2797,11 +3948,21 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Environment"
+                  "$ref": "#/components/schemas/CreatedImport"
                 }
               }
             },
-            "description": "Environment updated"
+            "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"
+                }
+              }
+            },
+            "description": "Import created; send its zip file to the upload URL, then complete it"
           },
           "400": {
             "content": {
@@ -2911,64 +4072,30 @@
         ]
       }
     },
-    "/v1/environments/{environmentId}/apps/{appName}/credentials": {
-      "post": {
-        "operationId": "createCredentials",
+    "/v1/imports/{importId}": {
+      "delete": {
+        "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"
-            }
           }
         ],
-        "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"
+                  "$ref": "#/components/schemas/Import"
                 }
               }
             },
-            "description": "How to call one app as one actor; the same tokens each time"
+            "description": "Import deleted, with its problems cleared and its zip file removed"
           },
           "400": {
             "content": {
@@ -3076,52 +4203,30 @@
             "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",
+      },
+      "get": {
+        "operationId": "getImport",
         "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"
-            }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/LaunchUiSession"
-              }
-            }
-          },
-          "required": true
-        },
         "responses": {
-          "201": {
+          "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/UiSessionLaunch"
+                  "$ref": "#/components/schemas/Import"
                 }
               }
             },
-            "description": "A pending session and its one-use grant"
+            "description": "Import"
           },
           "400": {
             "content": {
@@ -3231,37 +4336,18 @@
         ]
       }
     },
-    "/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",
+    "/v1/imports/{importId}/complete": {
+      "post": {
+        "operationId": "completeImport",
         "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": {
@@ -3269,11 +4355,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/UiSessionRevocation"
+                  "$ref": "#/components/schemas/Import"
                 }
               }
             },
-            "description": "The session is revoked"
+            "description": "The import after the check of its zip file: `ready`, or `invalid` with its problems"
           },
           "400": {
             "content": {
@@ -4556,19 +5642,7 @@
           "content": {
             "application/json": {
               "schema": {
-                "properties": {
-                  "environmentId": {
-                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
-                    "type": "string"
-                  },
-                  "name": {
-                    "maxLength": 120,
-                    "minLength": 1,
-                    "type": ["string", "null"]
-                  }
-                },
-                "required": ["environmentId"],
-                "type": "object"
+                "$ref": "#/components/schemas/CreateSnapshot"
               }
             }
           },