@usestatemachines/sdk 0.4.0 → 0.5.0

package/openapi.json

@@ -573,20 +573,6 @@
             "format": "date-time",
             "type": ["string", "null"]
           },
-          "forkedAt": {
-            "default": null,
-            "properties": {
-              "generation": {
-                "minimum": 1,
-                "type": "integer"
-              },
-              "lsn": {
-                "type": "string"
-              }
-            },
-            "required": ["generation", "lsn"],
-            "type": ["object", "null"]
-          },
           "id": {
             "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
             "type": "string"
@@ -645,250 +631,197 @@
         ],
         "type": "object"
       },
-      "EnvironmentExchange": {
+      "EnvironmentLifetime": {
         "properties": {
-          "actor": {
-            "properties": {
-              "credentialId": {
-                "type": ["string", "null"]
-              },
-              "vendorUserId": {
-                "type": ["string", "null"]
-              }
-            },
-            "required": ["vendorUserId", "credentialId"],
-            "type": ["object", "null"]
-          },
-          "appKey": {
-            "pattern": "^[a-z][a-z0-9-]{0,39}$",
-            "type": "string"
-          },
-          "bodies": {
-            "properties": {
-              "request": {
-                "$ref": "#/components/schemas/HistoryBody"
-              },
-              "response": {
-                "$ref": "#/components/schemas/HistoryBody"
-              }
-            },
-            "required": ["request", "response"],
-            "type": ["object", "null"]
+          "defaultMinutes": {
+            "type": "integer"
           },
-          "channel": {
-            "enum": [
-              "api",
-              "ui",
-              "reactor",
-              "timer",
-              "inbound-webhook",
-              "bootstrap",
-              "restore",
-              null
-            ],
+          "maximumMinutes": {
+            "type": "integer"
+          }
+        },
+        "required": ["defaultMinutes", "maximumMinutes"],
+        "type": "object"
+      },
+      "EnvironmentRequest": {
+        "properties": {
+          "appInstanceId": {
             "type": ["string", "null"]
           },
-          "eventIds": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "appKey": {
+            "type": "string"
           },
-          "exchangeId": {
-            "maxLength": 128,
-            "minLength": 1,
+          "completedAt": {
+            "format": "date-time",
             "type": "string"
           },
-          "objectCount": {
+          "durationMs": {
+            "minimum": 0,
             "type": "integer"
           },
-          "objects": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "environmentId": {
+            "type": "string"
           },
-          "observedAt": {
-            "format": "date-time",
+          "errorCode": {
+            "type": ["string", "null"]
+          },
+          "id": {
+            "format": "uuid",
             "type": "string"
           },
-          "operation": {
-            "properties": {
-              "id": {
-                "type": ["string", "null"]
-              },
-              "method": {
-                "type": "string"
-              },
-              "profile": {
-                "type": "string"
-              },
-              "route": {
-                "type": "string"
-              },
-              "target": {
-                "type": "string"
-              }
-            },
-            "required": ["id", "profile", "method", "route", "target"],
-            "type": ["object", "null"]
+          "method": {
+            "type": "string"
           },
           "outcome": {
-            "properties": {
-              "refusal": {
-                "enum": [
-                  "auth",
-                  "not-served",
-                  "unsupported",
-                  "limit",
-                  "validation",
-                  "conflict",
-                  null
-                ],
-                "type": ["string", "null"]
-              },
-              "status": {
-                "type": "integer"
-              },
-              "vendorErrorCode": {
-                "type": ["string", "null"]
-              }
-            },
-            "required": ["status", "vendorErrorCode", "refusal"],
-            "type": ["object", "null"]
+            "enum": ["replica_response", "gateway_error"],
+            "type": "string"
           },
-          "position": {
-            "$ref": "#/components/schemas/HistoryPosition"
+          "path": {
+            "type": "string"
           },
-          "state": {
-            "enum": ["recorded", "unknown"],
+          "query": {
             "type": "string"
           },
-          "timing": {
-            "properties": {
-              "clockSource": {
-                "enum": ["gateway", "runner"],
-                "type": "string"
-              },
-              "databaseMs": {
-                "type": "number"
-              },
-              "environmentTime": {
-                "type": "string"
-              },
-              "handlerMs": {
-                "type": "number"
-              },
-              "leaseWaitMs": {
-                "type": "number"
-              },
-              "responseReadyAt": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "clockSource",
-              "leaseWaitMs",
-              "handlerMs",
-              "databaseMs",
-              "responseReadyAt",
-              "environmentTime"
-            ],
-            "type": ["object", "null"]
+          "receivedAt": {
+            "format": "date-time",
+            "type": "string"
           },
-          "trace": {
-            "properties": {
-              "parentSpanId": {
-                "type": ["string", "null"]
-              },
-              "spanId": {
-                "type": "string"
-              },
-              "traceId": {
-                "type": "string"
-              }
-            },
-            "required": ["traceId", "parentSpanId", "spanId"],
-            "type": ["object", "null"]
+          "requestBytes": {
+            "type": ["integer", "null"]
           },
-          "transactions": {
-            "items": {
-              "$ref": "#/components/schemas/HistoryTransaction"
-            },
-            "type": "array"
+          "responseBytes": {
+            "type": ["integer", "null"]
+          },
+          "status": {
+            "type": "integer"
           }
         },
         "required": [
-          "exchangeId",
+          "id",
+          "environmentId",
           "appKey",
-          "state",
-          "observedAt",
-          "position",
-          "channel",
-          "operation",
+          "appInstanceId",
+          "method",
+          "path",
+          "query",
+          "receivedAt",
+          "completedAt",
+          "durationMs",
+          "status",
           "outcome",
-          "actor",
-          "trace",
-          "timing",
-          "bodies",
-          "objects",
-          "objectCount",
-          "eventIds",
-          "transactions"
+          "errorCode",
+          "requestBytes",
+          "responseBytes"
         ],
         "type": "object"
       },
-      "EnvironmentLifetime": {
-        "properties": {
-          "defaultMinutes": {
-            "type": "integer"
+      "EnvironmentRequestDetail": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EnvironmentRequest"
           },
-          "maximumMinutes": {
-            "type": "integer"
+          {
+            "properties": {
+              "requestBody": {
+                "$ref": "#/components/schemas/RequestPayloadPreview"
+              },
+              "requestHeaders": {
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "type": "object"
+              },
+              "responseBody": {
+                "$ref": "#/components/schemas/RequestPayloadPreview"
+              },
+              "responseHeaders": {
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "type": "object"
+              }
+            },
+            "required": [
+              "requestHeaders",
+              "responseHeaders",
+              "requestBody",
+              "responseBody"
+            ],
+            "type": "object"
           }
-        },
-        "required": ["defaultMinutes", "maximumMinutes"],
-        "type": "object"
+        ]
       },
-      "EnvironmentPosition": {
+      "EnvironmentRequestStats": {
         "properties": {
-          "apps": {
+          "buckets": {
             "items": {
               "properties": {
-                "appInstanceId": {
-                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
-                  "type": "string"
+                "clientError": {
+                  "minimum": 0,
+                  "type": "integer"
                 },
-                "key": {
-                  "pattern": "^[a-z][a-z0-9-]{0,39}$",
+                "from": {
+                  "format": "date-time",
                   "type": "string"
                 },
-                "position": {
-                  "properties": {
-                    "generation": {
-                      "minimum": 1,
-                      "type": "integer"
-                    },
-                    "lsn": {
-                      "pattern": "^[0-9A-F]{1,8}\\/[0-9A-F]{1,8}$",
-                      "type": "string"
-                    }
-                  },
-                  "required": ["generation", "lsn"],
-                  "type": ["object", "null"]
+                "serverError": {
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "success": {
+                  "minimum": 0,
+                  "type": "integer"
                 }
               },
-              "required": ["key", "appInstanceId", "position"],
+              "required": ["from", "success", "clientError", "serverError"],
               "type": "object"
             },
             "type": "array"
           },
-          "environmentId": {
-            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+          "clientErrorCount": {
+            "minimum": 0,
+            "type": "integer"
+          },
+          "count": {
+            "minimum": 0,
+            "type": "integer"
+          },
+          "from": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "p50Ms": {
+            "minimum": 0,
+            "type": ["number", "null"]
+          },
+          "p95Ms": {
+            "minimum": 0,
+            "type": ["number", "null"]
+          },
+          "serverErrorCount": {
+            "minimum": 0,
+            "type": "integer"
+          },
+          "successCount": {
+            "minimum": 0,
+            "type": "integer"
+          },
+          "to": {
+            "format": "date-time",
             "type": "string"
           }
         },
-        "required": ["environmentId", "apps"],
+        "required": [
+          "from",
+          "to",
+          "count",
+          "successCount",
+          "clientErrorCount",
+          "serverErrorCount",
+          "p50Ms",
+          "p95Ms",
+          "buckets"
+        ],
         "type": "object"
       },
       "EnvironmentSnapshot": {
@@ -995,7 +928,6 @@
                   "not-snapshottable",
                   "not-suspended",
                   "organization-required",
-                  "position-unavailable",
                   "release-gone",
                   "release-lifecycle",
                   "release-unavailable",
@@ -1097,188 +1029,6 @@
         "required": ["data", "nextCursor"],
         "type": "object"
       },
-      "HistoryBody": {
-        "properties": {
-          "blob": {
-            "properties": {
-              "bytes": {
-                "type": "integer"
-              },
-              "sha256": {
-                "type": "string"
-              }
-            },
-            "required": ["sha256", "bytes"],
-            "type": ["object", "null"]
-          },
-          "coverage": {
-            "enum": ["complete", "redacted", "truncated", "omitted"],
-            "type": "string"
-          },
-          "inline": {
-            "type": ["string", "null"]
-          }
-        },
-        "required": ["coverage", "inline", "blob"],
-        "type": "object"
-      },
-      "HistoryCause": {
-        "oneOf": [
-          {
-            "properties": {
-              "exchangeId": {
-                "maxLength": 128,
-                "minLength": 1,
-                "type": "string"
-              },
-              "kind": {
-                "enum": ["exchange"],
-                "type": "string"
-              }
-            },
-            "required": ["kind", "exchangeId"],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "depth": {
-                "type": "integer"
-              },
-              "eventId": {
-                "type": "string"
-              },
-              "kind": {
-                "enum": ["reactor"],
-                "type": "string"
-              },
-              "reactor": {
-                "type": "string"
-              },
-              "rootExchangeId": {
-                "maxLength": 128,
-                "minLength": 1,
-                "type": ["string", "null"]
-              }
-            },
-            "required": [
-              "kind",
-              "reactor",
-              "eventId",
-              "rootExchangeId",
-              "depth"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "depth": {
-                "type": "integer"
-              },
-              "kind": {
-                "enum": ["timer"],
-                "type": "string"
-              },
-              "rootExchangeId": {
-                "maxLength": 128,
-                "minLength": 1,
-                "type": ["string", "null"]
-              },
-              "timerId": {
-                "type": "string"
-              }
-            },
-            "required": ["kind", "timerId", "rootExchangeId", "depth"],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "fromGeneration": {
-                "type": "integer"
-              },
-              "kind": {
-                "enum": ["restore"],
-                "type": "string"
-              },
-              "lsn": {
-                "type": "string"
-              }
-            },
-            "required": ["kind", "fromGeneration", "lsn"],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "kind": {
-                "enum": ["bootstrap"],
-                "type": "string"
-              }
-            },
-            "required": ["kind"],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "HistoryPosition": {
-        "properties": {
-          "generation": {
-            "minimum": 1,
-            "type": "integer"
-          },
-          "lsn": {
-            "pattern": "^[0-9A-F]{1,8}\\/[0-9A-F]{1,8}$",
-            "type": "string"
-          },
-          "until": {
-            "pattern": "^[0-9A-F]{1,8}\\/[0-9A-F]{1,8}$",
-            "type": ["string", "null"]
-          }
-        },
-        "required": ["generation", "lsn", "until"],
-        "type": "object"
-      },
-      "HistoryTransaction": {
-        "properties": {
-          "cause": {
-            "$ref": "#/components/schemas/HistoryCause"
-          },
-          "changes": {
-            "type": "integer"
-          },
-          "committedAt": {
-            "format": "date-time",
-            "type": "string"
-          },
-          "generation": {
-            "type": "integer"
-          },
-          "lsn": {
-            "pattern": "^[0-9A-F]{1,8}\\/[0-9A-F]{1,8}$",
-            "type": "string"
-          },
-          "tables": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "xid": {
-            "type": "integer"
-          }
-        },
-        "required": [
-          "generation",
-          "xid",
-          "lsn",
-          "committedAt",
-          "cause",
-          "tables",
-          "changes"
-        ],
-        "type": "object"
-      },
       "Release": {
         "properties": {
           "actors": {
@@ -1350,6 +1100,43 @@
         "required": ["id", "name", "summary"],
         "type": "object"
       },
+      "RequestPayloadPreview": {
+        "properties": {
+          "bytes": {
+            "type": ["integer", "null"]
+          },
+          "contentType": {
+            "type": ["string", "null"]
+          },
+          "coverage": {
+            "enum": ["captured", "redacted", "omitted"],
+            "type": "string"
+          },
+          "encoding": {
+            "enum": ["utf8", "binary"],
+            "type": "string"
+          },
+          "preview": {
+            "type": ["string", "null"]
+          },
+          "previewTruncated": {
+            "type": "boolean"
+          },
+          "reason": {
+            "type": ["string", "null"]
+          }
+        },
+        "required": [
+          "coverage",
+          "reason",
+          "contentType",
+          "bytes",
+          "encoding",
+          "preview",
+          "previewTruncated"
+        ],
+        "type": "object"
+      },
       "Workspace": {
         "properties": {
           "archivedAt": {
@@ -2324,17 +2111,172 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "properties": {
-                    "data": {
-                      "$ref": "#/components/schemas/ConnectionSecret"
-                    }
-                  },
-                  "required": ["data"],
-                  "type": "object"
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/ConnectionSecret"
+                    }
+                  },
+                  "required": ["data"],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Live credentials for one actor; recorded as an event"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Invalid request"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Permission denied"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Resource not found"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Conflicting request or version"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Request body too large"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Unsupported configuration"
+          },
+          "429": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Admission limit reached"
+          },
+          "500": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Unexpected failure"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Dependency unavailable"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "x-state-credentials": ["user", "api_key"]
+      }
+    },
+    "/v1/environments/{environmentId}/events": {
+      "get": {
+        "operationId": "listEnvironmentEvents",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "environmentId",
+            "required": true,
+            "schema": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+              "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": 64,
+              "pattern": "^\\d+$",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EventPage"
                 }
               }
             },
-            "description": "Live credentials for one actor; recorded as an event"
+            "description": "The environment's timeline, oldest first"
           },
           "400": {
             "content": {
@@ -2445,9 +2387,9 @@
         "x-state-credentials": ["user", "api_key"]
       }
     },
-    "/v1/environments/{environmentId}/events": {
+    "/v1/environments/{environmentId}/requests": {
       "get": {
-        "operationId": "listEnvironmentEvents",
+        "operationId": "listEnvironmentRequests",
         "parameters": [
           {
             "in": "path",
@@ -2474,8 +2416,91 @@
             "name": "cursor",
             "required": false,
             "schema": {
-              "maxLength": 64,
-              "pattern": "^\\d+$",
+              "maxLength": 2048,
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "appKey",
+            "required": false,
+            "schema": {
+              "pattern": "^[a-z][a-z0-9-]{0,39}$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "status",
+            "required": false,
+            "schema": {
+              "maximum": 599,
+              "minimum": 100,
+              "type": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "statusClass",
+            "required": false,
+            "schema": {
+              "enum": ["2xx", "3xx", "4xx", "5xx"],
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "method",
+            "required": false,
+            "schema": {
+              "enum": [
+                "GET",
+                "HEAD",
+                "POST",
+                "PUT",
+                "PATCH",
+                "DELETE",
+                "OPTIONS",
+                "CONNECT",
+                "TRACE"
+              ],
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "search",
+            "required": false,
+            "schema": {
+              "maxLength": 200,
+              "pattern": "^[^\\0]*$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "writesOnly",
+            "required": false,
+            "schema": {
+              "enum": ["true", "false"],
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "from",
+            "required": false,
+            "schema": {
+              "format": "date-time",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "to",
+            "required": false,
+            "schema": {
+              "format": "date-time",
               "type": "string"
             }
           }
@@ -2485,11 +2510,23 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/EventPage"
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "$ref": "#/components/schemas/EnvironmentRequest"
+                      },
+                      "type": "array"
+                    },
+                    "nextCursor": {
+                      "type": ["string", "null"]
+                    }
+                  },
+                  "required": ["data", "nextCursor"],
+                  "type": "object"
                 }
               }
             },
-            "description": "The environment's timeline, oldest first"
+            "description": "Best-effort recorded replica requests, newest first"
           },
           "400": {
             "content": {
@@ -2600,9 +2637,9 @@
         "x-state-credentials": ["user", "api_key"]
       }
     },
-    "/v1/environments/{environmentId}/history": {
+    "/v1/environments/{environmentId}/requests/stats": {
       "get": {
-        "operationId": "listEnvironmentHistory",
+        "operationId": "getEnvironmentRequestStats",
         "parameters": [
           {
             "in": "path",
@@ -2615,21 +2652,85 @@
           },
           {
             "in": "query",
-            "name": "limit",
+            "name": "appKey",
             "required": false,
             "schema": {
-              "default": 50,
-              "maximum": 100,
-              "minimum": 1,
+              "pattern": "^[a-z][a-z0-9-]{0,39}$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "status",
+            "required": false,
+            "schema": {
+              "maximum": 599,
+              "minimum": 100,
               "type": "integer"
             }
           },
           {
             "in": "query",
-            "name": "cursor",
+            "name": "statusClass",
             "required": false,
             "schema": {
-              "maxLength": 2048,
+              "enum": ["2xx", "3xx", "4xx", "5xx"],
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "method",
+            "required": false,
+            "schema": {
+              "enum": [
+                "GET",
+                "HEAD",
+                "POST",
+                "PUT",
+                "PATCH",
+                "DELETE",
+                "OPTIONS",
+                "CONNECT",
+                "TRACE"
+              ],
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "search",
+            "required": false,
+            "schema": {
+              "maxLength": 200,
+              "pattern": "^[^\\0]*$",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "writesOnly",
+            "required": false,
+            "schema": {
+              "enum": ["true", "false"],
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "from",
+            "required": true,
+            "schema": {
+              "format": "date-time",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "to",
+            "required": true,
+            "schema": {
+              "format": "date-time",
               "type": "string"
             }
           }
@@ -2641,21 +2742,15 @@
                 "schema": {
                   "properties": {
                     "data": {
-                      "items": {
-                        "$ref": "#/components/schemas/EnvironmentExchange"
-                      },
-                      "type": "array"
-                    },
-                    "nextCursor": {
-                      "type": ["string", "null"]
+                      "$ref": "#/components/schemas/EnvironmentRequestStats"
                     }
                   },
-                  "required": ["data", "nextCursor"],
+                  "required": ["data"],
                   "type": "object"
                 }
               }
             },
-            "description": "The environment's exchanges in gateway order, each with its transactions and events"
+            "description": "Recorded request statistics across the selected time window"
           },
           "400": {
             "content": {
@@ -2766,9 +2861,9 @@
         "x-state-credentials": ["user", "api_key"]
       }
     },
-    "/v1/environments/{environmentId}/history/position": {
+    "/v1/environments/{environmentId}/requests/{requestId}": {
       "get": {
-        "operationId": "getEnvironmentPosition",
+        "operationId": "getEnvironmentRequest",
         "parameters": [
           {
             "in": "path",
@@ -2778,6 +2873,15 @@
               "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
               "type": "string"
             }
+          },
+          {
+            "in": "path",
+            "name": "requestId",
+            "required": true,
+            "schema": {
+              "format": "uuid",
+              "type": "string"
+            }
           }
         ],
         "responses": {
@@ -2787,7 +2891,7 @@
                 "schema": {
                   "properties": {
                     "data": {
-                      "$ref": "#/components/schemas/EnvironmentPosition"
+                      "$ref": "#/components/schemas/EnvironmentRequestDetail"
                     }
                   },
                   "required": ["data"],
@@ -2795,7 +2899,7 @@
                 }
               }
             },
-            "description": "Each app's current head position, as a fork from it would start"
+            "description": "Recorded request with bounded payload previews"
           },
           "400": {
             "content": {
@@ -2906,9 +3010,9 @@
         "x-state-credentials": ["user", "api_key"]
       }
     },
-    "/v1/environments/{environmentId}/history/{exchangeId}": {
+    "/v1/environments/{environmentId}/requests/{requestId}/payload/{direction}": {
       "get": {
-        "operationId": "getEnvironmentExchange",
+        "operationId": "getEnvironmentRequestPayload",
         "parameters": [
           {
             "in": "path",
@@ -2921,11 +3025,19 @@
           },
           {
             "in": "path",
-            "name": "exchangeId",
+            "name": "requestId",
             "required": true,
             "schema": {
-              "maxLength": 128,
-              "minLength": 1,
+              "format": "uuid",
+              "type": "string"
+            }
+          },
+          {
+            "in": "path",
+            "name": "direction",
+            "required": true,
+            "schema": {
+              "enum": ["request", "response"],
               "type": "string"
             }
           }
@@ -2933,19 +3045,14 @@
         "responses": {
           "200": {
             "content": {
-              "application/json": {
+              "application/octet-stream": {
                 "schema": {
-                  "properties": {
-                    "data": {
-                      "$ref": "#/components/schemas/EnvironmentExchange"
-                    }
-                  },
-                  "required": ["data"],
-                  "type": "object"
+                  "format": "binary",
+                  "type": "string"
                 }
               }
             },
-            "description": "One exchange of the environment, with the position a fork after it starts from"
+            "description": "Recorded payload as a safe attachment"
           },
           "400": {
             "content": {
@@ -3068,6 +3175,17 @@
               "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": {
@@ -3208,6 +3326,17 @@
               "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": {
@@ -3348,6 +3477,17 @@
               "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": {
@@ -4361,86 +4501,6 @@
                     },
                     "required": ["from"],
                     "type": "object"
-                  },
-                  {
-                    "additionalProperties": false,
-                    "properties": {
-                      "from": {
-                        "additionalProperties": false,
-                        "properties": {
-                          "at": {
-                            "anyOf": [
-                              {
-                                "additionalProperties": false,
-                                "properties": {
-                                  "position": {
-                                    "additionalProperties": false,
-                                    "properties": {
-                                      "generation": {
-                                        "minimum": 1,
-                                        "type": "integer"
-                                      },
-                                      "lsn": {
-                                        "pattern": "^[0-9A-F]{1,8}\\/[0-9A-F]{1,8}$",
-                                        "type": "string"
-                                      }
-                                    },
-                                    "required": ["generation", "lsn"],
-                                    "type": "object"
-                                  }
-                                },
-                                "required": ["position"],
-                                "type": "object"
-                              },
-                              {
-                                "additionalProperties": false,
-                                "properties": {
-                                  "exchangeId": {
-                                    "maxLength": 128,
-                                    "minLength": 1,
-                                    "type": "string"
-                                  }
-                                },
-                                "required": ["exchangeId"],
-                                "type": "object"
-                              }
-                            ]
-                          },
-                          "environment": {
-                            "maxLength": 128,
-                            "minLength": 1,
-                            "type": "string"
-                          }
-                        },
-                        "required": ["environment", "at"],
-                        "type": "object"
-                      },
-                      "labels": {
-                        "additionalProperties": {
-                          "maxLength": 256,
-                          "type": "string"
-                        },
-                        "default": {},
-                        "type": "object"
-                      },
-                      "lifetimeMinutes": {
-                        "maximum": 1440,
-                        "minimum": 1,
-                        "type": "integer"
-                      },
-                      "name": {
-                        "maxLength": 120,
-                        "minLength": 1,
-                        "type": "string"
-                      },
-                      "version": {
-                        "default": 1,
-                        "enum": [1],
-                        "type": "number"
-                      }
-                    },
-                    "required": ["from"],
-                    "type": "object"
                   }
                 ]
               }