Management endpoint reference

This reference derives from the same OpenAPI contract that ships in @usestatemachines/sdk. It covers the management operations available to API-key callers. Member-only dashboard administration and vendor-native app APIs have separate contracts. Requests use a workspace API key in the Authorization: Bearer header. The management API reference explains authentication, workspace scope, and how accepted lifecycle requests become usable resources. The permissions guide describes which actions a key can perform. Each heading is an OpenAPI operation ID, followed by its HTTP method and route. Request bodies below are schemas, not example payloads. The schema’s required list identifies its declared mandatory fields. Service rules can add conditional requirements, such as choosing apps or a snapshot, or supplying both ends of a request time window. The task guides describe those rules and permission checks. References such as #/components/schemas/Environment point to the models in the downloadable contract. Nested references remain in their original form. Response tables show the statuses declared in the contract. The contract shares an error schema across routes. Most routes return only some of these errors. An HTTP success can mean a lifecycle operation was accepted rather than completed. Native app calls return their own responses instead of this management error format.

listApps

GET /v1/apps Parameters

Name	Location	Required	Schema
`limit`	query	No	`{"default":50,"maximum":100,"minimum":1,"type":"integer"}`
`cursor`	query	No	`{"maxLength":2048,"type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	The apps an environment can run	application/json	`{"properties":{"data":{"items":{"$ref":"#/components/schemas/App"},"type":"array"},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"type":"object"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

listVersions

GET /v1/apps/{appId}/versions Parameters

Name	Location	Required	Schema
`appId`	path	Yes	`{"pattern":"^[a-z][a-z0-9-]{1,39}$","type":"string"}`
`limit`	query	No	`{"default":50,"maximum":100,"minimum":1,"type":"integer"}`
`cursor`	query	No	`{"maxLength":2048,"type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	The app’s published versions, newest first	application/json	`{"properties":{"data":{"items":{"$ref":"#/components/schemas/Version"},"type":"array"},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"type":"object"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

listAuditEvents

GET /v1/audit-events Parameters

Name	Location	Required	Schema
`limit`	query	No	`{"default":50,"maximum":100,"minimum":1,"type":"integer"}`
`cursor`	query	No	`{"maxLength":2048,"type":"string"}`
`workspaceId`	query	No	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`environmentId`	query	No	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	A workspace’s or an environment’s audit events, newest first	application/json	`{"properties":{"data":{"items":{"$ref":"#/components/schemas/AuditEvent"},"type":"array"},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"type":"object"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

listEnvironments

GET /v1/environments Parameters

Name	Location	Required	Schema
`limit`	query	No	`{"default":50,"maximum":100,"minimum":1,"type":"integer"}`
`cursor`	query	No	`{"maxLength":2048,"type":"string"}`
`workspaceId`	query	No	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`status`	query	No	`{"items":{"$ref":"#/components/schemas/EnvironmentStatus"},"maxItems":5,"type":"array"}`
`snapshotId`	query	No	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`search`	query	No	`{"maxLength":120,"type":"string"}`
`label`	query	No	`{"items":{"pattern":"^[^=]+=.*$","type":"string"},"maxItems":32,"type":"array"}`

Responses

Status	Meaning	Content type	Schema
200	The workspace’s environments, newest first	application/json	`{"properties":{"data":{"items":{"$ref":"#/components/schemas/Environment"},"type":"array"},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"type":"object"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

createEnvironment

POST /v1/environments Parameters

Name	Location	Required	Schema
`idempotency-key`	header	No	`{"maxLength":128,"minLength":8,"pattern":"^[A-Za-z0-9._:-]+$","type":"string"}`

Request body Request body required: Yes. application/json

{
  "properties": {
    "apps": {
      "items": {
        "anyOf": [
          {
            "pattern": "^[a-z][a-z0-9-]{1,39}$",
            "type": "string"
          },
          {
            "additionalProperties": false,
            "properties": {
              "app": {
                "pattern": "^[a-z][a-z0-9-]{1,39}$",
                "type": "string"
              },
              "name": {
                "pattern": "^[a-z][a-z0-9-]{0,39}$",
                "type": "string"
              },
              "settings": {
                "additionalProperties": {},
                "type": "object"
              }
            },
            "required": [
              "app"
            ],
            "type": "object"
          }
        ]
      },
      "maxItems": 10,
      "minItems": 1,
      "type": "array"
    },
    "labels": {
      "additionalProperties": {
        "maxLength": 256,
        "type": "string"
      },
      "default": {},
      "type": "object"
    },
    "name": {
      "maxLength": 120,
      "minLength": 1,
      "type": [
        "string",
        "null"
      ]
    },
    "snapshotId": {
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
      "type": "string"
    },
    "timeLimitMinutes": {
      "maximum": 1440,
      "minimum": 1,
      "type": "integer"
    },
    "tokenInUrl": {
      "default": false,
      "type": "boolean"
    },
    "workspaceId": {
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
      "type": "string"
    }
  },
  "type": "object"
}

Responses

Status	Meaning	Content type	Schema
200	The environment an earlier request with this Idempotency-Key created, as it is now	application/json	`{"$ref":"#/components/schemas/Environment"}`
202	Environment starting	application/json	`{"$ref":"#/components/schemas/Environment"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

deleteEnvironment

DELETE /v1/environments/{environmentId} Parameters

Name	Location	Required	Schema
`environmentId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`idempotency-key`	header	No	`{"maxLength":128,"minLength":8,"pattern":"^[A-Za-z0-9._:-]+$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Environment deleted; compute and data are released after the response	application/json	`{"$ref":"#/components/schemas/Environment"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

getEnvironment

GET /v1/environments/{environmentId} Parameters

Name	Location	Required	Schema
`environmentId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Environment	application/json	`{"$ref":"#/components/schemas/Environment"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

updateEnvironment

PATCH /v1/environments/{environmentId} Parameters

Name	Location	Required	Schema
`environmentId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`

Request body Request body required: Yes. application/json

{
  "properties": {
    "labels": {
      "additionalProperties": {
        "maxLength": 256,
        "type": "string"
      },
      "type": "object"
    },
    "name": {
      "maxLength": 120,
      "minLength": 1,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "type": "object"
}

Responses

Status	Meaning	Content type	Schema
200	Environment updated	application/json	`{"$ref":"#/components/schemas/Environment"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

createCredentials

POST /v1/environments/{environmentId}/apps/{appName}/credentials Parameters

Name	Location	Required	Schema
`environmentId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`appName`	path	Yes	`{"pattern":"^[a-z][a-z0-9-]{0,39}$","type":"string"}`

Request body Request body required: No. application/json

{
  "properties": {
    "actorId": {
      "maxLength": 255,
      "minLength": 1,
      "type": "string"
    }
  },
  "type": "object"
}

Responses

Status	Meaning	Content type	Schema
200	How to call one app as one actor; the same tokens each time	application/json	`{"$ref":"#/components/schemas/Credentials"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

pauseEnvironment

POST /v1/environments/{environmentId}/pause Parameters

Name	Location	Required	Schema
`environmentId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`idempotency-key`	header	No	`{"maxLength":128,"minLength":8,"pattern":"^[A-Za-z0-9._:-]+$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Environment paused; the gateway refuses calls from now on	application/json	`{"$ref":"#/components/schemas/Environment"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

resumeEnvironment

POST /v1/environments/{environmentId}/resume Parameters

Name	Location	Required	Schema
`environmentId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`idempotency-key`	header	No	`{"maxLength":128,"minLength":8,"pattern":"^[A-Za-z0-9._:-]+$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Environment starting again	application/json	`{"$ref":"#/components/schemas/Environment"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

getMe

GET /v1/me Responses

Status	Meaning	Content type	Schema
200	The caller, its organization, permissions and limits	application/json	`{"$ref":"#/components/schemas/Me"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

listRequests

GET /v1/requests Parameters

Name	Location	Required	Schema
`limit`	query	No	`{"default":50,"maximum":100,"minimum":1,"type":"integer"}`
`cursor`	query	No	`{"maxLength":2048,"type":"string"}`
`environmentId`	query	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`app`	query	No	`{"pattern":"^[a-z][a-z0-9-]{0,39}$","type":"string"}`
`method`	query	No	`{"enum":["GET","HEAD","POST","PUT","PATCH","DELETE","OPTIONS","CONNECT","TRACE"],"type":"string"}`
`responseStatus`	query	No	`{"maximum":599,"minimum":100,"type":"integer"}`
`statusClass`	query	No	`{"enum":["2xx","3xx","4xx","5xx"],"type":"string"}`
`writesOnly`	query	No	`{"type":"boolean"}`
`search`	query	No	`{"maxLength":200,"pattern":"^[^\\0]*$","type":"string"}`
`from`	query	No	`{"format":"date-time","type":"string"}`
`to`	query	No	`{"format":"date-time","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Calls the gateway recorded for an environment, newest first; recording is best effort	application/json	`{"properties":{"data":{"items":{"$ref":"#/components/schemas/Request"},"type":"array"},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"type":"object"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

getRequestStats

GET /v1/requests/stats Parameters

Name	Location	Required	Schema
`environmentId`	query	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`app`	query	No	`{"pattern":"^[a-z][a-z0-9-]{0,39}$","type":"string"}`
`method`	query	No	`{"enum":["GET","HEAD","POST","PUT","PATCH","DELETE","OPTIONS","CONNECT","TRACE"],"type":"string"}`
`responseStatus`	query	No	`{"maximum":599,"minimum":100,"type":"integer"}`
`statusClass`	query	No	`{"enum":["2xx","3xx","4xx","5xx"],"type":"string"}`
`writesOnly`	query	No	`{"type":"boolean"}`
`search`	query	No	`{"maxLength":200,"pattern":"^[^\\0]*$","type":"string"}`
`from`	query	Yes	`{"format":"date-time","type":"string"}`
`to`	query	Yes	`{"format":"date-time","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Counts and latency of the recorded calls in a window	application/json	`{"$ref":"#/components/schemas/RequestStats"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

getRequest

GET /v1/requests/{requestId} Parameters

Name	Location	Required	Schema
`requestId`	path	Yes	`{"pattern":"^req_[0-9a-z]{16}$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	A recorded call with its headers and body previews	application/json	`{"$ref":"#/components/schemas/RequestDetail"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

getRequestBody

GET /v1/requests/{requestId}/body/{direction} Parameters

Name	Location	Required	Schema
`requestId`	path	Yes	`{"pattern":"^req_[0-9a-z]{16}$","type":"string"}`
`direction`	path	Yes	`{"enum":["request","response"],"type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	The recorded body as an attachment	application/octet-stream	`{"format":"binary","type":"string"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

listSnapshots

GET /v1/snapshots Parameters

Name	Location	Required	Schema
`limit`	query	No	`{"default":50,"maximum":100,"minimum":1,"type":"integer"}`
`cursor`	query	No	`{"maxLength":2048,"type":"string"}`
`workspaceId`	query	No	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`environmentId`	query	No	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`
`status`	query	No	`{"items":{"$ref":"#/components/schemas/SnapshotStatus"},"maxItems":4,"type":"array"}`

Responses

Status	Meaning	Content type	Schema
200	The workspace’s snapshots, newest first	application/json	`{"properties":{"data":{"items":{"$ref":"#/components/schemas/Snapshot"},"type":"array"},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"type":"object"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

createSnapshot

POST /v1/snapshots Parameters

Name	Location	Required	Schema
`idempotency-key`	header	No	`{"maxLength":128,"minLength":8,"pattern":"^[A-Za-z0-9._:-]+$","type":"string"}`

Request body Request body required: Yes. application/json

{
  "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"
}

Responses

Status	Meaning	Content type	Schema
200	The snapshot an earlier request with this Idempotency-Key created, as it is now	application/json	`{"$ref":"#/components/schemas/Snapshot"}`
202	Snapshot created; its status is `saving` until the data is saved	application/json	`{"$ref":"#/components/schemas/Snapshot"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

deleteSnapshot

DELETE /v1/snapshots/{snapshotId} Parameters

Name	Location	Required	Schema
`snapshotId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Snapshot deleted; its files are removed afterwards	application/json	`{"$ref":"#/components/schemas/Snapshot"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

getSnapshot

GET /v1/snapshots/{snapshotId} Parameters

Name	Location	Required	Schema
`snapshotId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Snapshot	application/json	`{"$ref":"#/components/schemas/Snapshot"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

updateSnapshot

PATCH /v1/snapshots/{snapshotId} Parameters

Name	Location	Required	Schema
`snapshotId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`

Request body Request body required: Yes. application/json

{
  "properties": {
    "name": {
      "maxLength": 120,
      "minLength": 1,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "name"
  ],
  "type": "object"
}

Responses

Status	Meaning	Content type	Schema
200	Snapshot renamed	application/json	`{"$ref":"#/components/schemas/Snapshot"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

listWorkspaces

GET /v1/workspaces Parameters

Name	Location	Required	Schema
`limit`	query	No	`{"default":50,"maximum":100,"minimum":1,"type":"integer"}`
`cursor`	query	No	`{"maxLength":2048,"type":"string"}`
`archived`	query	No	`{"default":"false","enum":["true","false"],"type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	The organization’s workspaces; an API key sees its own	application/json	`{"properties":{"data":{"items":{"$ref":"#/components/schemas/Workspace"},"type":"array"},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"type":"object"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

getWorkspace

GET /v1/workspaces/{workspaceId} Parameters

Name	Location	Required	Schema
`workspaceId`	path	Yes	`{"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","type":"string"}`

Responses

Status	Meaning	Content type	Schema
200	Workspace	application/json	`{"$ref":"#/components/schemas/Workspace"}`
400	Invalid request	application/json	`{"$ref":"#/components/schemas/Error"}`
401	Authentication required	application/json	`{"$ref":"#/components/schemas/Error"}`
403	Permission denied	application/json	`{"$ref":"#/components/schemas/Error"}`
404	Resource not found	application/json	`{"$ref":"#/components/schemas/Error"}`
409	Conflicting request	application/json	`{"$ref":"#/components/schemas/Error"}`
413	Request body too large	application/json	`{"$ref":"#/components/schemas/Error"}`
422	Version unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`
429	Limit reached	application/json	`{"$ref":"#/components/schemas/Error"}`
500	Unexpected failure	application/json	`{"$ref":"#/components/schemas/Error"}`
503	Dependency unavailable	application/json	`{"$ref":"#/components/schemas/Error"}`

​listApps

​listVersions

​listAuditEvents

​listEnvironments

​createEnvironment

​deleteEnvironment

​getEnvironment

​updateEnvironment

​createCredentials

​pauseEnvironment

​resumeEnvironment

​getMe

​listRequests

​getRequestStats

​getRequest

​getRequestBody

​listSnapshots

​createSnapshot

​deleteSnapshot

​getSnapshot

​updateSnapshot

​listWorkspaces

​getWorkspace

listApps

listVersions

listAuditEvents

listEnvironments

createEnvironment

deleteEnvironment

getEnvironment

updateEnvironment

createCredentials

pauseEnvironment

resumeEnvironment

getMe

listRequests

getRequestStats

getRequest

getRequestBody

listSnapshots

createSnapshot

deleteSnapshot

getSnapshot

updateSnapshot

listWorkspaces

getWorkspace