Retrieve a workspace
Retrieve a workspace
Retrieve a workspace by ID. Returns workspace details.
Access: Instance-level users (Sys Admin, Account Manager, Admin, DPO Admin) can retrieve any workspace. Company-level users (Company Admin, Company DPO) can retrieve workspaces in their company. Regular users can retrieve workspaces where they are members.
Member Visibility: Instance-level users and company-level users see all members. Workspace OWNER sees members. EDITOR and VIEWER do not see members.
Sync status: For synced workspaces, the response includes a sync block with datasource_type, source_name, last_status, updated_at, failed_files_count, and next_import_date. Use this field for polling the sync state.
Returns 403 for both non-existent and unauthorized workspaces.
Authorization
bearerAuth Console session token (Authorization: Bearer <session>) or product API key (Authorization: Bearer <api-key> or x-api-key). Session tokens are validated via Better Auth get-session; API keys against the shared database.
In: header
Path Parameters
The unique identifier of the workspace.
Query Parameters
When true, allow retrieving a soft-deleted workspace.
falseHeader Parameters
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/workspaces/0"{ "id": 0, "name": "string", "workspace_type": "string", "document_upload_method": "string", "description": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "files_count": 0, "user_role": "owner", "used_storage": 0, "summaries": [ { "language": "string", "summary": "string" } ], "sync": { "datasource_type": "string", "source_name": "string", "last_status": "string", "updated_at": "2019-08-24T14:15:22Z", "failed_files_count": 0, "next_import_date": "2019-08-24T14:15:22Z", "editable": true, "name": "string", "instance_url": "string", "tenant_id": "string", "site_name": "string", "client_id": "string", "filter_criteria": null }, "scoped_api_keys": [ { "id": "string", "name": "string", "prefix": "string", "role": "string", "created_at": "2019-08-24T14:15:22Z", "created_by": "string", "scope_type": "workspace" } ]}Test datasource credentials POST
Test datasource credentials Test datasource credentials without persisting anything. Validates that the provided credentials can connect to the external source. Returns 200 if the connection succeeds, 400 otherwise. No datasource or import is created. Use this before `PATCH /api/v1/workspaces/{id}` with a `datasource` payload to surface connection errors before committing the conversion. **Access:** any authenticated user. Credentials per type: - **googledrive**: `service_account_file` (JSON string of the service account key file) - **sharepoint**: `client_id`, `client_secret`, `tenant_id`, `site_id` (optional), `site_name` (optional) - **servicenow**: `instance_url`, `username`, `password` - **webscrapper**: no credentials required Filter criteria per type: - **googledrive**: `folder_id` (required), `recursive` (optional) - **sharepoint**: `folder_path` (required), `recursive` (optional) - **servicenow**: `doc_type` (required, e.g. `knowledge`) - **webscrapper**: `start_url` (required)
Update a workspace PATCH
Update a workspace 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/v1/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