---
title: "Update a workspace"
method: PATCH
path: "/api/v3/workspaces/{id}"
tags: ["Workspaces"]
---

# Update a workspace

`PATCH /api/v3/workspaces/{id}`

⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

Partially update a given workspace.

**Standard update (workspace OWNER only):**
- **name** (string, optional): Desired workspace name (max 100 characters, cannot be empty)
- **description** (string, optional): Desired workspace description. Send empty string or null to clear.

**Convert to a synced workspace** (workspace OWNER or a role granting workspace edit/delete):
- **datasource** (object): Datasource configuration used to populate the workspace. Credentials are validated against the external source before persistence; use `POST /api/v3/workspaces/{id}/datasource/test` to validate them without committing.
- The target workspace must be empty (no documents) and not already synced.

**Edit an existing synced workspace's datasource:**
- If the workspace is already synced and no successful sync has happened yet, sending a `datasource` payload edits the datasource in place (full credential re-entry required, name/filter_criteria updated, next sync re-triggered).
- After the first successful sync, the field is rejected with **409 Conflict** — ingested data integrity is preserved by locking the config. Delete and recreate the workspace to change its configuration.
- The datasource `type` is immutable on edit (changing it returns 400).
- Edits are also rejected with 409 while a sync is currently in flight (WAITING/PROCESSING).
- The current edit-availability is exposed in the response under `sync.editable` (boolean).

**Restrictions:**
- Only SHARED workspaces can be updated (PERSONAL workspaces cannot be modified)
- Conversion is one-way: a synced workspace cannot be reverted to manual via the API

## Path parameters

- `id` integer, required

## Request body

- PatchedUpdateWorkspaceV3Request
  - `name` string — Workspace name (max 100 characters, cannot be empty). When sent together with `deleted_at: null` (restore), the workspace is restored under this name — used to resolve a collision when the original name was re-taken by a live workspace during the grace period.
  - `description` string — Workspace description. Send empty string or null to clear. May be sent together with `deleted_at: null` (restore) to set the description as part of the restore request; a name collision rejects the whole request before the description is applied. `members` and `datasource` are not accepted on a restore request — restore first, then PATCH them.
  - `members` unknown
  - `datasource` DatasourceConversionRequest — Nested serializer for documentation of the datasource conversion payload.
    - `type` 'servicenow' | 'googledrive' | 'sharepoint' | 'webscrapper', required — * `servicenow` - servicenow * `googledrive` - googledrive * `sharepoint` - sharepoint * `webscrapper` - webscrapper
    - `name` string, required — Display name for the datasource.
    - `credentials` object — Provider credentials. googledrive: service_account_file (JSON string). sharepoint: client_id, client_secret, tenant_id, site_id (opt), site_name (opt), instance_url (opt). servicenow: instance_url, username, password. webscrapper: none required.
    - `filter_criteria` object — Provider filter criteria. googledrive: folder_id (required), recursive (opt). sharepoint: folder_path (required), recursive (opt). servicenow: doc_type (required, e.g. 'knowledge'). webscrapper: start_url (required).

## Response `200`

Workspace updated successfully

- StandardWorkspaceV3DetailsResponse — V3 Response serializer for company workspace creation and retrieval.
  - `id` integer, required
  - `name` string, required
  - `workspace_type` string, required
  - `document_upload_method` string, required
  - `description` string, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `files_count` integer, required
  - `user_role` union, required
    - 'owner' | 'editor' | 'viewer' — * `owner` - owner * `editor` - editor * `viewer` - viewer * `` -
    - ''
  - `used_storage` number, double, required
  - `summaries` WorkspaceSummary[], required
    - `language` string, required
    - `summary` string, required
  - `sync` WorkspaceSync, required
    - `datasource_type` string, required
    - `source_name` string, required
    - `last_status` string, required
    - `updated_at` string, date-time, nullable, required
    - `failed_files_count` integer, required
    - `next_import_date` string, date-time, nullable, required
    - `editable` boolean, required
    - `name` string, required
    - `instance_url` string, nullable, required
    - `tenant_id` string, required
    - `site_name` string, required
    - `client_id` string, required
    - `filter_criteria` unknown, required
  - `scoped_api_keys` WorkspaceScopedAPIKey[], required
    - `id` string, required
    - `name` string, required
    - `prefix` string, required
    - `role` string, required
    - `created_at` string, date-time, required
    - `created_by` string, required
    - `scope_type` 'workspace' | 'global', required — * `workspace` - workspace * `global` - global

## Other responses

- `400` — Bad Request - Invalid input parameters (empty name, name too long, unsupported fields, etc.)
- `401` — Unauthenticated - Missing or invalid API key/session cookie
- `403` — Unauthorized - User must be workspace owner and workspace must be custom type
- `404` — Not Found - Workspace does not exist or belongs to another company
- `409` — Conflict - Datasource edit rejected because the workspace has already completed at least one successful sync (config locked), or a sync is currently in flight.

---

[API](https://skmtc.dev/lighton/apis/lighton-api.md) · [All operations](https://skmtc.dev/lighton/apis/lighton-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lighton/lighton-api/revisions/86c57e94ef15/schema)