--- title: Rename, pin, order, archive or edit an in-house Space sheet canonical_url: https://orchestor.io/docs/en/space/rest-api/endpoint-reference/sheets/patch-update-space-sheet markdown_url: https://orchestor.io/docs/en/space/rest-api/endpoint-reference/sheets/patch-update-space-sheet.md --- # Rename, pin, order, archive or edit an in-house Space sheet ```http PATCH /v1/space/sheets/{sheet_id} ``` Server: https://api.orchestor.io Operation ID: `updateSpaceSheet` ## Authentication ```json [ [ { "key": "session_cookie", "type": "apiKey", "description": "Browser session established by signing in to the web app. The server checks your workspace membership and permissions. Supply X-Workspace-ID for workspace-scoped operations. For server-to-server requests, use an API key when the operation supports it.", "name": "wos-session", "in": "cookie", "scopes": [] } ], [ { "key": "bearer_api_key", "type": "http", "description": "Authenticate with a workspace-scoped API key using Authorization: Bearer . Supported key prefixes are sk_live_ and sk_test_. The key determines the workspace and allowed permissions; supplying X-Workspace-ID does not grant access to another workspace. Create and manage API keys in workspace settings. Never put a key in a URL.", "scheme": "bearer", "scopes": [] } ] ] ``` ## Parameters ```json [ { "name": "X-Workspace-ID", "in": "header", "required": false, "description": "Workspace to access. With a workspace-scoped API key, the server derives this value from the key, so the header is optional. If supplied, it must match the credential workspace or the request returns 403 workspace_mismatch. For interactive session requests, supply this header to select a workspace where you are a member. A project ID cannot be used as a workspace ID.", "schema": { "type": "string", "example": "wks_abc123" } }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "pattern": "^sht_[a-f0-9]{24}$", "type": "string" } } ] ``` ## Request body ```json { "required": true, "content": [ { "contentType": "application/json", "schema": { "name": "UpdateSpaceSheet", "type": "object", "required": [ "updated_at" ], "properties": { "archived": { "type": "boolean" }, "pinned": { "type": "boolean" }, "sort_position": { "minimum": 0, "maximum": 2147483647, "type": "integer" }, "tabs": { "minItems": 1, "type": "array", "items": { "type": "object", "required": [ "id", "title", "rows" ], "properties": { "columns": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "type" ], "properties": { "color": { "type": "string" }, "currencyCode": { "type": "string" }, "description": { "type": "string" }, "hidden": { "type": "boolean" }, "id": { "minLength": 1, "maxLength": 256, "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "pinned": { "type": "boolean" }, "title": { "type": "string" }, "type": { "type": "string", "enumValues": [ "text", "number", "currency", "url", "domain", "date", "timestamp", "email", "image", "checkbox", "select", "multi-select" ] }, "width": { "minimum": 104, "type": "integer" } }, "additionalProperties": false } }, "deleted": { "type": "boolean" }, "filter": { "type": "object", "required": [ "columnId", "value" ], "properties": { "columnId": { "minLength": 1, "maxLength": 256, "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false }, "hidden": { "type": "boolean" }, "id": { "minLength": 1, "maxLength": 256, "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "minLength": 1, "maxLength": 256, "type": "string" }, "parentId": { "minLength": 1, "maxLength": 256, "type": "string" }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } } }, "additionalProperties": false } }, "sort": { "type": "object", "required": [ "columnId", "direction" ], "properties": { "columnId": { "minLength": 1, "maxLength": 256, "type": "string" }, "direction": { "type": "string", "enumValues": [ "asc", "desc" ] } }, "additionalProperties": false }, "title": { "minLength": 1, "maxLength": 100, "type": "string" } }, "additionalProperties": false } }, "title": { "minLength": 1, "maxLength": 100, "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } ] } ``` ## Responses ### 200 ```json { "statusCode": "200", "description": "Updated sheet", "headers": [], "content": [ { "contentType": "application/json", "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "name": "SpaceSheet", "type": "object", "required": [ "id", "workspace_id", "title", "pinned", "sort_position", "archived", "tabs", "created_at", "updated_at", "deleted_at" ], "properties": { "archived": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "nullable": true, "format": "date-time" }, "folder_id": { "type": "string", "nullable": true, "default": null }, "id": { "pattern": "^sht_[a-f0-9]{24}$", "type": "string" }, "pinned": { "type": "boolean" }, "sort_position": { "minimum": 0, "maximum": 2147483647, "type": "integer" }, "tabs": { "minItems": 1, "type": "array", "items": { "type": "object", "required": [ "id", "title", "rows" ], "properties": { "columns": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "type" ], "properties": { "color": { "type": "string" }, "currencyCode": { "type": "string" }, "description": { "type": "string" }, "hidden": { "type": "boolean" }, "id": { "minLength": 1, "maxLength": 256, "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "pinned": { "type": "boolean" }, "title": { "type": "string" }, "type": { "type": "string", "enumValues": [ "text", "number", "currency", "url", "domain", "date", "timestamp", "email", "image", "checkbox", "select", "multi-select" ] }, "width": { "minimum": 104, "type": "integer" } }, "additionalProperties": false } }, "deleted": { "type": "boolean" }, "filter": { "type": "object", "required": [ "columnId", "value" ], "properties": { "columnId": { "minLength": 1, "maxLength": 256, "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false }, "hidden": { "type": "boolean" }, "id": { "minLength": 1, "maxLength": 256, "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "minLength": 1, "maxLength": 256, "type": "string" }, "parentId": { "minLength": 1, "maxLength": 256, "type": "string" }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } } }, "additionalProperties": false } }, "sort": { "type": "object", "required": [ "columnId", "direction" ], "properties": { "columnId": { "minLength": 1, "maxLength": 256, "type": "string" }, "direction": { "type": "string", "enumValues": [ "asc", "desc" ] } }, "additionalProperties": false }, "title": { "minLength": 1, "maxLength": 100, "type": "string" } }, "additionalProperties": false } }, "title": { "minLength": 1, "maxLength": 100, "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "string" } } } } } } ] } ``` ### 400 ```json { "statusCode": "400", "description": "Invalid request parameters or body. Not retryable — fix the request before retrying.\nCommon error codes: `invalid_parameter` (wrong type or out of range),\n`missing_required_field` (a required body field is absent),\n`invalid_json` (request body is not valid JSON),\n`validation_error` (field fails schema validation, e.g., URL format or enum value).\n", "headers": [], "content": [ { "contentType": "application/json", "schema": { "name": "ApiError", "type": "object", "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Failure category, code and human-readable explanation, with optional field or validation context.", "required": [ "type", "code", "message", "doc_url" ], "properties": { "type": { "type": "string", "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.", "enumValues": [ "invalid_request_error", "authentication_error", "permission_error", "entitlement_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.", "example": "Request validation failed" }, "feature": { "type": "string", "description": "Entitlement capability required for a 402 denial.", "example": "included_engines" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan or grant recovery destination supplied with a 402 denial." }, "param": { "type": "string", "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.", "example": "limit" }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.", "example": "https://docs.orchestor.io/errors/validation_error" }, "details": { "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.", "anyOf": [ { "type": "array", "description": "Validation issues. A request can have multiple issues, including more than one for the same field.", "example": [ { "path": "items.0.name", "message": "Invalid input", "code": "invalid_type" } ], "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.", "example": "items.0.name" }, "message": { "type": "string", "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.", "example": "Invalid input" }, "code": { "type": "string", "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.", "example": "invalid_type" } } } }, { "type": "object", "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.", "additionalProperties": true } ] } } } } }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "limit must be between 1 and 200", "param": "limit", "doc_url": "https://docs.orchestor.io/api-reference/errors#invalid-request" } } } ] } ``` ### 401 ```json { "statusCode": "401", "description": "Authentication required or credentials invalid. Not retryable without new credentials.\nCommon error codes: `invalid_api_key` (key is missing, malformed, or revoked),\n`expired_session` (session cookie expired — re-authenticate via the web app).\n", "headers": [], "content": [ { "contentType": "application/json", "schema": { "name": "ApiError", "type": "object", "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Failure category, code and human-readable explanation, with optional field or validation context.", "required": [ "type", "code", "message", "doc_url" ], "properties": { "type": { "type": "string", "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.", "enumValues": [ "invalid_request_error", "authentication_error", "permission_error", "entitlement_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.", "example": "Request validation failed" }, "feature": { "type": "string", "description": "Entitlement capability required for a 402 denial.", "example": "included_engines" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan or grant recovery destination supplied with a 402 denial." }, "param": { "type": "string", "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.", "example": "limit" }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.", "example": "https://docs.orchestor.io/errors/validation_error" }, "details": { "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.", "anyOf": [ { "type": "array", "description": "Validation issues. A request can have multiple issues, including more than one for the same field.", "example": [ { "path": "items.0.name", "message": "Invalid input", "code": "invalid_type" } ], "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.", "example": "items.0.name" }, "message": { "type": "string", "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.", "example": "Invalid input" }, "code": { "type": "string", "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.", "example": "invalid_type" } } } }, { "type": "object", "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.", "additionalProperties": true } ] } } } } }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided", "doc_url": "https://docs.orchestor.io/api-reference/errors#authentication" } } } ] } ``` ### 409 ```json { "statusCode": "409", "description": "Sheet changed or is unavailable. Reload before writing.", "headers": [], "content": [] } ``` --- [Documentation index](https://orchestor.io/docs/llms.txt)