# List file versions (/api-reference/files/listFileVersions)

`GET /api/v2/files/{fileId}/versions`

## Description
List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits, and repeated workflow writes by one author, fold into a version under ten minutes old and written in the last five. Renames and moves are not versions. Retention removes older versions by age and plan but keeps the newest ten, so numbers can have gaps.

OAuth scope: `api:read`.

## Parameters

- **fileId** (path) (required) — `string`: File identifier.

- **workspaceId** (query) (required) — `string`: Workspace that owns the file.

- **sortBy** (query) — `string`: Field used to sort the result.

- **sortOrder** (query) — `string`: Sort direction.

- **limit** (query) — `integer`: Maximum versions to return per page. Must be a whole number from 1 to 100. Defaults to 50.

- **cursor** (query) — `string`: Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.

## Responses

### 200 — A page of file versions.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fileId": {
            "type": "string",
            "description": "File this version belongs to."
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Version number, increasing by one per recorded version. Numbers are never reused, so a gap means an older version was removed by retention or deleted.",
            "examples": [
              3
            ]
          },
          "isCurrent": {
            "type": "boolean",
            "description": "Whether this version holds the current content of the file."
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Size in bytes of the stored content of this version."
          },
          "contentType": {
            "type": "string",
            "description": "MIME type of the stored content of this version."
          },
          "source": {
            "type": "string",
            "enum": [
              "upload",
              "user",
              "api",
              "copilot",
              "workflow",
              "collab",
              "revert",
              "unknown"
            ],
            "description": "What wrote this version: `upload` (the original upload), `user` (a save in the Sim editor), `api` (an API, CLI, or MCP write), `copilot` (Sim, the agent), `workflow` (a workflow run), `collab` (collaborative editing), `revert` (a revert to an earlier version), or `unknown` (content written before version history existed, or by a writer with no source of its own)."
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "User identifier."
                },
                "email": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "email",
                      "pattern": "^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Current email address of the user, or null when the account no longer exists."
                }
              },
              "required": [
                "id",
                "email"
              ],
              "additionalProperties": false
            },
            "description": "Users who wrote this version, in order of first contribution. Empty for actorless writers such as workspace API keys. A collaborative version lists every editor in its window."
          },
          "restoredFromVersion": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1,
                "maximum": 2147483647
              },
              {
                "type": "null"
              }
            ],
            "description": "For a `revert` version, the version whose content it restored; otherwise null."
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp when this content became current.",
            "format": "date-time",
            "examples": [
              "2026-01-15T10:30:00Z"
            ]
          },
          "updatedAt": {
            "type": "string",
            "description": "ISO 8601 timestamp of the last write folded into this version. Equals `createdAt` unless edits were coalesced into it.",
            "format": "date-time",
            "examples": [
              "2026-01-15T10:38:00Z"
            ]
          },
          "supersededAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp when a newer version replaced this one, or null for the current version. Retention ages versions from this time.",
            "format": "date-time",
            "examples": [
              "2026-01-16T09:00:00Z"
            ]
          }
        },
        "required": [
          "fileId",
          "version",
          "isCurrent",
          "size",
          "contentType",
          "source",
          "authors",
          "restoredFromVersion",
          "createdAt",
          "updatedAt",
          "supersededAt"
        ],
        "additionalProperties": false,
        "title": "File version",
        "description": "One recorded version of the content of a workspace file."
      },
      "description": "Items in the current page."
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
    }
  },
  "required": [
    "data",
    "nextCursor"
  ],
  "additionalProperties": false,
  "title": "File version list response",
  "description": "A cursor-paginated page of file versions.",
  "examples": [
    {
      "data": [
        {
          "fileId": "wf_V1StGXR8z5jdHi6BmyT91",
          "version": 3,
          "isCurrent": true,
          "size": 1024,
          "contentType": "text/csv",
          "source": "api",
          "authors": [
            {
              "id": "usr_4kJ9mN2pQ7rS",
              "email": "jane@example.com"
            }
          ],
          "restoredFromVersion": null,
          "createdAt": "2026-01-15T10:30:00Z",
          "updatedAt": "2026-01-15T10:30:00Z",
          "supersededAt": null
        }
      ],
      "nextCursor": null
    }
  ]
}
```

### 400 — The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 401 — The API credential is missing or invalid.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 403 — The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 404 — The requested resource was not found.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 429 — The caller exceeded the request rate limit.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 500 — An unexpected server error occurred.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 503 — A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```