> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usestatemachines.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Management endpoint reference

> Routes, parameters, request schemas, and responses generated from the public API contract.

This reference derives from the same [OpenAPI contract](/openapi.json) 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](/sdk-api/management-api) explains authentication, workspace scope, and how accepted lifecycle requests become usable resources. The [permissions guide](/environments/access) 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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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"}` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.