> ## Documentation Index > Fetch the complete documentation index at: https://developers.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a workspace > ⚠️ **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 ## OpenAPI ````yaml /api-reference/api-console.yaml patch /api/v3/workspaces/{id} openapi: 3.1.0 info: title: LightOn API version: 3.12.0 (v1) description: >- LightOn gives you an API to search, parse, and ingest documents at scale. Build knowledge-retrieval pipelines without managing vector databases or OCR models. servers: - url: https://api.lighton.ai security: [] tags: - name: Ask description: >- Retrieval-augmented generation: search your indexed corpus and generate an LLM answer grounded in the retrieved passages. Supports streaming (SSE) and synchronous modes. - name: Search description: >- Hybrid vector + text retrieval over your indexed corpus. Returns ranked passages with provenance (file, page range, workspace). Optional reranking and vision mode. - name: Files description: Upload, list, fetch, and delete documents indexed in your workspaces. - name: Facets description: >- Organise documents with hierarchical content types and custom attributes per file. Start from starter templates or build your own classification schema from scratch. - name: Tags description: >- Manage flat, company-wide labels used to scope search and group content across workspaces. - name: Workspaces description: >- Create and manage workspaces — the access-controlled containers your documents live in. - name: Parse description: >- Convert documents into structured Markdown — PDFs, images, Office files, and HTML. Synchronous endpoint capped at 20 MB / 15 pages. - name: Extract description: >- Pull typed fields out of documents using a JSON Schema you provide. Sync mode for small documents (≤20 MB / 15 pages); async mode for larger jobs (≤100 MB / 1000 pages) with polling on a job ID. - name: API Keys description: >- Provision and revoke API keys used to authenticate against the Console API. - name: Budget description: >- Manage your organization's monthly spend budget and alert thresholds. Set a hard cap that blocks API requests when reached, and configure email notifications at custom spend percentages. paths: /api/v3/workspaces/{id}: patch: tags: - Workspaces summary: Update a workspace description: >- ⚠️ **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 operationId: api_v3_workspaces_partial_update parameters: - in: path name: id schema: type: integer description: The unique identifier of the workspace. required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateWorkspaceV3Request' examples: RenameWorkspace: value: name: Updated Workspace Name description: Updated description summary: Rename workspace RestoreASoft-deletedWorkspace: value: deleted_at: null summary: Restore a soft-deleted workspace RestoreUnderANewName(resolvesANameCollision): value: deleted_at: null name: Project Apollo (restored) summary: Restore under a new name (resolves a name collision) RestoreAndUpdateTheDescription: value: deleted_at: null description: Reinstated after review summary: Restore and update the description ConvertToServiceNowSyncedWorkspace: value: datasource: type: servicenow name: My ServiceNow KB credentials: instance_url: https://acme.service-now.com username: admin password: s3cr3t filter_criteria: doc_type: knowledge summary: Convert to ServiceNow synced workspace ConvertToGoogleDriveSyncedWorkspace: value: datasource: type: googledrive name: Meet Recordings credentials: service_account_file: '{"type":"service_account","project_id":"my-project",...}' filter_criteria: folder_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs recursive: true summary: Convert to Google Drive synced workspace ConvertToSharePointSyncedWorkspace: value: datasource: type: sharepoint name: Engineering Docs credentials: client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx client_secret: s3cr3t tenant_id: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy site_name: EngineeringSite filter_criteria: folder_path: /Shared Documents/Engineering recursive: true summary: Convert to SharePoint synced workspace ConvertToWebScrapperSyncedWorkspace: value: datasource: type: webscrapper name: Public Docs credentials: {} filter_criteria: start_url: https://docs.example.com summary: Convert to WebScrapper synced workspace application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateWorkspaceV3Request' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateWorkspaceV3Request' responses: '200': content: application/json: schema: $ref: '#/components/schemas/StandardWorkspaceV3DetailsResponse' description: Workspace updated successfully '400': description: >- Bad Request - Invalid input parameters (empty name, name too long, unsupported fields, etc.) '401': description: Unauthenticated - Missing or invalid API key/session cookie '403': description: >- Unauthorized - User must be workspace owner and workspace must be custom type '404': description: Not Found - Workspace does not exist or belongs to another company '409': description: >- Conflict - Datasource edit rejected because the workspace has already completed at least one successful sync (config locked), or a sync is currently in flight. security: - bearerAuth: [] - {} components: schemas: PatchedUpdateWorkspaceV3Request: type: object properties: name: type: string description: >- 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: type: string description: >- 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: description: >- Members with roles in format {"users": [{"id": , "role": "owner|editor|viewer"}, ...], "groups": [{"id": , "role": "owner|editor|viewer"}, ...]}. Role defaults to viewer if not specified. REPLACES all existing members. datasource: allOf: - $ref: '#/components/schemas/_DatasourceConversionRequest' description: >- Datasource configuration to convert this workspace into a read-only synced workspace. Workspace OWNER (or a role granting workspace edit/delete) only. Cannot be undone. StandardWorkspaceV3DetailsResponse: type: object description: V3 Response serializer for company workspace creation and retrieval. properties: id: type: integer name: type: string workspace_type: type: string document_upload_method: type: string description: type: string created_at: type: string format: date-time updated_at: type: string format: date-time files_count: type: integer user_role: readOnly: true oneOf: - $ref: '#/components/schemas/UserRoleEnum' - $ref: '#/components/schemas/BlankEnum' used_storage: type: number format: double summaries: type: array items: $ref: '#/components/schemas/WorkspaceSummary' readOnly: true sync: oneOf: - $ref: '#/components/schemas/WorkspaceSync' - type: 'null' readOnly: true scoped_api_keys: type: array items: $ref: '#/components/schemas/WorkspaceScopedAPIKey' readOnly: true required: - created_at - description - document_upload_method - files_count - id - name - scoped_api_keys - summaries - sync - updated_at - used_storage - user_role - workspace_type _DatasourceConversionRequest: type: object description: >- Nested serializer for documentation of the datasource conversion payload. properties: type: allOf: - $ref: '#/components/schemas/_DatasourceConversionRequestTypeEnum' description: |- Datasource provider. * `servicenow` - servicenow * `googledrive` - googledrive * `sharepoint` - sharepoint * `webscrapper` - webscrapper name: type: string description: Display name for the datasource. credentials: type: object additionalProperties: {} description: >- 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: type: object additionalProperties: {} description: >- 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). required: - name - type UserRoleEnum: enum: - owner - editor - viewer type: string description: |- * `owner` - owner * `editor` - editor * `viewer` - viewer * `` - BlankEnum: enum: - '' WorkspaceSummary: type: object properties: language: type: string summary: type: string required: - language - summary WorkspaceSync: type: object properties: datasource_type: type: string source_name: type: string last_status: type: string updated_at: type: - string - 'null' format: date-time failed_files_count: type: integer next_import_date: type: - string - 'null' format: date-time editable: type: boolean name: type: string instance_url: type: - string - 'null' tenant_id: type: string site_name: type: string client_id: type: string filter_criteria: {} required: - client_id - datasource_type - editable - failed_files_count - filter_criteria - instance_url - last_status - name - next_import_date - site_name - source_name - tenant_id - updated_at WorkspaceScopedAPIKey: type: object description: >- An API key that can access a single workspace, seen from the workspace side. Covers both keys explicitly scoped to the workspace (`scope_type="workspace"`, each carrying its per-workspace role) and the requesting user's globally-scoped keys (`scope_type="global"`), which implicitly reach every workspace in the company with the user's own role here. Reads flat dicts built by `WorkspaceScopedAPIKeysMixin`, which lists explicitly-scoped keys first. properties: id: type: string name: type: string prefix: type: string role: type: string created_at: type: string format: date-time created_by: type: string scope_type: $ref: '#/components/schemas/ScopeTypeEnum' required: - created_at - created_by - id - name - prefix - role - scope_type _DatasourceConversionRequestTypeEnum: enum: - servicenow - googledrive - sharepoint - webscrapper type: string description: |- * `servicenow` - servicenow * `googledrive` - googledrive * `sharepoint` - sharepoint * `webscrapper` - webscrapper ScopeTypeEnum: enum: - workspace - global type: string description: |- * `workspace` - workspace * `global` - global securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````