> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/rest-api-reference/workspaces.md).

# Workspaces

## Introspect the current credential

> Returns what the presented credential is: userId, organisationId, workspaceId (the workspace the credential is pinned to, or null for org-wide), scopes, authType (apiKey | oauth), and rateLimit (requests per minute; null for OAuth connections, which share the fixed OAuth limit). Needs no scopes — any authenticated caller may ask who it is. Use it to fail fast on missing scopes before starting a workflow.

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Workspaces"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"schemas":{"CredentialEnvelope":{"type":"object","properties":{"data":{"type":"object","properties":{"userId":{"type":"string"},"organisationId":{"type":"string"},"workspaceId":{"type":["string","null"],"description":"The workspace the credential is pinned to, or null for org-wide"},"scopes":{"type":"array","items":{"type":"string"}},"authType":{"type":"string","enum":["apiKey","oauth"]},"rateLimit":{"type":["number","null"],"description":"Requests per minute; null for OAuth, which shares the fixed OAuth limit"}},"required":["userId","organisationId","workspaceId","scopes","authType","rateLimit"]}},"required":["data"]}},"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/me":{"get":{"operationId":"get-api-v1-me","summary":"Introspect the current credential","description":"Returns what the presented credential is: userId, organisationId, workspaceId (the workspace the credential is pinned to, or null for org-wide), scopes, authType (apiKey | oauth), and rateLimit (requests per minute; null for OAuth connections, which share the fixed OAuth limit). Needs no scopes — any authenticated caller may ask who it is. Use it to fail fast on missing scopes before starting a workflow.","tags":["Workspaces"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialEnvelope"}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```

## List workspaces

> Lists workspaces the user can access within the organisation. Filtered by resource access: only workspaces where the user has at least read permission (owner, accessRights, or org role) are returned. Not paginated.

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Workspaces"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"schemas":{"WorkspaceListEnvelope":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Workspace"}}},"required":["data"]},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"organisationId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"},"isOrgLibrary":{"type":"boolean"}},"required":["organisationId","name","createdAt"]}},"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/workspaces":{"get":{"operationId":"get-api-v1-workspaces","summary":"List workspaces","description":"Lists workspaces the user can access within the organisation. Filtered by resource access: only workspaces where the user has at least read permission (owner, accessRights, or org role) are returned. Not paginated.","tags":["Workspaces"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceListEnvelope"}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```

## Create workspace

> Creates a new workspace with name and optional description. The caller becomes the owner. Workspace is scoped to the organisation from the auth context.

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Workspaces"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"schemas":{"CreateWorkspaceSchema":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"]},"WorkspaceEnvelope":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workspace"}},"required":["data"]},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"organisationId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"},"isOrgLibrary":{"type":"boolean"}},"required":["organisationId","name","createdAt"]}},"responses":{"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/workspaces":{"post":{"operationId":"post-api-v1-workspaces","summary":"Create workspace","description":"Creates a new workspace with name and optional description. The caller becomes the owner. Workspace is scoped to the organisation from the auth context.","tags":["Workspaces"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceSchema"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceEnvelope"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```

## Get workspace

> Returns the workspace by id. wsId is resolved from the request URL; workspace must belong to the organisation and user must have access (enforced by middleware).

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Workspaces"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"schemas":{"WorkspaceEnvelope":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workspace"}},"required":["data"]},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"organisationId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"},"isOrgLibrary":{"type":"boolean"}},"required":["organisationId","name","createdAt"]}},"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/workspaces/{wsId}":{"get":{"operationId":"get-api-v1-workspaces-{wsId}","summary":"Get workspace","description":"Returns the workspace by id. wsId is resolved from the request URL; workspace must belong to the organisation and user must have access (enforced by middleware).","tags":["Workspaces"],"parameters":[{"name":"wsId","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: wsId"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceEnvelope"}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```

## Delete workspace

> Permanently deletes the workspace. Requires sources:delete scope and full permission. Does not necessarily delete data in the data-service; workspace-scoped resources may remain until explicitly cleaned.

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Workspaces"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/workspaces/{wsId}":{"delete":{"operationId":"delete-api-v1-workspaces-{wsId}","summary":"Delete workspace","description":"Permanently deletes the workspace. Requires sources:delete scope and full permission. Does not necessarily delete data in the data-service; workspace-scoped resources may remain until explicitly cleaned.","tags":["Workspaces"],"parameters":[{"name":"wsId","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: wsId"}],"responses":{"204":{"description":"No Content"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```

## Update workspace

> Updates workspace name and/or description. Only these fields are writable. Used for display and organisation.

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Workspaces"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"schemas":{"UpdateWorkspaceSchema":{"type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false},"WorkspaceEnvelope":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workspace"}},"required":["data"]},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"organisationId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"},"isOrgLibrary":{"type":"boolean"}},"required":["organisationId","name","createdAt"]}},"responses":{"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/workspaces/{wsId}":{"patch":{"operationId":"patch-api-v1-workspaces-{wsId}","summary":"Update workspace","description":"Updates workspace name and/or description. Only these fields are writable. Used for display and organisation.","tags":["Workspaces"],"parameters":[{"name":"wsId","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: wsId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceSchema"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceEnvelope"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```