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/testto 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
datasourcepayload 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
typeis 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
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The unique identifier of the workspace.
Body
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.
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 with roles in format {"users": [{"id": <user_id>, "role": "owner|editor|viewer"}, ...], "groups": [{"id": <group_id>, "role": "owner|editor|viewer"}, ...]}. Role defaults to viewer if not specified. REPLACES all existing members.
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.
Response
Workspace updated successfully
V3 Response serializer for company workspace creation and retrieval.
owner- ownereditor- editorviewer- viewer- `` -
owner, editor, viewer